Regex Tools Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require apie/regex-tools
   

   No additional configuration is required for basic usage.

2. First Use Case Import the core class and use it to validate or manipulate regex patterns:

   use Apie\RegexTools\RegexTools;
   
   $regex = new RegexTools('/^[a-zA-Z0-9]+$/');
   $isValid = $regex->isValid(); // Check if the regex is syntactically correct
   

3. Where to Look First

   • Source Code: The package is minimal, so reviewing src/RegexTools.php directly is the best starting point.
   • Monorepo Context: Since this is part of the Apie monorepo, check the Apie documentation for broader use cases.

Implementation Patterns

Core Workflows

1. Regex Validation Validate regex syntax before execution to avoid runtime errors:

   $regex = new RegexTools('/^[a-z]+$/');
   if ($regex->isValid()) {
       preg_match($regex->getPattern(), $input);
   }
   

2. Pattern Manipulation Modify or extend regex patterns dynamically:

   $regex = new RegexTools('/\d{3}-\d{4}/');
   $regex->setPattern('/\d{3}-\d{4}-\d{4}/'); // Update pattern
   

3. Integration with Laravel Use in validation rules, form requests, or middleware:

   use Apie\RegexTools\RegexTools;
   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($request->all(), [
       'username' => ['regex:/^[a-zA-Z0-9_]{4,20}$/', function ($attribute, $value, $fail) {
           $regex = new RegexTools('/^[a-zA-Z0-9_]{4,20}$/');
           if (!$regex->isValid()) {
               $fail('Invalid regex pattern.');
           }
       }]
   ]);
   

4. Testing Regex Logic Unit test regex patterns before deploying:

   use Apie\RegexTools\RegexTools;
   use PHPUnit\Framework\TestCase;
   
   class RegexTest extends TestCase {
       public function testValidRegex() {
           $regex = new RegexTools('/^[a-z]+$/');
           $this->assertTrue($regex->isValid());
       }
   }
   

Gotchas and Tips

Pitfalls

1. No Public Documentation The package lacks formal docs, so rely on the source code for usage details. Expect minimal error messages if misused.

2. Monorepo Dependency Since this is part of the Apie monorepo, updates may require changes in the main repository. Monitor PRs there for breaking changes.

3. Limited Features The package is lightweight—only provides basic regex validation and manipulation. For advanced features (e.g., regex explanation, debugging), consider alternatives like janusz/regex.

4. No Laravel-Specific Helpers While usable in Laravel, the package doesn’t include Blade directives, service providers, or Artisan commands. You’ll need to wrap logic manually.

Debugging Tips

• Validate Early Always call isValid() before using the regex to avoid runtime preg_* errors:

  if (!$regex->isValid()) {
      throw new \InvalidArgumentException('Invalid regex pattern.');
  }
  

• Pattern Escaping If dynamically constructing regex patterns, escape user input to prevent injection:

  $userInput = '/test/';
  $safePattern = preg_quote($userInput, '/');
  $regex = new RegexTools("/$safePattern/");
  

Extension Points

1. Custom Validators Extend RegexTools to add domain-specific validation:

   class CustomRegexTools extends RegexTools {
       public function isEmailValid() {
           $this->setPattern('/^[^\s@]+@[^\s@]+\.[^\s@]+$/');
           return $this->isValid();
       }
   }
   

2. Integration with Apie If using other Apie packages, explore how regex-tools might integrate (e.g., for API request validation).

3. Logging Log invalid regex patterns for debugging:

   if (!$regex->isValid()) {
       \Log::error("Invalid regex: {$regex->getPattern()}");
   }