Pcre Laravel Package

Product Decisions This Supports

• Silent-failure hardening as a roadmap item. Every preg_match/preg_replace call that can return null or false is an unhandled branch. Adopting composer/pcre converts those into PcreExceptions you can catch at a boundary (request validation, job handler, importer), decide on, and log. This is a tractable, low-risk reliability epic that maps to a measurable goal: reduce preg_*-related production errors and undefined-index warnings to zero.
• Build vs. buy for internal regex utilities. Teams routinely hand-roll a RegexHelper or SafeRegex class. This package is that class, maintained by the Composer maintainers, MIT-licensed, with a stable API since 2.0. Decision: buy. Spend the engineering budget on product work instead of maintaining a wrapper.
• Static-analysis maturity initiative. The PHPStan extension (vendor/composer/pcre/extension.neon) infers precise $matches array shapes from the regex literal and validates the pattern itself, plus subject narrowing (3.4.0+, PHPStan 2.2.2+). This directly unlocks raising the static-analysis baseline — a prerequisite for safe refactors in a large Laravel codebase and a durable velocity win rather than a one-off fix.
• Feature areas where the decision pays off most:
  • Input/form validation and normalization (slugs, phone numbers, identifiers) — exceptions give clear validation failure signals.
  • Ingestion/parsing pipelines (log lines, CSV/TSV quirks, imported files, diff/patch text) — partial matches must fail loudly, not silently produce empty records.
  • Templating and placeholder substitution — a null from replace today quietly writes "null" into stored data.
  • PII redaction/masking and data-retention scrubbing — a silent failure is a compliance incident, not a cosmetic bug.
  • Data migration/backfill scripts — silent mismatches skew historical data permanently.
• Regex authoring standards. *StrictGroups variants let you declare "this pattern's groups are always present," turning optional-capture-group bugs into loud, early exceptions and removing isset()/!== '' defensive code. That is an enforceable coding guideline, not just a library choice.
• Version-pinning decision. 3.x requires PHP 7.4+; 2.x covers PHP 7.2. Choose based on the oldest runtime still in the support matrix for Laravel versions you ship; note both branches received PHPStan 2 and PHP 8.4 deprecation fixes.

When to Consider This Package

Adopt when:

• Your PHP floor is 7.4 (3.x) or 7.2 (2.x) and you are on a maintained Laravel version.
• Regex usage is non-trivial — dozens or hundreds of call sites — and you already have visible symptoms: null/false return handling, isset($matches[3]), TypeErrors from array offsets, or PHPStan/Psalm suppressions around preg_*.
• Static analysis is part of the pipeline (PHPStan is the first-class target; the extension is PHPStan-specific).
• You want exceptions over sentinel returns and can place try/catch (PcreException) at sensible boundaries. This is an architectural preference worth validating with the team before committing.
• You need predictable match-array shape (all groups present, null when unmatched) — the library always sets PREG_UNMATCHED_AS_NULL, which removes the "empty string vs. no match" ambiguity.
• A quick check of composer.lock shows it is already present transitively; incremental cost is then effectively zero.

Look elsewhere or scope down when:

• You need a richer regex API (named-pattern objects, fluent builders, better error messages) — rawr/t-regx is the explicit alternative the README points to.
• You rely on features the wrapper deliberately drops: preg_filter, array $subject for replace*, PREG_SET_ORDER in matchAll, and offset flags mixed into the generic match/matchAll/split signatures.
• You need ReDoS protection. This library is type-safe, not runtime-safe: it does not add timeouts, backtrack limits, or sandboxing of untrusted/user-supplied patterns, and it does not cache or precompile patterns. If untrusted patterns are in scope, that is a separate decision with a much larger risk profile.
• The codebase has so few regex call sites that added indirection and a new exception type cost more than they save; or existing behavior depends on nulls propagating and you cannot add error handling during the current cycle.
• You cannot accept a new exception type in hot paths (per-request tight loops) until you've measured it — worth a spike, though the wrapper is thin enough that overhead is typically negligible.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can eliminate a recurring class of production bugs — regex operations that fail silently and write empty or null data — at essentially no cost. composer/pcre is a small, MIT-licensed, actively maintained wrapper around PHP's regex functions, maintained by the people who build Composer itself. It replaces silent failures with catchable exceptions and improves our static-analysis coverage, which reduces defect escape rate and speeds up refactoring across the whole codebase. It is a library swap, not a product change: no customer-visible behavior changes, no new infrastructure, days not quarters. Success is measurable: zero preg_*-attributed errors in production and a higher PHPStan level enforced in CI.

For engineering leadership: Thin, drop-in replacement for preg_* via Preg:: and Regex:: static APIs; always applies PREG_UNMATCHED_AS_NULL; throws Composer\Pcre\PcreException on failure; *StrictGroups variants for patterns with guaranteed groups; result objects (MatchResult, ReplaceResult) as an alternative to by-ref $matches. Ships a PHPStan extension for precise match types and regex validation. Known, documented limitations (no preg_filter, no array subjects in replace*, no PREG_SET_ORDER) mean we adopt it with a written migration checklist and a code-style rule rather than a blanket find-and-replace.

For the team: Migration is mechanical and reviewable — swap preg_* for Preg::*, add try/catch (or a helper that maps PcreException to a domain error) where failure is a real product state, enable extension.neon in PHPStan, and pin the major version compatible with our PHP floor. Track progress by call sites migrated and by a decrease in defensive null/false checks.