Spatie Regex

https://github.com/spatie/regex
Admin
Spatie Regex is a PHP package that provides a cleaner, more expressive interface for working with...
Tokens:5,002
Snippets:32
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Composer Installation for Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Provides the command to install the spatie/regex package using Composer. This is the standard method for managing dependencies in PHP projects.

```bash
composer require spatie/regex
```

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

### Retrieving the Full Match with MatchResult::result

Source: https://github.com/spatie/regex/blob/main/README.md

Explains how to use the `result` method on a `MatchResult` object to get the entire substring that matched the pattern. It returns `null` if no match was found.

```php
use Spatie\Regex\Regex;

Regex::match('/abc/', 'abc')->result(); // 'abc'
Regex::match('/def/', 'abc')->result(); // null
```

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

### Callable Replacement with Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Illustrates using a callable function as the replacement in `Regex::replace`. The callable receives a `MatchResult` object, allowing for dynamic replacements based on the matched content. The example shows repeating the matched character.

```php
Regex::replace('/a/', function (MatchResult $matchResult) {
    return str_repeat($matchResult->result(), 2);
}, 'abc')->result(); // 'aabc'
```

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

### Running Tests with Composer

Source: https://github.com/spatie/regex/blob/main/README.md

Provides the command to execute the package's test suite using Composer. This is a standard way to verify the package's functionality and ensure it integrates correctly.

```bash
$ composer test
```

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

### Basic Regex Matching and Grouping with Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Demonstrates how to use the `Regex::match` method for simple pattern matching and capturing specific groups. It shows how to check for a match, retrieve the full match, and extract captured subgroups. The `resultOr` and `groupOr` methods are also shown for providing default values when no match is found.

```php
use Spatie\Regex\Regex;

// Using `match`
Regex::match('/a/', 'abc'); // `MatchResult` object
Regex::match('/a/', 'abc')->hasMatch(); // true
Regex::match('/a/', 'abc')->result(); // 'a'

// Capturing groups with `match`
Regex::match('/a(b)/', 'abc')->result(); // 'ab'
Regex::match('/a(b)/', 'abc')->group(1); // 'b'

// Setting defaults
Regex::match('/a(b)/', 'xyz')->resultOr('default'); // 'default'
Regex::match('/a(b)/', 'xyz')->groupOr(1, 'default'); // 'default'
```

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

### Basic String Replacement with Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Demonstrates how to perform a simple string replacement using the `Regex::replace` method. This method takes a pattern, a replacement string, and the subject string as arguments. It returns the modified string.

```php
Regex::replace('/a/', 'b', 'abc')->result(); // 'bbc'
```

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

### Retrieving All Matches with MatchAllResult::results

Source: https://github.com/spatie/regex/blob/main/README.md

Illustrates how to use the `results` method of the `MatchAllResult` class to obtain an array of `MatchResult` objects, each representing a distinct match found by `Regex::matchAll`.

```php
use Spatie\Regex\Regex;

$results = Regex::matchAll('/ab([a-z])/', 'abcabd')->results();

$results[0]->result(); // 'abc'
$results[0]->group(1); // 'c'
$results[1]->result(); // 'abd'
$results[1]->group(1); // 'd'
```

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

### Matching All Occurrences with Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Illustrates the use of `Regex::matchAll` to find all occurrences of a pattern within a subject string. It explains how to check if any matches exist and how to retrieve an array of `MatchResult` objects, each representing a single match and its captured groups.

```php
use Spatie\Regex\Regex;

// Using `matchAll`
Regex::matchAll('/a/', 'abcabc')->hasMatch(); // true
Regex::matchAll('/a/', 'abcabc')->results(); // Array of `MatchResult` objects
```

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

### Perform Multiple Pattern Matching with Regex::matchAll()

Source: https://context7.com/spatie/regex/llms.txt

The `Regex::matchAll()` method finds all occurrences of a pattern within a string. It returns a `MatchAllResult` object, where the `results()` method yields an array of `MatchResult` objects. Each `MatchResult` provides access to the full match and captured groups, including named groups. This method is useful for extracting multiple pieces of information from text, such as all email addresses.

```php
use Spatie\Regex\Regex;

// Find all occurrences
$result = Regex::matchAll('/a/', 'banana');
$result->hasMatch();  // true
$matches = $result->results();
count($matches);              // 3
$matches[0]->result();        // 'a'
$matches[1]->result();        // 'a'
$matches[2]->result();        // 'a'

// No matches returns empty array
$result = Regex::matchAll('/xyz/', 'abcdef');
$result->hasMatch();   // false
$result->results();    // []

// Capturing groups in multiple matches
$result = Regex::matchAll('/a(b)/', 'ababab');
$matches = $result->results();
count($matches);              // 3
$matches[0]->result();        // 'ab'
$matches[0]->group(1);        // 'b'
$matches[1]->result();        // 'ab'
$matches[1]->group(1);        // 'b'

// Named groups with matchAll
$text = <<<'TEXT'
the sky is blue
foo bar
the sky is green
the sky is red
TEXT;

$result = Regex::matchAll('/the sky is (?<color>.+)/', $text);
$matches = $result->results();

count($matches);                  // 3
$matches[0]->result();            // 'the sky is blue'
$matches[0]->group('color');      // 'blue'
$matches[0]->group(1);            // 'blue'
$matches[1]->group('color');      // 'green'
$matches[2]->group('color');      // 'red'

// Extract all email addresses from text
$text = 'Contact us at support@example.com or sales@company.org for more info.';
$result = Regex::matchAll('/[\w.+-]+@[\w-]+\.[\w.-]+/', $text);

foreach ($result->results() as $match) {
    echo $match->result() . "\n";
}
// Output:
// support@example.com
// sales@company.org

```

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

