Composer PCRE

https://github.com/composer/pcre
Admin
Type-safe PHP wrapper library for PCRE functions with exception-based error handling and static type...
Tokens:46,279
Snippets:317
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install composer/pcre with Composer

Source: https://github.com/composer/pcre/blob/main/README.md

Install the latest version of the composer/pcre library using Composer.

```bash
$ composer require composer/pcre
```

--------------------------------

### replace usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of calling `Regex::replace` to get the new string and to check if a match occurred.

```php
$newString = Regex::replace('{fo+}', 'bar', $string)->result;
$result = Regex::replace('{fo+}', 'bar', $string);
if ($result->matched) { /* count > 0 */ }
```

--------------------------------

### matchAllWithOffsets usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of calling `Regex::matchAllWithOffsets` and accessing the first match's text and offset.

```php
$result = Regex::matchAllWithOffsets('{[a-z]+}', 'a b c');
[$text, $offset] = $result->matches[0][0];
```

--------------------------------

### Preg::splitWithOffsets usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::splitWithOffsets. Returns a list of [string, int] pairs with the offset of each match.

```php
$parts = Preg::splitWithOffsets('{;}', 'a;b;c'); // [['a',0], ['b',2], ['c',4]]
```

--------------------------------

### matchWithOffsets usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example of using matchWithOffsets. The $matches array contains pairs of captured text and byte offset. In this example, $matches[0] is ['foo', 2].

```php
$matches = null;
if (Preg::matchWithOffsets('{fo+}', 'xxfoo', $matches) === 1) {
    [$text, $offset] = $matches[0]; // ['foo', 2]
}
```

--------------------------------

### matchAll example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example usage of Regex::matchAll. It checks if the result matched and has more than 3 matches, then accesses the first match group as a list of strings or nulls.

```php
$result = Regex::matchAll('{fo+}', $string);
if ($result->matched && $result->count > 3) {
    $all = $result->matches[0]; // list<string|null>
}
```

--------------------------------

### replaceCallback usage examples

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Two examples of using Preg::replaceCallback. The first shows basic usage with a callback that uppercases matches. The second demonstrates using the PREG_OFFSET_CAPTURE flag, where the callback receives an array with the match and its offset.

```php
$count = null;
$new = Preg::replaceCallback('{fo+}', fn ($match) => strtoupper($match[0]), 'foo', -1, $count);
// with offsets: callback receives array{string|null, int} pairs
$new = Preg::replaceCallback('{fo+}', fn ($m) => strtoupper($m[0][0]), 'foo', -1, null, PREG_OFFSET_CAPTURE);
```

--------------------------------

### matchAllStrictGroups example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example usage of Regex::matchAllStrictGroups. It iterates over the matches of the first capture group, which are guaranteed to be strings.

```php
$result = Regex::matchAllStrictGroups('{([a-z]+)}', 'a b c');
foreach ($result->matches[1] as $group) { /* all strings */ }
```

--------------------------------

### isMatch usage examples

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Usage examples: a simple boolean test without $matches, and a call that passes $matches by reference to receive output even though the method returns bool.

```php
if (Preg::isMatch('{fo+}', $subject)) { /* bool test; no $matches needed */ }
$matches = null;
Preg::isMatch('{(a)?}', 'x', $matches); // $matches written despite bool return
```

--------------------------------

### replaceCallbackArray usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of replaceCallbackArray, applying a callback to matches of the pattern '{fo+}'.

```php
$new = Preg::replaceCallbackArray(['{fo+}' => fn ($m) => strtoupper($m[0])], $subject);
```

--------------------------------

### Preg::replace usage example with array patterns

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Demonstrates using Preg::replace with a count by reference, and a second call with array patterns and replacements to perform multiple replacements in one call.

```php
$count = null;
$new = Preg::replace('{fo+}', 'bar', $subject, -1, $count);
Preg::replace(['{a}', '{b}'], ['X', 'Y'], 'ab'); // array patterns/replacements
```

--------------------------------

### Preg::matchAllStrictGroups usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::matchAllStrictGroups. Captures groups into $matches and iterates over them, ensuring each group is a string (throws UnexpectedNullMatchException if any is null).

```php
$matches = null;
$n = Preg::matchAllStrictGroups('{([a-z]+)}', 'a b c', $matches);
foreach ($matches[1] as $g) { /* strings only */ }
```

--------------------------------

### Regex::match usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of using Regex::match. The result exposes matched and matches; matches is readonly and cannot be assigned.

```php
$result = Regex::match('{fo+}', $string);
if ($result->matched) {
    $full = $result->matches[0]; // string|null
    $result->matches = []; // cannot be assigned: property is readonly
}
```

--------------------------------

### replaceCallbackStrictGroups usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of replaceCallbackStrictGroups, converting lowercase letters to uppercase. The callback receives only non-null groups.

