Add Preg::isMatch and Preg::isMatchAll (#4)

Author: johnstevenson

README.md

@@ -64,6 +64,16 @@ the fact that they can only be strings (for replace), ints (for match) or arrays
 Similarly, due to type safety requirements matching using PREG_OFFSET_CAPTURE is made available via
 `matchWithOffset` and `matchAllWithOffset`. You cannot pass the flag to `match`/`matchAll`.
 
+Additionally the `Preg` class provides match methods that return `bool` rather than `int`, for stricter type safety
+when the number of pattern matches is not useful:
+
+```php
+use Composer\Pcre\Preg;
+
+if (Preg::isMatch('{fo+}', $string, $matches)) // bool
+if (Preg::isMatchAll('{fo+}', $string, $matches)) // bool
+```
+
 If you would prefer a slightly more verbose usage, replacing by-ref arguments by result objects, you can use the `Regex` class:
 
 ```php

src/Preg.php

@@ -214,4 +214,30 @@ public static function grep($pattern, array $array, $flags = 0)
 
         return $result;
     }
+
+    /**
+     * @param string   $pattern
+     * @param string   $subject
+     * @param array<string|null> $matches Set by method
+     * @param int      $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
+     * @param int      $offset
+     * @return bool
+     */
+    public static function isMatch($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
+    {
+        return (bool) static::match($pattern, $subject, $matches, $flags, $offset);
+    }
+
+    /**
+     * @param string   $pattern
+     * @param string   $subject
+     * @param array<int|string, list<string|null>> $matches Set by method
+     * @param int      $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
+     * @param int      $offset
+     * @return bool
+     */
+    public static function isMatchAll($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
+    {
+        return (bool) static::matchAll($pattern, $subject, $matches, $flags, $offset);
+    }
 }

tests/PregTests/IsMatchAllTest.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * This file is part of composer/pcre.
+ *
+ * (c) Composer <https://github.com/composer>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Composer\Pcre\PregTests;
+
+use Composer\Pcre\BaseTestCase;
+use Composer\Pcre\Preg;
+
+class IsMatchAllTest extends BaseTestCase
+{
+    /**
+     * This can be replaced with a setUp() method when appropriate
+     *
+     * @before
+     * @return void
+     */
+    public function registerFunctionName()
+    {
+        $this->pregFunction = 'preg_match_all()';
+    }
+
+    /**
+     * @return void
+     */
+    public function testSuccess()
+    {
+        $result = Preg::isMatchAll('{[aei]}', 'abcdefghijklmnopqrstuvwxyz', $matches);
+        $this->assertSame(true, $result);
+        $this->assertSame(array(0 => array('a', 'e', 'i')), $matches);
+    }
+
+    /**
+     * @return void
+     */
+    public function testSuccessNoRef()
+    {
+        $result = Preg::isMatchAll('{[aei]}', 'abcdefghijklmnopqrstuvwxyz');
+        $this->assertSame(true, $result);
+    }
+
+    /**
+     * @return void
+     */
+    public function testFailure()
+    {
+        $result = Preg::isMatchAll('{abc}', 'def', $matches);
+        $this->assertSame(false, $result);
+        $this->assertSame(array(array()), $matches);
+    }
+
+    /**
+     * @return void
+     */
+    public function testBadPatternThrowsIfWarningsAreNotThrowing()
+    {
+        $this->expectPcreException($pattern = '{[aei]');
+        @Preg::isMatchAll($pattern, 'abcdefghijklmnopqrstuvwxyz');
+    }
+
+    /**
+     * @return void
+     */
+    public function testBadPatternTriggersWarningByDefault()
+    {
+        $this->expectPcreWarning();
+        Preg::isMatchAll('{[aei]', 'abcdefghijklmnopqrstuvwxyz');
+    }
+}

tests/PregTests/IsMatchTest.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * This file is part of composer/pcre.
+ *
+ * (c) Composer <https://github.com/composer>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Composer\Pcre\PregTests;
+
+use Composer\Pcre\BaseTestCase;
+use Composer\Pcre\Preg;
+
+class IsMatchTest extends BaseTestCase
+{
+    /**
+     * This can be replaced with a setUp() method when appropriate
+     *
+     * @before
+     * @return void
+     */
+    public function registerFunctionName()
+    {
+        $this->pregFunction = 'preg_match()';
+    }
+
+    /**
+     * @return void
+     */
+    public function testSuccess()
+    {
+        $result = Preg::isMatch('{(?P<m>[io])}', 'abcdefghijklmnopqrstuvwxyz', $matches);
+        $this->assertSame(true, $result);
+        $this->assertSame(array(0 => 'i', 'm' => 'i', 1 => 'i'), $matches);
+    }
+
+    /**
+     * @return void
+     */
+    public function testSuccessNoRef()
+    {
+        $result = Preg::isMatch('{(?P<m>[io])}', 'abcdefghijklmnopqrstuvwxyz');
+        $this->assertSame(true, $result);
+    }
+
+    /**
+     * @return void
+     */
+    public function testFailure()
+    {
+        $result = Preg::isMatch('{abc}', 'def', $matches);
+        $this->assertSame(false, $result);
+        $this->assertSame(array(), $matches);
+    }
+
+    /**
+     * @return void
+     */
+    public function testBadPatternThrowsIfWarningsAreNotThrowing()
+    {
+        $this->expectPcreException($pattern = '{(?P<m>[io])');
+        @Preg::isMatch($pattern, 'abcdefghijklmnopqrstuvwxyz');
+    }
+
+    /**
+     * @return void
+     */
+    public function testBadPatternTriggersWarningByDefault()
+    {
+        $this->expectPcreWarning();
+        Preg::isMatch('{(?P<m>[io])', 'abcdefghijklmnopqrstuvwxyz');
+    }
+}