, (*1)
Making regex great again
, (*2)
Php's built in preg_* functions require some odd patterns like passing variables by reference and treating false or null values as errors. spatie/regex provides a cleaner interface for preg_match, preg_match_all, preg_replace and preg_replace_callback., (*3)
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'
// Using `matchAll`
Regex::matchAll('/a/', 'abcabc')->hasMatch(); // true
Regex::matchAll('/a/', 'abcabc')->results(); // Array of `MatchResult` objects
// Using replace
Regex::replace('/a/', 'b', 'abc')->result(); // 'bbc';
Regex::replace('/a/', function (MatchResult $result) {
return $result->result() . 'Hello!';
}, 'abc')->result(); // 'aHello!bc';
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website., (*4)
Support us
, (*5)
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products., (*6)
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall., (*7)
Installation
You can install the package via composer:, (*8)
``` bash
composer require spatie/regex, (*9)
## Usage
### Matching a pattern once
Matches a pattern on a subject. Returns a `MatchResult` object for the first match.
```php
/**
* @param string $pattern
* @param string $subject
*
* @return \Spatie\Regex\MatchResult
*/
Regex::match(string $pattern, string $subject): MatchResult
MatchResult::hasMatch(): bool
Checks if the pattern matches the subject., (*10)
Regex::match('/abc/', 'abc')->hasMatch(); // true
Regex::match('/def/', 'abc')->hasMatch(); // false
MatchResult::result(): string
Return the full match that was made. Returns null if no match was made., (*11)
Regex::match('/abc/', 'abc')->result(); // 'abc'
Regex::match('/def/', 'abc')->result(); // null
MatchResult::group(int $id): string
Return the contents of a captured group (with a 1-based index). Throws a RegexFailed exception if the group doesn't exist., (*12)
Regex::match('/a(b)c/', 'abc')->group(1); // 'b'
Regex::match('/a(b)c/', 'abc')->group(2); // `RegexFailed` exception
Matching all occurences of a pattern
Matches a pattern on a subject. Returns a MatchAllResult object containing all matches., (*13)
/**
* @param string $pattern
* @param string $subject
*
* @return \Spatie\Regex\MatchAllResult
*/
public static function matchAll(string $pattern, string $subject): MatchAllResult
MatchAllResult::hasMatch(): bool
Checks if the pattern matches the subject., (*14)
Regex::matchAll('/abc/', 'abc')->hasMatch(); // true
Regex::matchAll('/abc/', 'abcabc')->hasMatch(); // true
Regex::matchAll('/def/', 'abc')->hasMatch(); // false
MatchAllResult::results(): array
Returns an array of MatchResult objects., (*15)
$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'
Replacing a pattern in a subject
Replaces a pattern in a subject. Returns a ReplaceResult object., (*16)
/**
* @param string|array $pattern
* @param string|array|callable $replacement
* @param string|array $subject
* @param int $limit
*
* @return \Spatie\Regex\ReplaceResult
*/
public static function replace($pattern, $replacement, $subject, $limit = -1): ReplaceResult
ReplaceResult::result(): mixed
Regex::replace('/a/', 'b', 'abc')->result(); // 'bbc'
Regex::replace also works with callables. The callable will receive a MatchResult instance as it's argument., (*17)
Regex::replace('/a/', function (MatchResult $matchResult) {
return str_repeat($matchResult->result(), 2);
}, 'abc')->result(); // 'aabc'
Patterns, replacements and subjects can also be arrays. Regex::replace behaves exactly like preg_replace in those instances., (*18)
Error handling
If anything goes wrong in a Regex method, a RegexFailed exception gets thrown. No need for checking preg_last_error()., (*19)
Testing
bash
$ composer test, (*20)
Changelog
Please see CHANGELOG for more information on what has changed recently., (*21)
Contributing
Please see CONTRIBUTING for details., (*22)
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities., (*23)
Postcardware
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using., (*24)
Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium., (*25)
We publish all received postcards on our company website., (*26)
Credits
License
The MIT License (MIT). Please see License File for more information., (*27)
Wallogit.com