```php
$new = Preg::replaceCallbackStrictGroups('{([a-z]+)}', fn ($m) => strtoupper($m[1]), 'abc');
```

--------------------------------

### Preg::match usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::match with and without an offset. The first call returns 0 or 1, the second uses an offset of 1. Requires importing Composer\Pcre\Preg.

```php
use Composer\Pcre\Preg;

$matches = null;
$found = Preg::match('{fo+}', $subject, $matches);           // $found is 0|1
$found2 = Preg::match('{(?P<word>[a-z]+)}', 'hi', $matches, 0, 1); // with $offset
```

--------------------------------

### Using PregMatchFlags helpers

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Example usage of the PregMatchFlags helpers, as used by callers (not directly in app code). Shows importing the class and calling getType and removeNullFromMatches with the expected return types.

```php
use Composer\Pcre\PHPStan\PregMatchFlags;

$flagsType = PregMatchFlags::getType($flagsArg, $scope);       // ?Type
$nonNull = PregMatchFlags::removeNullFromMatches($matchesType); // Type
```

--------------------------------

### Preg::matchAll usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::matchAll. Captures all lowercase word sequences into $matches and returns the count (3).

```php
$matches = null;
$n = Preg::matchAll('{[a-z]+}', 'one two three', $matches); // $n === 3
```

--------------------------------

### Regex::isMatch Signature and Example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Shows the method signature for a static check that returns a boolean. The example demonstrates usage with a pattern and subject, returning a boolean without needing a matches parameter.

```php
public static function isMatch(string $pattern, string $subject, int $offset = 0): bool
```

```php
use Composer\Pcre\Regex;

$bool = Regex::isMatch('{fo+}', $string); // bool, no $matches needed
```

--------------------------------

### Example of unsafe strict groups call

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Example of a Preg::matchStrictGroups call that triggers the rule because group 1 is optional and may be null.

```php
Preg::matchStrictGroups('{(foo)?}', 'bar', $matches); // group 1 optional -> unsafeStrictGroups
```

--------------------------------

### Composer\Pcre\MatchAllWithOffsetsResult

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchAllWithOffsetsResult.md

Documentation for the MatchAllWithOffsetsResult value object, including its constructor, public properties, and usage examples.

```APIDOC
## Constructor

### Signature
```php
public function __construct(int $count, array $matches)
```

### Parameters
- **$count** (int, `0|positive-int`) - Required - Occurrence count
- **$matches** (array, `array<int|string, list<array{string|null, int}>>`) - Required - Group → list of `[string|null, int]` pairs

### Return
None (constructor).

## Public Properties

### $matches
- **Type:** `array<int|string, list<array{string|null, int}>>`
- **Description:** An array of match group => list of matches, every match being a pair of string matched + offset in bytes (or -1 if no match).

### $count
- **Type:** `0|positive-int`
- **Description:** Number of occurrences.

### $matched
- **Type:** `bool`
- **Description:** `(bool) $count`.

## Examples

### Basic use
```php
use Composer\Pcre\Regex;

$result = Regex::matchAllWithOffsets('{[a-z]+}', 'a bb ccc');
foreach ($result->matches[0] as $entry) {
    [$text, $offset] = $entry; // [string|null, int]
    // $text === 'a' / 'bb' / 'ccc'; $offset = 0 / 2 / 5
}
```

### Iterating a named group
```php
$result = Regex::matchAllWithOffsets('{(?P<w>[a-z]+)}', 'a b');
foreach ($result->matches['w'] as [$text, $offset]) {
    // per-occurrence captured text and byte offset
}
```
```

--------------------------------

### Preg::split usage examples

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::split. The first call splits on lowercase letters; the second uses PREG_SPLIT_NO_EMPTY to skip empty matches.

```php
$parts = Preg::split('{[a-z]+}', 'x1y2z');                      // list<string>
$parts = Preg::split('{\s+}', 'a b  c', -1, PREG_SPLIT_NO_EMPTY);
```

--------------------------------

### matchWithOffsets usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of using Regex::matchWithOffsets to match a pattern and access the matched text and its offset. The matches array contains arrays with the string (or null) and an integer offset.

```php
$result = Regex::matchWithOffsets('{fo+}', $string);
if ($result->matched) {
    [$text, $offset] = $result->matches[0];
}
```

--------------------------------

### Composer\Pcre\MatchAllStrictGroupsResult

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchAllStrictGroupsResult.md

Documentation for the MatchAllStrictGroupsResult value object, including its constructor, public properties, and usage examples.

