Initial commit

.gitattributes

@@ -0,0 +1,17 @@
+# Auto-detect text files, ensure they use LF.
+*       text=auto eol=lf
+
+# These files are always considered text and should use LF.
+# See core.whitespace @ http://git-scm.com/docs/git-config for whitespace flags.
+*.php   text eol=lf whitespace=blank-at-eol,blank-at-eof,space-before-tab,tab-in-indent,tabwidth=4 diff=php
+*.json  text eol=lf whitespace=blank-at-eol,blank-at-eof,space-before-tab,tab-in-indent,tabwidth=4
+
+# Ignore these files in GitHub dists and `git archive` actions.
+/.gitattributes export-ignore
+/.github export-ignore
+/.gitignore export-ignore
+/.php_cs export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore
+/tests export-ignore
+/CONTRIBUTING.md export-ignore

.github/workflows/continuous-integration.yml

@@ -0,0 +1,60 @@
+name: "Continuous Integration"
+
+on:
+  - push
+  - pull_request
+
+env:
+  COMPOSER_FLAGS: "--ansi --no-interaction --no-progress --prefer-dist"
+  SYMFONY_PHPUNIT_REMOVE_RETURN_TYPEHINT: "1"
+
+jobs:
+  tests:
+    name: "CI"
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version:
+          - "5.3"
+          - "5.4"
+          - "5.5"
+          - "5.6"
+          - "7.0"
+          - "7.1"
+          - "7.2"
+          - "7.3"
+          - "7.4"
+          - "8.0"
+          - "8.1"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: Get composer cache directory
+        id: composercache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composercache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: "Install latest dependencies"
+        run: |
+          # Remove PHPStan as it requires a newer PHP
+          composer remove phpstan/phpstan --dev --no-update
+          composer update ${{ env.COMPOSER_FLAGS }}
+
+      - name: "Run tests"
+        run: "vendor/bin/simple-phpunit --verbose"

.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: "PHP Lint"
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  tests:
+    name: "Lint"
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version:
+          - "5.3"
+          - "8.1"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: "Lint PHP files"
+        run: "find src/ -type f -name '*.php' -print0 | xargs -0 -L1 -P4 -- php -l -f"

.github/workflows/phpstan.yml

@@ -0,0 +1,50 @@
+name: "PHPStan"
+
+on:
+  - push
+  - pull_request
+
+env:
+  COMPOSER_FLAGS: "--ansi --no-interaction --no-progress --prefer-dist"
+  SYMFONY_PHPUNIT_VERSION: ""
+
+jobs:
+  tests:
+    name: "PHPStan"
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: Get composer cache directory
+        id: composercache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composercache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: "Install latest dependencies"
+        run: "composer update ${{ env.COMPOSER_FLAGS }}"
+
+      - name: Run PHPStan
+        # Locked to phpunit 7.5 here as newer ones have void return types which break inheritance
+        run: |
+          composer require --dev phpunit/phpunit:^7.5.20 --with-all-dependencies ${{ env.COMPOSER_FLAGS }}
+          vendor/bin/phpstan analyse

.gitignore

