Replaced PHPMatcher facade with implementation that makes possible to access backtrace

Author: norberttech

README.md

@@ -2,8 +2,12 @@
 
 Library created for testing all kinds of JSON/XML/TXT/Scalar values against patterns.
 
+API: 
+
 ```php
-PHPMatcher::match($value = '{"foo": "bar"}', $pattern = '{"foo": "@string@"}');
+PHPMatcher::match($value = '{"foo": "bar"}', $pattern = '{"foo": "@string@"}') : bool;
+PHPMatcher::backtrace() : Backtrace;
+PHPMatcher::error() : ?string;
 ```
 
 It was built to simplify API's functional testing.
@@ -31,32 +35,56 @@ composer require --dev "coduo/php-matcher"
 
 ## Basic usage
 
-### Using facade
+### Direct PHPMatcher usage
 
 ```php
 <?php
 
 use Coduo\PHPMatcher\PHPMatcher;
 
-if (!PHPMatcher::match("lorem ipsum dolor", "@string@", $error)) {
-    echo $error; // in case of error message is set on $error variable via reference
+$matcher = new PHPMatcher();
+$match = $matcher->match("lorem ipsum dolor", "@string@");
+
+if (!$match) {
+    echo "Error: " . $matcher->error();
+    echo "Backtrace: \n";
+    echo (string) $matcher->backtrace();
 }
+```
+
+### PHPUnit extending PHPMatcherTestCase
+
+```php
+<?php
+
+use Coduo\PHPMatcher\PHPUnit\PHPMatcherTestCase;
 
+class MatcherTest extends PHPMatcherTestCase
+{
+    public function test_matcher_that_value_matches_pattern()
+    {
+        $this->assertMatchesPattern('{"name": "Norbert"}', '{"name": "@string@"}');
+    }
+}
 ```
 
-### Using Factory
+### PHPUnit using PHPMatcherAssertions trait
 
 ```php
 <?php
 
-use Coduo\PHPMatcher\Factory\MatcherFactory;
+use Coduo\PHPMatcher\PHPUnit\PHPMatcherAssertions;
+use PHPUnit\Framework\TestCase;
 
-$factory = new MatcherFactory();
-$matcher = $factory->createMatcher();
+class MatcherTest extends TestCase
+{
+    use PHPMatcherAssertions;
 
-$match = $matcher->match("lorem ipsum dolor", "@string@");
-// $match === true
-$matcher->getError(); // returns null or error message
+    public function test_matcher_that_value_matches_pattern()
+    {
+        $this->assertMatchesPattern('{"name": "Norbert"}', '{"name": "@string@"}');
+    }
+}
 ```
 
 ### Available patterns

UPGRADE.md

@@ -0,0 +1,26 @@
+# 3.x -> 4.0 
+
+Below you can find list of changes between 3.x and 4.0 versions of PHPMatcher.
+
+### Creating Matcher
+
+```diff
+-$factory = new MatcherFactory();
+-$this->matcher = $factory->createMatcher();
+```
+
+```diff
++$this->matcher = new PHPMatcher();
+```
+
+### Simple Matching
+
+```diff
+-PHPMatcher::match($value, $pattern, $error)
+```
+
+```diff
++$matcher = new PHPMatcher();
++$matcher->match($value, $pattern);
++echo $matcher->error();
+```

src/Backtrace.php

@@ -104,6 +104,11 @@ public function expanderFailed(string $name, $value, string $error) : void
         );
     }
 