```APIDOC
## Constructor

### Signature
```php
public function __construct(int $count, array $matches)
```

### Parameters
- `$count` (int, `0|positive-int`) - Required - Occurrence count
- `$matches` (array, `array<int|string, list<string>>`) - Required - Group → list of strings

### Description
Creates a new `MatchAllStrictGroupsResult` value object. This constructor is typically not called directly; instances are produced by `Regex::matchAllStrictGroups`.

## Public Properties

### `$matches`
- Type: `array<int|string, list<string>>`
- Description: An array of match group => list of matched strings. All entries are strings.

### `$count`
- Type: `0|positive-int`
- Description: Number of occurrences.

### `$matched`
- Type: `bool`
- Description: `(bool) $count`.

## Usage Example

```php
use Composer\Pcre\Regex;

$result = Regex::matchAllStrictGroups('{([a-z]+)}', 'a b c');
foreach ($result->matches[1] as $group) {
    // $group is a string for every occurrence
}
```

## Error Handling

If the pattern contains optional subpatterns that can produce `null`, a `UnexpectedNullMatchException` is thrown instead of returning a result.

```php
use Composer\Pcre\UnexpectedNullMatchException;

try {
    $result = Regex::matchAllStrictGroups('{(foo)?(bar)}', 'bar');
} catch (UnexpectedNullMatchException $e) {
    // Pattern "{(foo)?(bar)}" had an unexpected unmatched group "1", ...
}
```
```

--------------------------------

### Preg::grep usage examples

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Example usage of Preg::grep. The first call filters elements matching the pattern; the second uses PREG_GREP_INVERT to keep non-matching elements.

```php
$filtered = Preg::grep('{[a-z]}', $elements);
$inverted = Preg::grep('{[0-9]}', $elements, PREG_GREP_INVERT);
```

--------------------------------

### Preg::matchAllWithOffsets usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Shows calling Preg::matchAllWithOffsets to capture matches and offsets. Accessing $matches[0][0] yields a [text, offset] pair for the first occurrence. The method returns the number of matches.

```php
$matches = null;
$n = Preg::matchAllWithOffsets('{[a-z]+}', 'a b', $matches);
[$text, $off] = $matches[0][0]; // first occurrence
```

--------------------------------

### Regex::match error handling

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of error handling for Regex::match. Catches PcreException and retrieves the error code.

```php
try {
    Regex::match('{invalid[', $string);
} catch (Composer\Pcre\PcreException $e) {
    $code = $e->getCode();
}
```

--------------------------------

### Catching UnexpectedNullMatchException

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/UnexpectedNullMatchException.md

Example of catching UnexpectedNullMatchException and the parent PcreException when using Preg::matchStrictGroups.

```php
use Composer\Pcre\Preg;
use Composer\Pcre\UnexpectedNullMatchException;

try {
    $matches = null;
    Preg::matchStrictGroups('{(foo)?(bar)}', 'bar', $matches);
} catch (UnexpectedNullMatchException $e) {
    // Pattern "{(foo)?(bar)}" had an unexpected unmatched group "1", ...
} catch (Composer\Pcre\PcreException $e) {
    // PCRE failure still caught by the parent type
}
```

--------------------------------

### composer require composer/pcre

Source: https://github.com/composer/pcre/blob/main/_autodocs/index.md

Installs the composer/pcre library via Composer. Ensure PHP ^7.4 || ^8.0 is available (3.x) and for PHPStan integration, PHPStan ^2.2.2 is required.

```bash
composer require composer/pcre
```

--------------------------------

### matchStrictGroups usage example

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example of using Regex::matchStrictGroups to match a pattern and access the matched group as a guaranteed string. The result's matches array contains non-null string values.

```php
$result = Regex::matchStrictGroups('{([a-z]+)}', $string);
if ($result->matched) {
    $word = $result->matches[1]; // guaranteed string
}
```

--------------------------------

### Error handling with PcreException

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/ReplaceResult.md

Error handling example showing that a PcreException is thrown when the PCRE pattern fails to compile or run. In such cases, no ReplaceResult is produced.

```php
try {
    $result = Regex::replace('{invalid[', 'x', $subject);
} catch (Composer\Pcre\PcreException $e) {
    // PCRE failed compiling/running the pattern; no result is returned
}
```

--------------------------------

### preg_match with PREG_UNMATCHED_AS_NULL comparison

Source: https://github.com/composer/pcre/blob/main/README.md

Example used to illustrate the effect of PREG_UNMATCHED_AS_NULL. The table below shows that without the flag, unmatched groups may be empty strings or missing, while with the flag they are null.

```php
preg_match('/(a)(b)*(c)(d)*/', 'ac', $matches, $flags);
```

--------------------------------

### Handling unmatched group offset (-1)

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchWithOffsetsResult.md

Demonstrates that when a group does not participate in the match, the text is null and the offset is -1. The example shows group 1 unmatched and group 2 matched.

```php
$result = Regex::matchWithOffsets('{(foo)?(bar)}', 'bar');
[$text1, $off1] = $result->matches[1]; // $text1 === null, $off1 === -1
[$text2, $off2] = $result->matches[2]; // $text2 === 'bar', $off2 === 0
```

--------------------------------

### Composer\Pcre\ReplaceResult

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/ReplaceResult.md

