Weave Code
Pcre Laravel Package
composer/pcre
Type-safe wrappers around PHP's preg_* functions that fail loudly instead of returning unexpected nulls. Enforces PREG_UNMATCHED_AS_NULL, simplifies return types for PHPStan and Psalm, and includes a PHPStan extension for better regex analysis.
PCRE wrapping library that offers type-safe preg_* replacements.
Frequently asked questions about Pcre
- How do I install composer/pcre in a Laravel application?
- Run composer require composer/pcre. There is no service provider to register, no config file to publish, and no container binding: the package is plain PSR-4 code, so it works as soon as Composer autoloads it. Version 3.x requires PHP 7.4 or newer, which every currently supported Laravel release satisfies. You can start replacing preg_match and preg_replace calls immediately, one call site at a time.
- Does composer/pcre support Laravel 9, 10, 11, and 12?
- Yes. The package is framework-agnostic and has zero dependencies beyond PHP itself, so it has no Laravel version constraints to conflict with. Laravel 9 through 12 on PHP 8.1+ is fully compatible. It also coexists cleanly with Larastan and other static analysis tooling. Pin to the 3.x line to get the PHPStan extension and the enforced PREG_UNMATCHED_AS_NULL behavior.
- What does PREG_UNMATCHED_AS_NULL change about the $matches array?
- Since version 2.0/3.0 the library always applies PREG_UNMATCHED_AS_NULL, so optional groups that never participated in the match are present in the array as null instead of being omitted or returned as an empty string. Trailing optional groups that used to be absent from the array now appear with a null value, and unmatched interior groups become null rather than an empty string. Code relying on isset($matches[1]) semantics can therefore change behavior silently, and null can leak into typed properties or DTOs. Audit every downstream consumer of $matches before switching, especially where results are persisted.
- Why does composer/pcre throw PcreException instead of returning false?
- Native preg_* functions return false or null on failure, which is easy to ignore and leads to silent wrong output. composer/pcre converts those failures into a Composer\Pcre\PcreException so problems surface immediately instead of corrupting data. The trade-off is that a bad pattern now produces an exception rather than a soft failure, which can turn a validation edge case into a 500. For user-supplied or database-driven patterns, catch PcreException at the boundary and map it to a 422 response or a fallback.
- How do I enable the composer/pcre PHPStan extension with Larastan?
- If phpstan/extension-installer is installed, which is standard in Larastan setups, the bundled extension.neon is registered automatically and needs no configuration. Without the installer, add the extension.neon path to the includes section of your phpstan.neon. Once active, PHPStan infers the shape of the $matches array and validates your patterns at analysis time. That inference is the highest-leverage benefit of the package, so confirm the extension is actually loaded in CI.
- What are the limitations of composer/pcre compared to native preg_* functions?
- The restrictions are documented and narrow: there is no preg_filter, no array $subject for replace operations, and no PREG_SET_ORDER support. You also cannot pass PREG_OFFSET_CAPTURE or PREG_SPLIT_OFFSET_CAPTURE as flags; use matchWithOffsets and splitWithOffsets instead. Any call site relying on those features is a non-mechanical rewrite rather than a rename. Inventory those call sites first to estimate the real effort.
- Should I use Composer\Pcre\Preg or Composer\Pcre\Regex?
- Both wrap the same behavior; the difference is the API style. Preg exposes static methods that mirror preg_* with a by-reference $matches argument, which makes legacy procedural code easy to port. Regex returns immutable result objects such as MatchResult and ReplaceResult, which suits Laravel service classes and action classes where explicit return types are preferred. Mixing both in one codebase is fine, but pick a default per layer to keep things predictable.
- How do I test code that uses composer/pcre's static methods?
- Because Preg methods are static, they are awkward to mock, so stop trying to intercept the calls. Assert on outcomes instead: pass known input strings and check the returned booleans, MatchResult values, or replaced strings. Test the boundary handling of PcreException with deliberately invalid patterns or inputs. If you need seams for testing, wrap the calls in your own small service that the container can resolve.
- Is composer/pcre a replacement for Laravel's Str::match or the regex validation rule?
- No. Laravel's Str::match, Str::matchAll, and the regex validation rule remain preg_*-based, and composer/pcre complements rather than replaces them. Use the package for ad-hoc preg_match and preg_replace calls in form requests, casts, importers, parsers, custom rules, and domain services, which Laravel does not wrap. Reach for the framework helpers when you want Laravel-native behavior, and the package where you want type safety and static analysis support.
- What are the alternatives to composer/pcre for type-safe regex in PHP?
- The README points to rawr/t-regx as the richer API option if you want a full regular expression abstraction rather than a thin wrapper. Native preg_* with careful error handling is the zero-dependency baseline, but it leaves the null and false edge cases in play. composer/pcre's differentiator is that it stays close to the native API while adding a PHPStan extension, so migration cost stays low. For teams already running Larastan, that combination is usually the deciding factor.
Weaver
How can I help you explore Laravel packages today?