Regex Laravel Package

Product Decisions This Supports

• Standardization of regex logic across Laravel applications, eliminating inconsistencies in pattern matching, validation, and text processing workflows. Reduces technical debt by replacing ad-hoc preg_* calls with a type-safe, maintainable API.
• Developer productivity boost by abstracting repetitive regex operations (e.g., validation, parsing) into reusable methods like Regex::test(), Regex::extract(), and Regex::replace(). Enables faster iteration in features like:
  • Form validation (e.g., custom rules for emails, slugs, or API payloads).
  • Data parsing (e.g., extracting structured data from logs, CSV, or JSON).
  • Text sanitization (e.g., stripping HTML tags, normalizing strings).
• Risk reduction in regex-heavy codebases by:
  • Enforcing safer defaults (e.g., handling preg_last_error() internally).
  • Eliminating ambiguous return values (e.g., preg_match’s null/false ambiguity).
  • Providing structured capture groups for cleaner data extraction.
• Alignment with Laravel’s ecosystem by offering a lightweight, dependency-free solution that integrates with:
  • Validation (e.g., custom rules, FormRequest parsing).
  • Service layers (e.g., parsing API responses or user-generated content).
  • Blade templates (e.g., regex-based filters or directives).
• Roadmap justification for "buy vs. build":
  • Buy: This package is a low-effort, high-impact solution for teams already using Laravel/PHP. Avoids reinventing a regex wrapper while adding type safety and consistency.
  • Build: Only consider if the package lacks critical features (e.g., Laravel-specific integrations) or if performance benchmarks reveal unacceptable overhead.
• Key use cases:
  • Validation: Replace preg_match in custom validation rules (e.g., Rule::custom('regex', fn($attr, $value) => Regex::test('/pattern/', $value))).
  • APIs: Parse and transform request/response payloads (e.g., extracting IDs from JSON strings).
  • Content Processing: Sanitize or normalize user-generated text (e.g., removing unwanted characters, extracting hashtags).
  • Logs/Monitoring: Extract structured data from unformatted logs (e.g., timestamps, error codes).
  • CLI Tools: Add regex capabilities to Artisan commands (e.g., log analysis, migration helpers).

When to Consider This Package

Adopt if:

• Your Laravel application heavily relies on regex for validation, parsing, or text processing, and inconsistencies or bugs are a recurring issue.
• Teams spend excessive time debugging preg_* calls, handling edge cases (e.g., preg_last_error()), or maintaining repetitive regex logic.
• You prioritize developer experience over micro-optimizations (the package adds negligible runtime overhead compared to raw preg_*).
• Your project is greenfield or modular, allowing you to enforce the standardized API from the start (e.g., new validation rules, parsing utilities).
• You need type safety for regex operations (e.g., typed capture groups, structured return values) to reduce runtime errors.
• Laravel-specific integrations (e.g., validation rules, Blade directives) are a secondary priority—the package can be extended post-adoption.

Look elsewhere if:

• Your use case requires advanced PCRE features (e.g., recursive patterns, complex lookarounds) that this wrapper doesn’t support. Benchmark against raw preg_* first.
• Performance is critical (e.g., high-throughput parsing in background jobs). Test the package’s overhead against native preg_*—though the abstraction should be minimal.
• You’re already using a dedicated parsing library (e.g., Symfony’s StringUtil, league/html-to-markdown) that handles regex internally. Avoid layering abstractions.
• Your team lacks PHP regex expertise; this package assumes familiarity with PCRE syntax and may introduce a learning curve.
• The codebase is monolithic with deeply embedded preg_* calls, making refactoring to the new API prohibitively costly. Prioritize incremental adoption instead.
• You need Laravel-native integrations (e.g., out-of-the-box validation rule support, Blade directives). The package requires custom wrappers for these cases.

How to Pitch It (Stakeholders)

For Executives/Product Owners:

*"This package standardizes regex usage across our Laravel codebase, cutting bugs and improving maintainability—especially in validation, parsing, and text processing. By replacing raw preg_* calls with a safer, type-safe API, we reduce repetitive boilerplate and make regex logic easier to debug and maintain. It’s a low-risk, high-reward investment that aligns with our focus on developer productivity and code quality.

Why now?

• Our current regex-heavy features (e.g., form validation, log parsing) are prone to inconsistencies and edge-case bugs.
• Adopting this package would reduce technical debt and accelerate development for text-processing tasks.
• The MIT license and lightweight design mean minimal risk—we can pilot it in one module before rolling out broadly.

Ask: Approval to adopt as a core dependency for new features or refactors involving regex, with a budget for minor onboarding (e.g., documentation, team training)."

For Engineers/Tech Leads:

*"This package solves three critical problems in our Laravel codebase:

1. Safety: Eliminates preg_* pitfalls (e.g., silent failures, unclear return values) with structured methods like:

   • Regex::test($pattern, $input) → Returns bool (no more null/false ambiguity).
   • Regex::extract($pattern, $input) → Returns typed arrays for capture groups.
   • Regex::replace($pattern, $replacement, $input) → Safer than preg_replace.

2. Consistency: Standardizes regex patterns across validation, parsing, and utilities—no more copy-pasted preg_match snippets. Example:

   // Before (inconsistent)
   if (preg_match('/^[A-Za-z0-9]+$/', $input)) { ... }
   if (preg_match('#\d{3}-\d{2}-\d{4}#', $ssn)) { ... }
   
   // After (standardized)
   if (Regex::test('/^[A-Za-z0-9]+$/', $input)) { ... }
   if (Regex::test('/\d{3}-\d{2}-\d{4}/', $ssn)) { ... }
   

3. Readability: Fluent methods are self-documenting and easier to debug:

   $cleaned = Regex::replace()
       ->pattern('/[^\w\s]/u')
       ->with('')
       ->in($userInput);
   

Proposal:

• Pilot in one high-impact area: Start with user input validation or log parsing to measure developer satisfaction and bug reduction.
• Replace custom regex utilities: Deprecate in-house wrappers or ad-hoc preg_* calls in favor of this standardized API.
• Add to style guide: Enforce the package as a required dependency for new text-processing logic.

Trade-offs:

• Minimal performance impact: Benchmark if critical (e.g., high-volume API parsing), but expect negligible overhead.
• Refactoring effort: Existing preg_* calls will need updates, but this reduces long-term tech debt.
• Laravel integrations: Requires custom wrappers for validation rules or Blade directives (but this is a one-time effort).

Next Steps:

1. Benchmark the package against raw preg_* for our top 3 regex-heavy use cases.
2. Prototype a Laravel validation rule using the package (e.g., RegexRule).
3. Propose a phased adoption plan (e.g., new features first, then legacy code)."*

For Developers:

*"This package makes regex safer, cleaner, and more maintainable in Laravel. Here’s how it helps you:

✅ No more preg_* headaches:

• Regex::test() → Always returns bool (no null/false confusion).
• Regex::extract() → Returns typed arrays for capture groups (e.g., ['group1' => 'value']).

✅ Less boilerplate:

// Before
$matches = [];
if (preg_match('/(\d{3})-(\d{2})-(\d{4})/', $ssn, $matches)) {
    $area = $matches[1];
    $exchange = $matches[2];
}

// After
$parts = Regex::extract('/(\d{3})-(\d{2})-(\d{4})/', $ssn);
$area = $parts['1']; // Typed access!

✅ Easier debugging:

• Clear error messages for invalid patterns (e.g., Regex::test() throws exceptions on failure).
• Structured return values reduce off-by-one errors in capture groups.

How to start:

1. Replace preg_match with Regex::test() in validation rules.
2. Use Regex::extract()