Documentation for the Composer\Pcre\ReplaceResult value object, including its constructor, public properties, and usage examples.

```APIDOC
## ReplaceResult Class

### Description
Immutable value object produced by the `Regex::replace*` family. Carries the resulting string plus the number of replacements performed.

### Constructor

**Signature:** `public function __construct(int $count, string $result)`

#### Parameters
- **$count** (int, `0|positive-int`) - Required - Number of replacements performed (output of `preg_replace*`'s count parameter); cast to `$matched`.
- **$result** (string) - Required - The substituted subject string.

### Public Properties
- **$result** (string) - The replaced subject string. Annotated `@readonly`.
- **$count** (`0|positive-int`) - Number of replacements performed. Annotated `@readonly`.
- **$matched** (bool) - `(bool) $count` — whether at least one replacement occurred. Annotated `@readonly`.

### Usage Example
```php
use Composer\Pcre\Regex;

$newString = Regex::replace('{fo+}', 'bar', $subject)->result; // string
```

### Error Handling
```php
try {
    $result = Regex::replace('{invalid[', 'x', $subject);
} catch (Composer\Pcre\PcreException $e) {
    // PCRE failed compiling/running the pattern; no result is returned
}
```
```

--------------------------------

### Basic use of Regex::matchWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchWithOffsetsResult.md

Shows how to use Regex::matchWithOffsets to get match results with offsets. The result's $matched property is checked, and the match group 0 is destructured into text and byte offset.

```php
use Composer\Pcre\Regex;

$result = Regex::matchWithOffsets('{fo+}', 'xxfoo');
if ($result->matched) {
    [$text, $offset] = $result->matches[0];
    // $text === 'foo', $offset === 2 (byte offset)
}
```

--------------------------------

### Using Regex::replaceCallbackArray with a callback map

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Example usage of Regex::replaceCallbackArray with a pattern-to-callback map. The result is a ReplaceResult object; the new string is accessed via the result property.

```php
$result = Regex::replaceCallbackArray(['{fo+}' => fn ($match) => strtoupper($match[0])], $string);
$newString = $result->result;
```

--------------------------------

### Using Composer\Pcre\Regex for matching and replacing

Source: https://github.com/composer/pcre/blob/main/README.md

Shows the main Regex class methods for matching and replacing. isMatch returns a bool, while match/matchWithOffsets/matchAll return result objects with ->matched and ->matches. replace methods return a result object with ->result. Note that preg_grep and preg_split are only available via the Preg class.

```php
use Composer\Pcre\Regex;

// this is useful when you are just interested in knowing if something matched
// as it returns a bool instead of int(1/0) for match
$bool = Regex::isMatch('{fo+}', $string);

$result = Regex::match('{fo+}', $string);
if ($result->matched) { something($result->matches); }

$result = Regex::matchWithOffsets('{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;
$newString = Regex::replaceCallbackArray(['{fo+}' => fn ($match) => strtoupper($match[0])], $string)->result;
```

--------------------------------

### Basic use of Regex::matchAllWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchAllWithOffsetsResult.md

Shows how to call Regex::matchAllWithOffsets and iterate over the matches[0] entries, each a [string|null, int] pair. The comments indicate expected text and byte offsets for the subject 'a bb ccc'.

```php
use Composer\Pcre\Regex;

$result = Regex::matchAllWithOffsets('{[a-z]+}', 'a bb ccc');
foreach ($result->matches[0] as $entry) {
    [$text, $offset] = $entry; // [string|null, int]
    // $text === 'a' / 'bb' / 'ccc'; $offset = 0 / 2 / 5
}
```

--------------------------------

### Constructor signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Constructor accepting a RegexArrayShapeMatcher instance.

```php
public function __construct(RegexArrayShapeMatcher $regexShapeMatcher)
```

--------------------------------

### Use Preg class methods for type-safe replacements

Source: https://github.com/composer/pcre/blob/main/README.md

Equivalent calls using the Preg class. The main difference is that failures throw a Composer\Pcre\PcreException instead of returning null or false, so return values are safely strings, ints, or arrays.

```php
use Composer\Pcre\Preg;

if (Preg::match('{fo+}', $string, $matches)) { ... }
if (Preg::matchWithOffsets('{fo+}', $string, $matches)) { ... }
if (Preg::matchAll('{fo+}', $string, $matches)) { ... }
$newString = Preg::replace('{fo+}', 'bar', $string);
$newString = Preg::replaceCallback('{fo+}', function ($match) { return strtoupper($match[0]); }, $string);
$newString = Preg::replaceCallbackArray(['{fo+}' => fn ($match) => strtoupper($match[0])], $string);
$filtered = Preg::grep('{[a-z]}', $elements);
$array = Preg::split('{[a-z]+}', $string);
```

--------------------------------

### Class hierarchy of UnexpectedNullMatchException

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/UnexpectedNullMatchException.md