### Perform Single Pattern Matching with Regex::match()

Source: https://context7.com/spatie/regex/llms.txt

The `Regex::match()` method finds the first occurrence of a pattern in a string. It returns a `MatchResult` object, which allows checking for matches, retrieving the full match, accessing captured groups by index or name, and providing default values for missing matches. It also handles exceptions for invalid patterns or non-existent groups.

```php
use Spatie\Regex\Regex;
use Spatie\Regex\Exceptions\RegexFailed;

// Basic pattern matching
$result = Regex::match('/abc/', 'abcdef');
$result->hasMatch();  // true
$result->result();    // 'abc'

// No match returns null for result
$result = Regex::match('/xyz/', 'abcdef');
$result->hasMatch();  // false
$result->result();    // null

// Capturing groups (1-based index)
$result = Regex::match('/a(b)(c)/', 'abcdef');
$result->result();    // 'abc' (full match)
$result->group(1);    // 'b'
$result->group(2);    // 'c'

// Named capturing groups
$result = Regex::match('/(?<first>\w+)@(?<domain>\w+\.\w+)/', 'user@example.com');
$result->result();              // 'user@example.com'
$result->group('first');        // 'user'
$result->namedGroup('domain');  // 'example.com'

// Get all groups as array
$result = Regex::match('/(a)(b)(c)/', 'abc');
$result->groups();  // ['abc', 'a', 'b', 'c']

// Default values for missing matches
$result = Regex::match('/blue/', 'yellow');
$result->resultOr('default');   // 'default'

$result = Regex::match('/the sky is (.+)/', 'unknown text');
$result->groupOr(1, 'blue');    // 'blue'

// Unmatched optional groups return null
$result = Regex::match('/(?<A>a)|(?<B>b)/', 'a');
$groups = $result->groups();
$groups['A'];  // 'a'
$groups['B'];  // null

// Exception handling for non-existent groups
try {
    Regex::match('/(a)bc/', 'abcdef')->group(5);
} catch (RegexFailed $e) {
    echo $e->getMessage();  // "Pattern `/(a)bc/` with subject `abcdef` didn't capture a group named 5"
}

// Exception for invalid patterns
try {
    Regex::match('/abc', 'abc');  // Missing closing delimiter
} catch (RegexFailed $e) {
    echo $e->getMessage();  // "Error matching pattern `/abc` with subject `abc`. preg_match(): No ending delimiter '/' found"
}
```

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

### Replacing Patterns with Spatie Regex

Source: https://github.com/spatie/regex/blob/main/README.md

Shows how to use the `Regex::replace` method to substitute patterns within a subject string. This method supports simple string replacements as well as replacements defined by a callback function, allowing for dynamic content generation based on the match. It returns a `ReplaceResult` object.

```php
use Spatie\Regex\Regex;
use Spatie\Regex\MatchResult;

// Using replace
Regex::replace('/a/', 'b', 'abc')->result(); // 'bbc';
Regex::replace('/a/', function (MatchResult $result) {
    return $result->result() . 'Hello!';
}, 'abc')->result(); // 'aHello!bc';
```

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

### Checking for Matches with MatchAllResult::hasMatch

Source: https://github.com/spatie/regex/blob/main/README.md

Demonstrates the `hasMatch` method of the `MatchAllResult` class, which returns a boolean indicating whether the pattern found any matches in the subject string.

```php
use Spatie\Regex\Regex;

Regex::matchAll('/abc/', 'abc')->hasMatch(); // true
Regex::matchAll('/abc/', 'abcabc')->hasMatch(); // true
Regex::matchAll('/def/', 'abc')->hasMatch(); // false
```

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

### Array Input for Regex::replace

Source: https://github.com/spatie/regex/blob/main/README.md

Explains that `Regex::replace` supports array inputs for patterns, replacements, and subjects, behaving similarly to PHP's built-in `preg_replace` function. This allows for multiple replacements in a single operation.

```php
Regex::replace(['/a/', '/b/'], ['c', 'd'], ['abc', 'def'])->result(); // ['cdc', 'def']
```

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

### RegexFailed Exception Handling in PHP

Source: https://context7.com/spatie/regex/llms.txt

Handles errors during regex operations by throwing a `RegexFailed` exception. This exception provides detailed error messages including the pattern, subject, and specific error information, eliminating the need for manual `preg_last_error()` checks. It covers invalid patterns, backtracking limits, and non-existent capture groups.