+    public function isEmpty() : bool
+    {
+        return \count($this->trace) === 0;
+    }
+
     public function __toString() : string
     {
         return \implode("\n", $this->trace);

src/Factory.php

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

src/Factory/MatcherFactory.php

@@ -12,9 +12,9 @@
 
 final class MatcherFactory implements Factory
 {
-    public function createMatcher(Backtrace $backtrace = null) : Matcher
+    public function createMatcher() : Matcher
     {
-        $matcherBacktrace = $backtrace ? $backtrace : new Backtrace();
+        $matcherBacktrace = new Backtrace();
 
         return new Matcher($this->buildMatchers($this->buildParser($matcherBacktrace), $matcherBacktrace), $matcherBacktrace);
     }

src/Factory/SimpleFactory.php

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

src/PHPMatcher.php

@@ -8,27 +8,43 @@
 
 final class PHPMatcher
 {
-    public static function match($value, $pattern, string &$error = null) : bool
+    private $matcher;
+
+    public function match($value, $pattern) : bool
     {
-        $matcher = (new MatcherFactory())->createMatcher();
+        $this->matcher = null;
 
-        if (!$matcher->match($value, $pattern)) {
-            $error = $matcher->getError();
-            return false;
-        }
+        return $this->getMatcher()->match($value, $pattern);
+    }
 
-        return true;
+    /**
+     * Returns backtrace from last matching.
+     * When called before PHPMatcher::match() function it will return instance where Backtrace::isEmpty() will return true
+     *
+     * @return Backtrace
+     */
+    public function backtrace() : Backtrace
+    {
+        return $this->getMatcher()->backtrace();
     }
 
-    public static function matchBacktrace($value, $pattern, Backtrace $backtrace, string &$error = null) : bool
+    /**
+     * Returns error from last matching.
+     * If last matching was successful this function will return null.
+     *
+     * @return string|null
+     */
+    public function error() : ?string
     {
-        $matcher = (new MatcherFactory())->createMatcher($backtrace);
+        return $this->getMatcher()->getError();
+    }
 
-        if (!$matcher->match($value, $pattern)) {
-            $error = $matcher->getError();
-            return false;
+    private function getMatcher() : Matcher
+    {
+        if (null === $this->matcher) {
+            $this->matcher = (new MatcherFactory())->createMatcher();
         }
 
-        return true;
+        return $this->matcher;
     }
 }

src/PHPUnit/PHPMatcherConstraint.php

@@ -4,9 +4,7 @@
 
 namespace Coduo\PHPMatcher\PHPUnit;
 
-use Coduo\PHPMatcher\Backtrace;
-use Coduo\PHPMatcher\Factory\MatcherFactory;
-use Coduo\PHPMatcher\Matcher;
+use Coduo\PHPMatcher\PHPMatcher;
 use PHPUnit\Framework\Constraint\Constraint;
 use PHPUnit\Util\Json;
 use SebastianBergmann\Comparator\ComparisonFailure;
@@ -15,7 +13,6 @@ final class PHPMatcherConstraint extends Constraint
 {
     private $pattern;
     private $matcher;
-    private $backtrace;
     private $lastValue;
 
     public function __construct($pattern)
@@ -33,33 +30,30 @@ public function __construct($pattern)
         }
 
         $this->pattern = $pattern;
-        $this->backtrace = new Backtrace();
-        $this->matcher = $this->createMatcher();
+        $this->matcher = new PHPMatcher();
     }
 
     /**
      * {@inheritdoc}
      */
     public function toString() : string
     {
-        return 'matches the pattern';
+        return 'matches given pattern.';
     }
 
     protected function failureDescription($other): string
     {
-        return parent::failureDescription($other) . ".\nError: " . $this->matcher->getError();
+        return parent::failureDescription($other)
+            . "\nPattern: " . $this->exporter()->export($this->pattern)
+            . "\nError: " . $this->matcher->error()
+            . "\nBacktrace: \n" . $this->matcher->backtrace();
     }
 
     protected function matches($value) : bool
     {
         return $this->matcher->match($this->lastValue = $value, $this->pattern);
     }
 
-    private function createMatcher() : Matcher
-    {
-        return (new MatcherFactory())->createMatcher($this->backtrace);
-    }
-
     /**
      * {@inheritdoc}
      */

tests/BacktraceTest.php

@@ -4,21 +4,19 @@
 
 namespace Coduo\PHPMatcher\Tests;
 
-use Coduo\PHPMatcher\Factory\MatcherFactory;
-use Coduo\PHPMatcher\Matcher;
+use Coduo\PHPMatcher\PHPMatcher;
 use PHPUnit\Framework\TestCase;
 
 final class BacktraceTest extends TestCase
 {
     /**
-     * @var Matcher
+     * @var PHPMatcher
      */
     protected $matcher;
 
     public function setUp() : void
     {
-        $factory = new MatcherFactory();
-        $this->matcher = $factory->createMatcher();
+        $this->matcher = new PHPMatcher();
     }
 
     public function test_backtrace_in_failed_simple_matching()

tests/EmptyPatternsTest.php

@@ -4,22 +4,19 @@
 
 namespace Coduo\PHPMatcher\Tests;
 
-use Coduo\PHPMatcher\Factory\MatcherFactory;
-use Coduo\PHPMatcher\Matcher;
 use Coduo\PHPMatcher\PHPMatcher;
 use PHPUnit\Framework\TestCase;
 
 final class EmptyPatternsTest extends TestCase
 {
     /**
-     * @var Matcher
+     * @var PHPMatcher
      */
     protected $matcher;
 
     public function setUp() : void
     {
-        $factory = new MatcherFactory();
-        $this->matcher = $factory->createMatcher();
+        $this->matcher = new PHPMatcher();
     }
 
     /**
@@ -29,7 +26,6 @@ public function test_empty_pattern_in_the_json($value, $pattern, $expectedResult
     {
         $match = $this->matcher->match($value, $pattern);
         $this->assertSame($expectedResult, $match);
-        $this->assertSame($expectedResult, PHPMatcher::match($value, $pattern));
     }
 
     public static function emptyPatternString()

tests/ExpandersTest.php

@@ -4,31 +4,27 @@
 
 namespace Coduo\PHPMatcher\Tests;
 
-use Coduo\PHPMatcher\Factory\MatcherFactory;
-use Coduo\PHPMatcher\Matcher;
 use Coduo\PHPMatcher\PHPMatcher;
 use PHPUnit\Framework\TestCase;
 
 final class ExpandersTest extends TestCase
 {
     /**
-     * @var Matcher
+     * @var PHPMatcher
      */
     protected $matcher;
 
     public function setUp() : void
     {
-        $factory = new MatcherFactory();
-        $this->matcher = $factory->createMatcher();
+        $this->matcher = new PHPMatcher();
     }
 
     /**
      * @dataProvider expanderExamples()
      */
     public function test_expanders($value, $pattern, $expectedResult)
     {
-        $this->assertSame($expectedResult, $this->matcher->match($value, $pattern), (string) $this->matcher->getError());
-        $this->assertSame($expectedResult, PHPMatcher::match($value, $pattern));
+        $this->assertSame($expectedResult, $this->matcher->match($value, $pattern), (string) $this->matcher->error());
     }
 
     public static function expanderExamples()

tests/Factory/SimpleFactoryTest.php

@@ -5,13 +5,14 @@
 namespace Coduo\PHPMatcher\Tests;
 
 use Coduo\PHPMatcher\Factory\SimpleFactory;
+use Coduo\PHPMatcher\Matcher;
 use PHPUnit\Framework\TestCase;
 
 class SimpleFactoryTest extends TestCase
 {
     public function test_creating_matcher()
     {
         $factory = new SimpleFactory();
-        $this->assertInstanceOf('Coduo\PHPMatcher\Matcher', $factory->createMatcher());
+        $this->assertInstanceOf(Matcher::class, $factory->createMatcher());
     }
 }