Shows the inheritance chain: RuntimeException -> PcreException -> UnexpectedNullMatchException, with the source file location.

```text
\RuntimeException
 └── PcreException
      └── UnexpectedNullMatchException   (src/UnexpectedNullMatchException.php:14)
```

--------------------------------

### Preg::matchAllWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Documentation for the static method `matchAllWithOffsets` of the `Preg` class.

```APIDOC
## `matchAllWithOffsets`

### Description
Performs a global regular expression match and returns the matches along with their offsets. The matches are stored in the provided `$matches` parameter by reference.

### Method
`Preg::matchAllWithOffsets` (static method)

### Signature
```php
public static function matchAllWithOffsets(string $pattern, string $subject, ?array &$matches, int $flags = 0, int $offset = 0): int
```

### Parameters
- **`$pattern`** (string) - Required - The regular expression pattern.
- **`$subject`** (string) - Required - The input string to search.
- **`$matches`** (?array, by reference) - Required - Output parameter; receives an array mapping group names/numbers to a list of `[string|null, int]` pairs (text and offset) per occurrence.
- **`$flags`** (int) - Optional - Default: `0`. Bitmask of `PREG_UNMATCHED_AS_NULL` and/or `PREG_OFFSET_CAPTURE`.
- **`$offset`** (int) - Optional - Default: `0`. The offset in the subject at which to start searching.

### Return Value
- **`int`** - Returns `0` or a positive integer representing the number of matches found.

### Throws
- `PcreException` if the result is not an integer.
- `\InvalidArgumentException` if `PREG_SET_ORDER` flag is used.

### Example
```php
$matches = null;
$n = Preg::matchAllWithOffsets('{[a-z]+}', 'a b', $matches);
[$text, $off] = $matches[0][0]; // first occurrence
```
```

--------------------------------

### Constructor

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchStrictGroupsResult.md

Creates a new MatchStrictGroupsResult instance with the given match count and matches array.

```APIDOC
## Constructor

### Description
Creates a new MatchStrictGroupsResult instance. The count is cast to a boolean for the 'matched' property, and the matches array must contain only string values.

### Signature
```php
public function __construct(int $count, array $matches)
```

### Parameters
- **$count** (int, 0|positive-int) - Required - Match count; casts to `$matched`.
- **$matches** (array<int|string, string>) - Required - Match-group array, already validated non-null by `Regex::matchStrictGroups`.

### Return
None (constructor).
```

--------------------------------

### Discriminating PCRE errors with getCode()

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PcreException.md

Example of discriminating failure types in a catch block by comparing getCode() to PREG_COMPILE_ERROR. This allows handling bad pattern literals separately from other PCRE execution errors.

```php
} catch (PcreException $e) {
    if ($e->getCode() === PREG_COMPILE_ERROR) {
        // bad pattern literal
    } else {
        // other PCRE execution error
    }
}
```

--------------------------------

### isMatch* method signatures

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Signatures of the six boolean-returning match variants, copied from src/Preg.php. Each delegates to its counterpart and casts (bool). The two *WithOffsets variants require $matches (no default).

```php
// :299  isMatch                (string, string, ?array &$matches = null, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, string|null> $matches
// :314  isMatchStrictGroups    (string, string, ?array &$matches = null, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, string> $matches        @throws UnexpectedNullMatchException
// :328  isMatchAll             (string, string, ?array &$matches = null, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, list<string|null>> $matches
// :342  isMatchAllStrictGroups (string, string, ?array &$matches = null, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, list<string>> $matches
// :358  isMatchWithOffsets     (string, string, ?array &$matches, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, array{string|null, int<-1, max>}> $matches   (no default for $matches)
// :374  isMatchAllWithOffsets  (string, string, ?array &$matches, int $flags = 0, int $offset = 0): bool
//       @param-out array<int|string, list<array{string|null, int<-1, max>}>> $matches
```

--------------------------------

### PcreException::fromFunction

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PcreException.md

Factory method to create a PcreException instance when a preg_* call fails.

```APIDOC
## `Composer\Pcre\PcreException::fromFunction`

### Description
Creates a new `PcreException` instance when an underlying `preg_*` call fails. The exception code is set to the value of `preg_last_error()`, and the message includes the function name, pattern(s), and a human-readable error description.

### Method
`public static function fromFunction($function, $pattern)`

### Parameters
- `$function` (string) - Required - Name of the failing `preg_*` function, e.g. `'preg_match'`.
- `$pattern` (string|string[]) - Required - The pattern(s) that were executed; arrays are joined with `', '` for the message.

### Return Value
- `PcreException` - A new exception instance with the error code from `preg_last_error()`.

### Error Description Resolution
1. If `preg_last_error_msg` exists (PHP 8.1+), its value is used.
2. Otherwise, the `pcre` constant group is scanned for a constant with suffix `_ERROR` matching the error code; the constant name is used.
3. Falls back to the literal string `'UNDEFINED_ERROR'`.

### Example
```php
use Composer\Pcre\PcreException;