```php
use Spatie\Regex\Regex;
use Spatie\Regex\Exceptions\RegexFailed;

// Handle invalid pattern errors
try {
    Regex::match('/[invalid/', 'subject');
} catch (RegexFailed $e) {
    echo $e->getMessage();
    // "Error matching pattern `/[invalid/` with subject `subject`. ..."
}

// Handle catastrophic backtracking
try {
    Regex::match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');
} catch (RegexFailed $e) {
    echo $e->getMessage();
    // "Error matching pattern `...` with subject `foobar foobar foobar`. Backtrack limit exhausted"
}

// Handle non-existent capture groups
try {
    $result = Regex::match('/(a)/', 'abc');
    $result->group(5);  // Group 5 doesn't exist
} catch (RegexFailed $e) {
    echo $e->getMessage();
    // "Pattern `/(a)/` with subject `abc` didn't capture a group named 5"
}

// Safe group access with defaults (no exception)
$result = Regex::match('/(a)/', 'abc');
$value = $result->groupOr(5, 'fallback');  // 'fallback'

// Replacement error handling
try {
    Regex::replace('/unclosed(group/', 'replacement', 'subject');
} catch (RegexFailed $e) {
    echo $e->getMessage();
    // "Error replacing pattern `/unclosed(group/` in subject `subject`. ..."
}

// Long subjects are trimmed in error messages (40 chars max)
try {
    $longSubject = str_repeat('a', 100);
    Regex::replace('/invalid', 'b', $longSubject);
} catch (RegexFailed $e) {
    // Subject shown as: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..."
}

```

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

### Retrieving a Captured Group with MatchResult::group

Source: https://github.com/spatie/regex/blob/main/README.md

Shows how to extract the content of a specific captured group from a `MatchResult` using the `group` method. Groups are 1-indexed, and an exception is thrown if the requested group does not exist.

```php
use Spatie\Regex\Regex;

Regex::match('/a(b)c/', 'abc')->group(1); // 'b'
Regex::match('/a(b)c/', 'abc')->group(2); // `RegexFailed` exception
```

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

### Regex::replace - Pattern Replacement in PHP

Source: https://context7.com/spatie/regex/llms.txt

Performs pattern-based string replacement using various methods including simple string replacement, callback functions, array patterns, and replacement limits. It returns a `ReplaceResult` object containing the modified string and the count of replacements made. Supports string and array subjects.

```php
use Spatie\Regex\Regex;
use Spatie\Regex\MatchResult;

// Simple string replacement
$result = Regex::replace('/a/', 'b', 'aabb');
$result->result();  // 'bbbb'
$result->count();   // 2 (number of replacements made)

// Callback replacement with MatchResult
$result = Regex::replace('/a(b)/', function (MatchResult $match) {
    return strtoupper($match->result());
}, 'abc');
$result->result();  // 'ABc'

// Callback with access to captured groups
$result = Regex::replace('/(\w+)@(\w+)\.(\w+)/', function (MatchResult $match) {
    $user = $match->group(1);
    $domain = $match->group(2);
    return "{$user} at {$domain}";
}, 'Email: user@example.com');
$result->result();  // 'Email: user at example'

// Duplicate matched content
$result = Regex::replace('/a/', function (MatchResult $match) {
    return $match->result() . $match->result();
}, 'abc');
$result->result();  // 'aabc'

// Limit number of replacements
$result = Regex::replace('/a/', 'b', 'aaaa', 2);
$result->result();  // 'bbaa'
$result->count();   // 2

// Array of patterns with single replacement
$result = Regex::replace(['/a/', '/b/'], 'c', 'aabb');
$result->result();  // 'cccc'

// Array of patterns with array of replacements
$result = Regex::replace(['/a/', '/b/'], ['x', 'y'], 'aabb');
$result->result();  // 'xxyy'

// Working with array subjects
$subjects = ['apple', 'banana', 'apricot'];
$result = Regex::replace('/a/', 'X', $subjects);
$result->result();  // ['Xpple', 'bXnXnX', 'Xpricot']

// Practical example: Format phone numbers
$result = Regex::replace(
    '/(\d{3})(\d{3})(\d{4})/',
    '($1) $2-$3',
    'Call 5551234567 now!'
);
$result->result();  // 'Call (555) 123-4567 now!'

// Practical example: Slugify text
$text = 'Hello World! This is a Test.';
$result = Regex::replace('/[^a-z0-9]+/i', '-', strtolower($text));
$result->result();  // 'hello-world-this-is-a-test-'

```

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

### Checking for a Match with MatchResult::hasMatch

Source: https://github.com/spatie/regex/blob/main/README.md

Demonstrates the `hasMatch` method of the `MatchResult` class, which returns a boolean indicating whether a regular expression successfully matched the subject.

```php
use Spatie\Regex\Regex;

Regex::match('/abc/', 'abc')->hasMatch(); // true
Regex::match('/def/', 'abc')->hasMatch(); // false
```
Tokens:
Raw