README

An intuitive, readable, and powerful fluent interface for working with Regular Expressions in PHP.

Features

• Fluent API: Chain methods to build complex patterns naturally.
• Readable Syntax: Methods like beginsWith, contains, digit, and or make your intent clear.
• Lookahead Support: Easily implement complex "must contain" logic without the headache.
• Atomic & Reusable: Build patterns using closures and reuse them across your project.
• Built-in Helpers: One-call solutions for common tasks like email, url, uuid, and more.
• Safe by Default: Automatically handles preg_quote where necessary.

Installation

You can install the package via composer:

composer require damilarekoiki/phpregex

Usage

Basic Example

Checking if a string is a valid invoice number (starts with INV-, followed by digits, and ends with .pdf):

require_once 'vendor/autoload.php';

use DamilareKoiki\PhpRegex\Regex;

$regex = Regex::build()
    ->beginsWith('INV')
    ->then('-')
    ->digits()
    ->endsWith('.pdf');

if ($regex->matches('INV-12345.pdf')) {
    // It's a match!
}

Powerful Lookaheads

Validate a password: must contain at least one digit, one uppercase letter, and be at least 8 characters long:

$regex = Regex::build()
    ->containsDigit()
    ->containsUppercaseLetter()
    ->containsAtLeastSequencesOf(fn(Regex $regex) => $regex->anything(), 8);

$regex->matches('Pass1234'); // true

Data Extraction & Replacement

$regex = Regex::build()->digits(); // A consecutive sequence of digits

// Count matches
$count = $regex->count('There are 12 apples and 34 oranges.'); // 2

// Replace matches
$clean = $regex->replace('Order #12345', 'XXXXX'); // "Order #XXXXX"

// Using callbacks for replacement
$result = $regex->replace('Score: 10', function(array $match): int {
    return (int)$match[0] * 2;
}); // "Score: 20"

API Reference

Foundation

Positional & Boundaries

Presence (Lookaheads)

Exact Matches (Consuming)

Quantifiers

Logic & Conditionals

Flags

Helpers (Presets)

Highly optimized patterns for common use cases:

Complex Sequences

Use containsSequence to match a sequence of patterns anywhere in the string:

$regex = Regex::build()->containsSequence(function (Sequence $sequence): void {
    $sequence->then('Step 1')
      ->then(fn(Regex $regex) => $regex->digits())
      ->then('Finished');
});

Matches Step 123Finished, abc Step 1562890Finished, Step 123Finished def.

Consuming vs. Non-Consuming Patterns

Patterns in this library generally fall into two categories:

• Consuming Patterns: Methods like then(), digit(), or anyOf() match and consume characters. They move the regex "cursor" forward.
• Non-Consuming Patterns (Lookaheads): Methods in the Presence category (e.g., contains*() methods) and and() are zero-width assertions. They check if a pattern exists without actually matching or "eating" the characters.

Important: count() and replace()

Because non-consuming patterns (Lookaheads) match zero characters, they do not work as expected with count() and replace():

• count($subject): A lookahead might match once at a specific position but won't "progress" through the string.
• replace($subject, $replacement): Since no characters are consumed, replace() will insert the replacement text at the matched position instead of replacing existing text.

Alternative: Use Exact Matches (Consuming) if you need to count or replace specific substrings.

// ❌ This will insert 'bar' at the start of the string if 'foo' exists anywhere.
Regex::build()->contains('foo')->replace('I have foo', 'bar');

// ✅ This will replace 'foo' with 'bar'.
Regex::build()->then('foo')->replace('I have foo', 'bar');

Testing

The package is thoroughly tested with Pest PHP.

composer test

License

The MIT License (MIT). Please see License File for more information.