Download the PHP package liquidrazor/liquid-regex without Composer

LiquidRazor Regex

An intuitive, small, and fast regular expression helper for PHP 8.3+ with clean result objects and a few ergonomic utilities around PCRE.

Package: liquidrazor/liquid-regex • License: MIT

✨ Features

• Fluent, tiny API for matching and replacing.
• Lazy, rewindable match results with Iterator, ArrayAccess, Countable, and JsonSerializable support.
• Deterministic result shapes via ResultTypes (numeric, associative, or both) and a STRICT filter.
• PCRE helpers to check version/JIT support and validate pattern syntax.
• Exceptions you can catch with informative messages bubbled from PCRE.

🚧 Requirements

• PHP 8.3 or newer
• PCRE (bundled with PHP)

📦 Installation

The library is namespaced under LiquidRazor\Regex and PSR‑4 autoloaded per composer.json.

🧠 Concepts at a Glance

Regex — main entry point

The Regex class is the main façade. It also memoizes compiled instances by pattern:

From there you can match or replace (see examples below).

ResultTypes — control your result shape

Choose how match arrays are exposed:

This lets you request exactly the view you need (e.g., only named groups). You can bit‑OR flags:

Flags (PCRE capture flags)

Extra capture behavior forwarded to PCRE:

🚀 Quick start

1) Find the first match

3) Replace

LiquidRazor\Regex\Result\Replace\Result implements Stringable. If the replacement result is an array (e.g., when replacing in arrays), __toString() returns JSON.

🎛️ Controlling result shapes

The LiquidRazor\Regex\Result\Matches\Result object exposes a lazy, memoized sequence of match entries. You decide which keys appear using ResultTypes:

• INDEXED: keeps only integer keys (0,1,2…). With STRICT, filters out any non-integer keys.
• ASSOCIATIVE: keeps only named group keys. With STRICT, filters out numeric-looking strings.
• BOTH: includes both numeric and associative keys (default). Combine with STRICT to prune mixed keys.

The object supports:

• Iterator (rewindable)
• ArrayAccess (read-only; attempting to mutate throws ImmutableException)
• Countable
• JsonSerializable

If there was no match, the Result is empty with didMatch === false (safe to iterate/count/JSON-encode).

🧩 PCRE helpers

Use the Pcre static utility for environment checks:

Note: isValid() only checks a basic /.../flags shape, also does compile the pattern and checks the result. If compilation fails, it returns false.

⚠️ Exceptions

The library centralizes PCRE errors through LiquidRazor\Regex\Exception classes:

• PcreException – wraps preg_last_error() & message
• Exception – currently extends PcreException for convenience
• ImmutableException – thrown on attempts to mutate read-only results

In practice, most API calls either return a Result object or throw on internal PCRE errors (e.g., bad backtrack limit).

📚 API sketch

The following reflects the current source structure at a high level. Some signatures may evolve.

• Regex::compiled(string $pattern): Regex
• Regex->match(string $haystack, int $resultType = ResultTypes::BOTH, Flags ...$captureFlags): LiquidRazor\Regex\Result\Matches\Result
• Regex->replace(string|array $subject, string|callable $replacement, int $limit = -1): LiquidRazor\Regex\Result\Replace\Result

Result types:

• LiquidRazor\Regex\Result\Matches\Result
  • Properties: pattern, haystack, didMatch
  • Interfaces: Iterator, ArrayAccess (read-only), Countable, JsonSerializable
• LiquidRazor\Regex\Result\Replace\Result implements Stringable
  • Properties: pattern, count, replaced
  • Casting: (string)$result yields the final string (or JSON if array)

Helpers:

• LiquidRazor\Regex\Pcre
  • versionString(): string
  • isJitSupported(): bool
  • isValid(?string $pattern): bool

Enums / constants:

• LiquidRazor\Regex\Lib\Flags — Default, OffsetCapture, UnmatchedAsNull
• LiquidRazor\Regex\Result\ResultTypes — INDEXED, ASSOCIATIVE, BOTH, STRICT

✅ Examples

Only named groups, strictly

With offsets and nulls for unmatched

🧪 Testing

You can plug this library into any test runner. The result objects are easy to snapshot by JSON encoding.

🤝 Contributing

• Open an issue for design/API discussions.
• Keep the API minimal and predictable.
• PRs welcome with tests and docs for new behavior.

📄 License

MIT © LiquidRazor