$exception = PcreException::fromFunction('preg_match', '{invalid[');
$code = $exception->getCode(); // int from preg_last_error()
```
```

--------------------------------

### matchAllWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Performs a global regular expression match and returns all matches with their byte offsets. This method always adds the PREG_UNMATCHED_AS_NULL and PREG_OFFSET_CAPTURE flags and rejects the PREG_SET_ORDER flag.

```APIDOC
## matchAllWithOffsets

### Description
Performs a global regular expression match and returns all matches with their byte offsets. This method always adds the PREG_UNMATCHED_AS_NULL and PREG_OFFSET_CAPTURE flags and rejects the PREG_SET_ORDER flag.

### Method
matchAllWithOffsets

### Signature
public static function matchAllWithOffsets(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllWithOffsetsResult

### Parameters
- **$pattern** (string, non-empty) - Required - PCRE pattern
- **$subject** (string) - Required - Subject string
- **$flags** (int) - Optional - Flag mask; PREG_UNMATCHED_AS_NULL and PREG_OFFSET_CAPTURE always added; PREG_SET_ORDER rejected. Default: 0
- **$offset** (int) - Optional - Byte offset. Default: 0

### Return
MatchAllWithOffsetsResult - matches: array<int|string, list<array{string|null, int<-1, max>}>>

### Throws
PcreException on failure; \InvalidArgumentException for PREG_SET_ORDER.

### Example
```php
$result = Regex::matchAllWithOffsets('{[a-z]+}', 'a b c');
[$text, $offset] = $result->matches[0][0];
```
```

--------------------------------

### matchWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Performs a regex match and returns an array of matches, each with the captured text and byte offset. Always sets PREG_OFFSET_CAPTURE internally.

```APIDOC
## `matchWithOffsets`

### Description
Performs a regex match, returning an array of matches each containing the captured string (or null) and its byte offset. The PREG_OFFSET_CAPTURE flag is always applied internally.

### Method
`public static function matchWithOffsets(string $pattern, string $subject, ?array &$matches, int $flags = 0, int $offset = 0): int`

### Parameters
- **$pattern** (string) - Required - The regex pattern.
- **$subject** (string) - Required - The input string.
- **$matches** (?array, by reference) - Required - Output array. Each element is `array{string|null, int<-1, max>}`: the captured text and byte offset (-1 if unmatched).
- **$flags** (int) - Optional - Must be `PREG_UNMATCHED_AS_NULL` or `PREG_OFFSET_CAPTURE`; PREG_OFFSET_CAPTURE is always set automatically. Default 0.
- **$offset** (int) - Optional - Offset to start search. Default 0.

### Return
- **int** - `1` if a match is found, `0` otherwise.

### Throws
- **PcreException** - When `preg_match` returns `false` (i.e., regex error).

### Example
```php
$matches = null;
if (Preg::matchWithOffsets('{fo+}', 'xxfoo', $matches) === 1) {
    [$text, $offset] = $matches[0]; // ['foo', 2]
}
```
```

--------------------------------

### matchAll(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllResult

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Performs a global regular expression match on the subject string and returns a MatchAllResult object containing match status, count, and matches array. It rejects PREG_OFFSET_CAPTURE and PREG_SET_ORDER flags, throwing exceptions if used.

```APIDOC
## `matchAll`

### Description
Performs a global regular expression match against the subject string, returning a `MatchAllResult` object with match status, count, and matches array.

### Method
`public static function matchAll`

### Signature
```php
public static function matchAll(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllResult
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$pattern` | `string` (non-empty) | yes | — | PCRE pattern |
| `$subject` | `string` | yes | — | Subject string |
| `$flags` | `int` | no | `0` | Flag mask; rejects `PREG_OFFSET_CAPTURE` and `PREG_SET_ORDER` |
| `$offset` | `int` | no | `0` | Byte offset |

### Return
- **Type:** [`MatchAllResult`](MatchAllResult.md)
- **Fields:** `matched: bool`, `count: 0|positive-int`, `matches: array<int|string, list<string|null>>`

### Throws
- [`PcreException`](PcreException.md) on failure
- `\InvalidArgumentException` for `PREG_OFFSET_CAPTURE` (suggests `matchAllWithOffsets`) and `PREG_SET_ORDER`

### Example
```php
$result = Regex::matchAll('{fo+}', $string);
if ($result->matched && $result->count > 3) {
    $all = $result->matches[0]; // list<string|null>
}
```
```

--------------------------------

### Catching PcreException

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PcreException.md

How to catch and handle PcreException thrown by Preg methods.

```APIDOC
## Catching `PcreException`

### Description
`PcreException` extends `\RuntimeException` and is thrown by `Composer\Pcre\Preg` methods when the underlying `preg_*` call fails. The exception code holds the raw `preg_last_error()` value, allowing discrimination between different PCRE error constants.

### Usage
```php
use Composer\Pcre\Preg;
use Composer\Pcre\PcreException;

try {
    Preg::match('{invalid[', $subject, $matches);
} catch (PcreException $e) {
    $code = $e->getCode(); // int from preg_last_error()
    // matching a PCRE_*_ERROR constant value (e.g. PREG_COMPILE_ERROR)
}
```

### Error Code Comparison
```php
} catch (PcreException $e) {
    if ($e->getCode() === PREG_COMPILE_ERROR) {
        // bad pattern literal
    } else {
        // other PCRE execution error
    }
}
```
```

