Added possibility to dump backtrace

src/Backtrace.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Coduo\PHPMatcher;
+
+use Coduo\PHPMatcher\Value\SingleLineString;
+use Coduo\ToString\StringConverter;
+
+final class Backtrace
+{
+    private $trace;
+
+    public function __construct()
+    {
+        $this->trace = [];
+    }
+
+    public function matcherCanMatch(string $name, $value, bool $result) : void
+    {
+        $this->trace[] = \sprintf(
+            '#%d Matcher %s %s match pattern "%s"',
+            $this->entriesCount(),
+            $name,
+            $result ? 'can' : 'can\'t',
+            new SingleLineString((string) new StringConverter($value))
+        );
+    }
+
+    public function matcherEntrance(string $name, $value, $pattern) : void
+    {
+        $this->trace[] = \sprintf(
+            '#%d Matcher %s matching value "%s" with "%s" pattern',
+            $this->entriesCount(),
+            $name,
+            new SingleLineString((string) new StringConverter($value)),
+            new SingleLineString((string) new StringConverter($pattern))
+        );
+    }
+
+    public function matcherSucceed(string $name, $value, $pattern) : void
+    {
+        $this->trace[] = \sprintf(
+            '#%d Matcher %s successfully matched value "%s" with "%s" pattern',
+            $this->entriesCount(),
+            $name,
+            new SingleLineString((string) new StringConverter($value)),
+            new SingleLineString((string) new StringConverter($pattern))
+        );
+    }
+
+    public function matcherFailed(string $name, $value, $pattern, string $error) : void
+    {
+        $this->trace[] = \sprintf(
+            '#%d Matcher %s failed to match value "%s" with "%s" pattern',
+            $this->entriesCount(),
+            $name,
+            new SingleLineString((string) new StringConverter($value)),
+            new SingleLineString((string) new StringConverter($pattern))
+        );
+
+        $this->trace[] = \sprintf(
+            '#%d Matcher %s error: %s',
+            $this->entriesCount(),
+            $name,
+            new SingleLineString($error)
+        );
+    }
+
+    public function __toString() : string
+    {
+        return \implode("\n", $this->trace);
+    }
+
+    public function raw() : array
+    {
+        return $this->trace;
+    }
+
+    private function entriesCount(): int
+    {
+        return \count($this->trace) + 1;
+    }
+}

src/Factory.php

@@ -6,5 +6,5 @@
 
 interface Factory
 {
-    public function createMatcher() : Matcher;
+    public function createMatcher(Backtrace $backtrace = null) : Matcher;
 }

src/Factory/MatcherFactory.php

@@ -4,22 +4,25 @@
 
 namespace Coduo\PHPMatcher\Factory;
 