@@ -0,0 +1,4 @@
+vendor/
+.php_cs.cache
+composer.lock
+.phpunit.result.cache

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+Contributing to composer/pcre
+=============================
+
+Please note that this project is released with a
+[Contributor Code of Conduct](http://contributor-covenant.org/version/1/1/0/).
+By participating in this project and its community you agree to abide by those terms.
+
+Reporting Issues
+----------------
+
+When reporting issues, please try to be as descriptive as possible, and include
+as much relevant information as you can. A step by step guide on how to
+reproduce the issue will greatly increase the chances of your issue being
+resolved in a timely manner.
+
+Contributing Policy
+-------------------
+
+Fork the project, create a feature branch, and send us a pull request.
+
+To ensure a consistent code base, you should make sure the code follows
+the [PSR-2 Coding Standards](http://www.php-fig.org/psr/psr-2/). Run
+[php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) to automatically "fix" files.
+
+If you would like to help, take a look at the [list of issues](https://github.com/composer/pcre/issues).

LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2021 Composer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,61 @@
+composer/pcre
+=============
+
+PCRE wrapping library that offers type-safe preg_* replacements.
+
+If you are using a modern PHP version you are probably better off using [spatie/regex](https://github.com/spatie/regex) instead as it offers more functionality.
+
+This library is a minimalistic way to ensure preg_* functions do not fail silently, returning unexpected `null`s.
+
+[![Continuous Integration](https://github.com/composer/pcre/workflows/Continuous%20Integration/badge.svg?branch=main)](https://github.com/composer/pcre/actions)
+
+
+Installation
+------------
+
+Install the latest version with:
+
+```bash
+$ composer require composer/pcre
+```
+
+
+Requirements
+------------
+
+* PHP 5.3.2 is required but using the latest version of PHP is highly recommended.
+
+
+Basic usage
+-----------
+
+Instead of:
+
+```php
+if (preg_match('{fo+}', $string, $matches)) { ... }
+if (preg_match_all('{fo+}', $string, $matches)) { ... }
+$newString = preg_replace('{fo+}', 'bar', $string);
+$newString = preg_replace_callback('{fo+}', function ($match) { return strtoupper($match[0]); }, $string);
+```
+
+You can now do:
+
+```php
+use Composer\Pcre\Regex;
+
+$result = Regex::match('{fo+}', $string);
+if ($result->matched) { something($result->matches); }
+
+$result = Regex::matchAll('{fo+}', $string);
+if ($result->matched && $result->count > 3) { something($result->matches); }
+
+$newString = Regex::replace('{fo+}', 'bar', $string)->result;
+$newString = Regex::replaceCallback('{fo+}', function ($match) { return strtoupper($match[0]); }, $string)->result;
+```
+
+See the *Result classes for more.
+
+License
+-------
+
+composer/pcre is licensed under the MIT License, see the LICENSE file for details.

composer.json

@@ -0,0 +1,45 @@
+{
+    "name": "composer/pcre",
+    "description": "PCRE wrapping library that offers type-safe preg_* replacements.",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "pcre",
+        "regex",
+        "preg",
+        "regular expression"
+    ],
+    "authors": [
+        {
+            "name": "Jordi Boggiano",
+            "email": "[email protected]",
+            "homepage": "http://seld.be"
+        }
+    ],
+    "require": {
+        "php": "^5.3.2 || ^7.0 || ^8.0"
+    },
+    "require-dev": {
+        "symfony/phpunit-bridge": "^4.2 || ^5",
+        "phpstan/phpstan": "^1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Composer\\Pcre\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Composer\\Pcre\\": "tests"
+        }
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-main": "1.x-dev"
+        }
+    },
+    "scripts": {
+        "test": "SYMFONY_PHPUNIT_REMOVE_RETURN_TYPEHINT=1 vendor/bin/simple-phpunit",
+        "phpstan": "phpstan analyse"
+    }
+}

phpstan.neon.dist

@@ -0,0 +1,5 @@
+parameters:
+    level: 9
+    paths:
+        - src
+        - tests

phpunit.xml.dist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.5/phpunit.xsd"
+    backupGlobals="false"
+    colors="true"
+    bootstrap="vendor/autoload.php"
+    >
+    <testsuites>
+        <testsuite name="PCRE Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/MatchAllResult.php

@@ -0,0 +1,48 @@
+<?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;
+
+class MatchAllResult
+{
+    /**
+     * @readonly
+     * @var array<array<string|null>>
+     */
+    public $matches;
+
+    /**
+     * @readonly
+     * @var int
+     */
+    public $count;
+
+    /**
+     * @readonly
+     * @var bool
+     */
+    public $matched;
+
+    /**
+     * @param  int $count
+     * @param  array<array<string|null>> $matches
+     * @return self
+     */
+    public static function create($count, $matches)
+    {
+        $result = new self;
+        $result->matches = $matches;
+        $result->matched = (bool) $count;
+        $result->count = $count;
+
+        return $result;
+    }
+}