--------------------------------

### getClass signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Returns the fully qualified class name the extension applies to.

```php
public function getClass(): string
```

--------------------------------

### Constructor signature for PregMatchParameterOutTypeExtension

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

The constructor accepts a RegexArrayShapeMatcher instance, which is injected by PHPStan's service container.

```php
public function __construct(
    RegexArrayShapeMatcher $regexShapeMatcher
)
```

--------------------------------

### Preg::replace

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Documentation for the static method `replace` of the `Preg` class.

```APIDOC
## `replace`

### Description
Performs a regular expression search and replace. Supports array patterns and replacements, and can count the number of replacements performed.

### Method
`Preg::replace` (static method)

### Signature
```php
public static function replace($pattern, $replacement, $subject, int $limit = -1, ?int &$count = null): string
```

### Parameters
- **`$pattern`** (string|string[]) - Required - The regular expression pattern or an array of patterns.
- **`$replacement`** (string|string[]) - Required - The replacement string or an array of replacements. Backreferences like `$n` and `${name}` are supported.
- **`$subject`** (string) - Required - The input string. Arrays are rejected.
- **`$limit`** (int) - Optional - Default: `-1`. Maximum number of replacements; `-1` means no limit.
- **`$count`** (?int, by reference) - Optional - Default: `null`. Output parameter; receives the number of replacements performed.

### Return Value
- **`string`** - The resulting string after replacements.

### Throws
- `\InvalidArgumentException` if `$subject` is an array.
- `\TypeError` if `$subject` is not a scalar or array.
- `PcreException` if `preg_replace` returns `null`.

### Example
```php
$count = null;
$new = Preg::replace('{fo+}', 'bar', $subject, -1, $count);
Preg::replace(['{a}', '{b}'], ['X', 'Y'], 'ab'); // array patterns/replacements
```
```

--------------------------------

### isStaticMethodSupported method signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Returns true when the declaring class is Composer\Pcre\Preg, the method is one of the match or isMatch variants, and the parameter is named 'matches'.

```php
public function isStaticMethodSupported(MethodReflection $methodReflection, ParameterReflection $parameter): bool
```

--------------------------------

### getParameterOutTypeFromStaticMethodCall method signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/PHPStan-extensions.md

Reads args 0 (pattern), 2 ($matches), and 3 ($flags). Returns null when pattern or matches arg is missing or flags cannot be inferred. Otherwise delegates to RegexArrayShapeMatcher::matchAllExpr for matchAll-prefixed methods or matchExpr with TrinaryLogic::createMaybe().

```php
public function getParameterOutTypeFromStaticMethodCall(MethodReflection $methodReflection, StaticCall $methodCall, ParameterReflection $parameter, Scope $scope): ?Type
```

--------------------------------

### matchAllStrictGroups(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllStrictGroupsResult

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Similar to matchAll but returns a MatchAllStrictGroupsResult that guarantees all match groups are non-null strings, throwing UnexpectedNullMatchException if any group captures null. Rejects the same flags as matchAll.