+use Coduo\PHPMatcher\Backtrace;
 use Coduo\PHPMatcher\Factory;
 use Coduo\PHPMatcher\Lexer;
 use Coduo\PHPMatcher\Matcher;
 use Coduo\PHPMatcher\Parser;
 
 final class MatcherFactory implements Factory
 {
-    public function createMatcher() : Matcher
+    public function createMatcher(Backtrace $backtrace = null) : Matcher
     {
-        return new Matcher($this->buildMatchers($this->buildParser()));
+        $matcherBacktrace = $backtrace ? $backtrace : new Backtrace();
+
+        return new Matcher($this->buildMatchers($this->buildParser(), $matcherBacktrace), $matcherBacktrace);
     }
 
-    protected function buildMatchers(Parser $parser) : Matcher\ChainMatcher
+    protected function buildMatchers(Parser $parser, Backtrace $backtrace) : Matcher\ChainMatcher
     {
-        $scalarMatchers = $this->buildScalarMatchers($parser);
-        $arrayMatcher = $this->buildArrayMatcher($scalarMatchers, $parser);
+        $scalarMatchers = $this->buildScalarMatchers($parser, $backtrace);
+        $arrayMatcher = $this->buildArrayMatcher($scalarMatchers, $parser, $backtrace);
 
         // Matchers are registered in order of matching
         // 1) all scalars
@@ -28,48 +31,61 @@ protected function buildMatchers(Parser $parser) : Matcher\ChainMatcher
         // 4) or "||"
         // 5) full text
 
-        $chainMatcher = new Matcher\ChainMatcher([
-            $scalarMatchers,
-            new Matcher\JsonMatcher($arrayMatcher),
-            new Matcher\XmlMatcher($arrayMatcher),
-            $arrayMatcher,
-            new Matcher\OrMatcher($scalarMatchers),
-            new Matcher\TextMatcher($scalarMatchers, $parser),
-        ]);
+        $chainMatcher = new Matcher\ChainMatcher(
+            'all',
+            $backtrace,
+            [
+                $scalarMatchers,
+                new Matcher\JsonMatcher($arrayMatcher, $backtrace),
+                new Matcher\XmlMatcher($arrayMatcher, $backtrace),
+                $arrayMatcher,
+                new Matcher\OrMatcher($backtrace, $scalarMatchers),
+                new Matcher\TextMatcher($scalarMatchers, $backtrace, $parser),
+            ]
+        );
 
         return $chainMatcher;
     }
 
-    protected function buildArrayMatcher(Matcher\ChainMatcher $scalarMatchers, Parser $parser) : Matcher\ArrayMatcher
+    protected function buildArrayMatcher(Matcher\ChainMatcher $scalarMatchers, Parser $parser, Backtrace $backtrace) : Matcher\ArrayMatcher
     {
-        $orMatcher = new Matcher\OrMatcher($scalarMatchers);
+        $orMatcher = new Matcher\OrMatcher($backtrace, $scalarMatchers);
 
         return new Matcher\ArrayMatcher(
-            new Matcher\ChainMatcher([
-                $orMatcher,
-                $scalarMatchers,
-                new Matcher\TextMatcher($scalarMatchers, $parser)
-            ]),
+            new Matcher\ChainMatcher(
+                'array',
+                $backtrace,
+                [
+                    $orMatcher,
+                    $scalarMatchers,
+                    new Matcher\TextMatcher($scalarMatchers, $backtrace, $parser)
+                ]
+            ),
+            $backtrace,
             $parser
         );
     }
 
-    protected function buildScalarMatchers(Parser $parser) : Matcher\ChainMatcher
+    protected function buildScalarMatchers(Parser $parser, Backtrace $backtrace) : Matcher\ChainMatcher
     {
-        return new Matcher\ChainMatcher([
-            new Matcher\CallbackMatcher(),
-            new Matcher\ExpressionMatcher(),
-            new Matcher\NullMatcher(),
-            new Matcher\StringMatcher($parser),
-            new Matcher\IntegerMatcher($parser),
-            new Matcher\BooleanMatcher($parser),
-            new Matcher\DoubleMatcher($parser),
-            new Matcher\NumberMatcher($parser),
-            new Matcher\ScalarMatcher(),
-            new Matcher\WildcardMatcher(),
-            new Matcher\UuidMatcher($parser),
-            new Matcher\JsonObjectMatcher($parser)
-        ]);
+        return new Matcher\ChainMatcher(
+            'scalars',
+            $backtrace,
+            [
+                new Matcher\CallbackMatcher($backtrace),
+                new Matcher\ExpressionMatcher($backtrace),
+                new Matcher\NullMatcher($backtrace),
+                new Matcher\StringMatcher($backtrace, $parser),
+                new Matcher\IntegerMatcher($backtrace, $parser),
+                new Matcher\BooleanMatcher($backtrace, $parser),
+                new Matcher\DoubleMatcher($backtrace, $parser),
+                new Matcher\NumberMatcher($backtrace, $parser),
+                new Matcher\ScalarMatcher($backtrace),
+                new Matcher\WildcardMatcher($backtrace),
+                new Matcher\UuidMatcher($backtrace, $parser),
+                new Matcher\JsonObjectMatcher($backtrace, $parser)
+            ]
+        );
     }
 
     protected function buildParser() : Parser

src/Factory/SimpleFactory.php

@@ -4,6 +4,7 @@
 
 namespace Coduo\PHPMatcher\Factory;
 
+use Coduo\PHPMatcher\Backtrace;
 use Coduo\PHPMatcher\Factory;
 use Coduo\PHPMatcher\Matcher;
 
@@ -12,7 +13,7 @@
  */
 class SimpleFactory implements Factory
 {
-    public function createMatcher() : Matcher
+    public function createMatcher(Backtrace $backtrace = null) : Matcher
     {
         return (new MatcherFactory())->createMatcher();
     }

src/Matcher.php

@@ -8,19 +8,27 @@
 
 final class Matcher
 {
-    private $matcher;
+    private $valueMatcher;
 
-    public function __construct(ValueMatcher $matcher)
+    private $backtrace;
+
+    public function __construct(ValueMatcher $valueMatcher, Backtrace $backtrace)
     {
-        $this->matcher = $matcher;
+        $this->valueMatcher = $valueMatcher;
+        $this->backtrace = $backtrace;
     }
 
     public function match($value, $pattern) : bool
     {
-        $result = $this->matcher->match($value, $pattern);
+        $this->backtrace->matcherEntrance(self::class, $value, $pattern);
+
+        $result = $this->valueMatcher->match($value, $pattern);
 
         if ($result === true) {
-            $this->matcher->clearError();
+            $this->backtrace->matcherSucceed(self::class, $value, $pattern);
+            $this->valueMatcher->clearError();
+        } else {
+            $this->backtrace->matcherFailed(self::class, $value, $pattern, $this->valueMatcher->getError());
         }
 
         return $result;
@@ -31,6 +39,11 @@ public function match($value, $pattern) : bool
      */
     public function getError() : ?string
     {
-        return $this->matcher->getError();
+        return $this->valueMatcher->getError();
+    }
+
+    public function backtrace(): Backtrace
+    {
+        return $this->backtrace;
     }
 }

src/Matcher/ArrayMatcher.php

@@ -4,6 +4,7 @@
 
 namespace Coduo\PHPMatcher\Matcher;
 
+use Coduo\PHPMatcher\Backtrace;
 use Coduo\PHPMatcher\Exception\Exception;
 use Coduo\PHPMatcher\Parser;
 use Coduo\ToString\StringConverter;
@@ -18,25 +19,31 @@ final class ArrayMatcher extends Matcher
     const UNIVERSAL_KEY = '@*@';
 
     private $propertyMatcher;
-
     private $accessor;
-
     private $parser;
+    private $backtrace;
 
-    public function __construct(ValueMatcher $propertyMatcher, Parser $parser)
+    public function __construct(ValueMatcher $propertyMatcher, Backtrace $backtrace, Parser $parser)
     {
         $this->propertyMatcher = $propertyMatcher;
         $this->parser = $parser;
+        $this->backtrace = $backtrace;
     }
 
     public function match($value, $pattern) : bool
     {
+        $this->backtrace->matcherEntrance(self::class, $value, $pattern);
+
         if (parent::match($value, $pattern)) {
+            $this->backtrace->matcherSucceed(self::class, $value, $pattern);
+
             return true;
         }
 
         if (!\is_array($value)) {
             $this->error = \sprintf('%s "%s" is not a valid array.', \gettype($value), new StringConverter($value));
+            $this->backtrace->matcherFailed(self::class, $value, $pattern, $this->error);
+
             return false;
         }
 
@@ -45,9 +52,13 @@ public function match($value, $pattern) : bool
         }
 
         if (false === $this->iterateMatch($value, $pattern)) {
+            $this->backtrace->matcherFailed(self::class, $value, $pattern, $this->error);
+
             return false;
         }
 
+        $this->backtrace->matcherSucceed(self::class, $value, $pattern);
+
         return true;
     }
 
@@ -247,9 +258,13 @@ private function allExpandersMatch($value, $pattern) : bool
         $typePattern = $this->parser->parse($pattern);
         if (!$typePattern->matchExpanders($value)) {
             $this->error = $typePattern->getError();
+            $this->backtrace->matcherFailed(self::class, $value, $pattern, $this->error);
+
             return false;
         }
 
+        $this->backtrace->matcherSucceed(self::class, $value, $pattern);
+
         return true;
     }
 }