Added Feedback flow to return information about suggestions for password changes

src/Zxcvbn/Classes/FeedbackUtilities.php

@@ -0,0 +1,48 @@
+<?php
+
+    namespace Zxcvbn\Classes;
+
+    use Zxcvbn\Interfaces\MatchInterface;
+    use Zxcvbn\Objects\Feedback;
+
+    class FeedbackUtilities
+    {
+        /**
+         * @param int $score
+         * @param MatchInterface[] $sequence
+         * @return Feedback
+         */
+        public function getFeedback(int $score, array $sequence): Feedback
+        {
+            // starting feedback
+            if (count($sequence) === 0)
+            {
+                return new Feedback('', [
+                    "Use a few words, avoid common phrases",
+                    "No need for symbols, digits, or uppercase letters",
+                ]);
+            }
+
+            // no feedback if score is good or great.
+            if ($score > 2)
+            {
+                return new Feedback();
+            }
+
+            // tie feedback to the longest match for longer sequences
+            $longestMatch = $sequence[0];
+            foreach (array_slice($sequence, 1) as $match)
+            {
+                if (mb_strlen($match->token) > mb_strlen($longestMatch->token))
+                {
+                    $longestMatch = $match;
+                }
+            }
+
+            /** @var Feedback $feedback */
+            $feedback = $longestMatch->getFeedback(count($sequence) === 1);
+            $extraFeedback = 'Add another word or two. Uncommon words are better.';
+            array_unshift($feedback->Suggestions, $extraFeedback);
+            return $feedback;
+        }
+    }

src/Zxcvbn/Classes/Matchers/DateMatch.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Zxcvbn\Classes\Matchers;
+
+class DateMatch
+{
+
+}

src/Zxcvbn/Objects/Feedback.php

@@ -0,0 +1,62 @@
+<?php
+
+    /** @noinspection PhpMissingFieldTypeInspection */
+
+    namespace Zxcvbn\Objects;
+
+    class Feedback
+    {
+        /**
+         * The main warning of the feedback
+         *
+         * @var string
+         */
+        public $Warning;
+
+        /**
+         * Potential suggestions to correct the warning
+         *
+         * @var string[]
+         */
+        public $Suggestions;
+
+        /**
+         * @param string $warning
+         * @param array $Suggestions
+         */
+        public function __construct(string $warning=(string)null, array $Suggestions=[])
+        {
+            $this->Warning = $warning;
+            $this->Suggestions = $Suggestions;
+        }
+
+        /**
+         * @return array
+         * @noinspection PhpUnused
+         */
+        public function toArray(): array
+        {
+            return [
+                'warning' => $this->Warning,
+                'suggestions' => $this->Suggestions
+            ];
+        }
+
+        /**
+         * @param array $data
+         * @return Feedback
+         * @noinspection PhpUnused
+         */
+        public static function fromArray(array $data): Feedback
+        {
+            $FeedbackObject = new Feedback();
+
+            if(isset($data['warning']))
+                $FeedbackObject->Warning = $data['warning'];
+
+            if(isset($data['suggestions']))
+                $FeedbackObject->Suggestions = $data['suggestions'];
+
+            return $FeedbackObject;
+        }
+    }