```APIDOC
## `matchAllStrictGroups`

### Description
Performs a global regular expression match and returns a `MatchAllStrictGroupsResult` where all captured groups are guaranteed to be strings, throwing `UnexpectedNullMatchException` if a group is null.

### Method
`public static function matchAllStrictGroups`

### Signature
```php
public static function matchAllStrictGroups(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllStrictGroupsResult
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$pattern` | `string` (non-empty) | yes | — | PCRE pattern |
| `$subject` | `string` | yes | — | Subject string |
| `$flags` | `int` | no | `0` | Flag mask; rejects `PREG_OFFSET_CAPTURE` and `PREG_SET_ORDER` |
| `$offset` | `int` | no | `0` | Byte offset |

### Return
- **Type:** [`MatchAllStrictGroupsResult`](MatchAllStrictGroupsResult.md)
- **Fields:** `matches: array<int|string, list<string>>`

### Throws
- [`UnexpectedNullMatchException`](UnexpectedNullMatchException.md)
- [`PcreException`](PcreException.md)
- `\InvalidArgumentException` for the two rejected flags

### Example
```php
$result = Regex::matchAllStrictGroups('{([a-z]+)}', 'a b c');
foreach ($result->matches[1] as $group) { /* all strings */ }
```
```

--------------------------------

### Use *StrictGroups methods for guaranteed non-null match groups

Source: https://github.com/composer/pcre/blob/main/README.md

StrictGroups variants ensure match groups are always present and non-nullable. They throw if a subpattern does not match and produces null. Safe as long as there are no optional subpatterns like (something)? or (something)* or branches with | that result in unmatched groups.

```php
use Composer\Pcre\Preg;

// $matches is guaranteed to be an array of strings, if a subpattern does not match and produces a null it will throw
if (Preg::matchStrictGroups('{fo+}', $string, $matches))
if (Preg::matchAllStrictGroups('{fo+}', $string, $matches))
```

--------------------------------

### Preg::matchAllWithOffsets signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Preg.md

Copy of the method signature from src/Preg.php:130. It requires a pattern, subject, and a by-reference matches array; flags and offset are optional. May throw PcreException on a non-int result and InvalidArgumentException for PREG_SET_ORDER.

```php
public static function matchAllWithOffsets(string $pattern, string $subject, ?array &$matches, int $flags = 0, int $offset = 0): int
```

--------------------------------

### Regex::replaceCallback

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Documentation for the static method `Regex::replaceCallback` which performs a callback-based regex replacement.

```APIDOC
## `replaceCallback`

### Description
Replaces all occurrences of a pattern in a subject string using a callback function. The callback receives the group-match array and returns the replacement string.

### Method
`Regex::replaceCallback` (static method)

### Signature
```php
public static function replaceCallback($pattern, callable $replacement, $subject, int $limit = -1, int $flags = 0): ReplaceResult
```

### Parameters
- `$pattern` (string|string[]) - Required - Pattern or array of patterns
- `$replacement` (callable) - Required - Callback; receives the group-match array as its argument and returns `string`
- `$subject` (string) - Required - Subject string
- `$limit` (int) - Optional - Default: `-1` - Maximum replacements
- `$flags` (int) - Optional - Default: `0` - Flag mask; `PREG_UNMATCHED_AS_NULL` always added, `PREG_OFFSET_CAPTURE` supported

### Return Value
- `ReplaceResult` - The result of the replacement operation.

### Exceptions
- `\InvalidArgumentException` / `\TypeError` / `PcreException` propagated from `Preg::replaceCallback`.

### Example
```php
$result = Regex::replaceCallback('{fo+}', function ($match) {
    return strtoupper($match[0]);
}, $string);
$newString = $result->result;
```
```

--------------------------------

### matchWithOffsets

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Performs a PCRE match and returns the matched text along with its byte offset. The PREG_UNMATCHED_AS_NULL and PREG_OFFSET_CAPTURE flags are always added.

```APIDOC
## `matchWithOffsets`

### Signature
```php
public static function matchWithOffsets(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchWithOffsetsResult
```

### Description
Performs a PCRE match and returns the matched text along with its byte offset. The PREG_UNMATCHED_AS_NULL and PREG_OFFSET_CAPTURE flags are always added.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$pattern` | `string` (non-empty) | yes | — | PCRE pattern |
| `$subject` | `string` | yes | — | Subject string |
| `$flags` | `int` | no | `0` | Flag mask; `PREG_UNMATCHED_AS_NULL` + `PREG_OFFSET_CAPTURE` always added |
| `$offset` | `int` | no | `0` | Byte offset |

### Return Value
- **Type:** [`MatchWithOffsetsResult`](MatchWithOffsetsResult.md)
- **Description:** `matches: array<int|string, array{string|null, int<-1, max>}>`.

### Exceptions
- [`PcreException`](PcreException.md) on failure.

### Example
```php
$result = Regex::matchWithOffsets('{fo+}', $string);
if ($result->matched) {
    [$text, $offset] = $result->matches[0];
}
```
```

--------------------------------

### Signature of fromFunction method

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/UnexpectedNullMatchException.md

The signature of the fromFunction method, which is guarded and always throws a LogicException.

```php
public static function fromFunction($function, $pattern)
```

--------------------------------

### matchAll signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/Regex.md

Signature of the matchAll method. It accepts a non-empty pattern, subject, flags, and offset, returning a MatchAllResult. Flags reject PREG_OFFSET_CAPTURE and PREG_SET_ORDER.

```php
public static function matchAll(string $pattern, string $subject, int $flags = 0, int $offset = 0): MatchAllResult
```

--------------------------------

### MatchAllResult constructor signature

Source: https://github.com/composer/pcre/blob/main/_autodocs/api-reference/MatchAllResult.md

Constructor signature for the MatchAllResult value object. It accepts the occurrence count and the matches array, storing the count and casting it to the matched boolean property.

```php
public function __construct(int $count, array $matches)
```
Tokens:
Raw