String Encoder Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require devanoxltd/string-encoder
   

   Add to composer.json under require if using Laravel’s autoloader.

2. First Use Case: Convert a string to UTF-8 (default) or another encoding:

   use StringEncoder\Encoder;
   
   $encoder = new Encoder();
   $utf8String = $encoder->convert()->fromString("Café")->toString();
   

3. Where to Look First:

   • Encoder class: Core functionality for conversions.
   • MB\Regex class: For multibyte regex operations.
   • docs/encoding.md: Detailed API reference for conversions, files, and DTOs.
   • docs/regex.md: Guide for Unicode-aware regex patterns.

Implementation Patterns

Usage Patterns

1. String Conversion Workflow

• Basic Conversion:

  $encoder = new Encoder();
  $result = $encoder->convert()->fromString($input)->toString();
  

• Explicit Encoding:

  $encoder->setSourceEncoding('ISO-8859-1')->setTargetEncoding('UTF-8');
  $result = $encoder->convert()->fromString($input)->toString();
  

2. File Handling

• Read from File:

  $content = $encoder->convert()->fromFile('path/to/file.txt')->toString();
  

• Write to File:

  $encoder->convert()->fromString($content)->toFile('path/to/output.txt');
  

3. DTO-Based Processing

• Extract Encoding Metadata:

  $dto = $encoder->convert()->fromString($input)->toDTO();
  $encoding = $dto->getEncodingDTO()->getEncoding(); // e.g., "UTF-8"
  

4. Multibyte Regex

• Sanitize Unicode Strings:

  $dto = $encoder->convert()->fromString($input)->toDTO();
  $regex = new \StringEncoder\MB\Regex();
  $sanitized = $regex->replace('[^\p{L}\p{N}]', '', $dto)->getString();
  

5. Proxy for Static Access

• Mount Encoder Globally:

  \StringEncoder\Proxy\Encoder::mountFromEncoding('ISO-8859-1', 'UTF-8');
  $result = \StringEncoder\Proxy\Encoder::convert()->fromString($input)->toString();
  

Integration Tips

Laravel-Specific Patterns

1. Service Provider Binding: Bind the encoder to Laravel’s container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(\StringEncoder\Contracts\EncoderInterface::class, function () {
           return new \StringEncoder\Encoder();
       });
   }
   

   Use in controllers/services:

   use StringEncoder\Contracts\EncoderInterface;
   
   public function __construct(EncoderInterface $encoder) {
       $this->encoder = $encoder;
   }
   

2. Form Request Validation: Sanitize multibyte strings in form requests:

   use StringEncoder\MB\Regex;
   
   public function rules()
   {
       return [
           'name' => 'required|string|regex:/^[^\p{C}\p{Z}]+$/u',
       ];
   }
   
   public function withValidator($validator)
   {
       $validator->after(function ($validator) {
           $regex = new Regex();
           $dto = $this->encoder->convert()->fromString($this->name)->toDTO();
           $this->name = $regex->replace('[^\p{L}\p{N}\p{M}]', '', $dto)->getString();
       });
   }
   

3. Eloquent Model Observers: Normalize encoding for database operations:

   // app/Observers/StringObserver.php
   public function saving(Model $model)
   {
       if (method_exists($model, 'getTextAttribute')) {
           $text = $model->{$model->getTextAttribute()};
           $model->{$model->getTextAttribute()} =
               $this->encoder->convert()->fromString($text)->toString();
       }
   }
   

4. API Response Filtering: Ensure consistent encoding in API responses:

   // app/Http/Middleware/EnsureUtf8.php
   public function handle($request, Closure $next)
   {
       $response = $next($request);
       $content = $response->getContent();
       $response->setContent(
           $this->encoder->convert()->fromString($content)->toString()
       );
       return $response;
   }
   

5. Command-Line Artisan Commands: Batch-process files for encoding consistency:

   // app/Console/Commands/NormalizeEncodings.php
   public function handle()
   {
       $files = Storage::files('public/uploads');
       foreach ($files as $file) {
           $content = $this->encoder->convert()->fromFile($file)->toString();
           Storage::put($file, $content);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Encoding Detection Assumptions:

   • The package defaults to UTF-8 if source encoding isn’t specified. Explicitly set setSourceEncoding() for non-UTF-8 inputs to avoid silent corruption.
   • Example Pitfall:

     // ❌ Silent failure: Assumes UTF-8 but input is ISO-8859-1
     $encoder->convert()->fromString("Café")->toString(); // May output "Café"
     

   • Fix:

     $encoder->setSourceEncoding('ISO-8859-1')->convert()->fromString("Café")->toString();
     

2. Regex Limitations:

   • The MB\Regex class requires a MBStringDTO (not raw strings). Forgetting to convert first causes InvalidArgumentException.
   • Example Pitfall:

     // ❌ Throws exception: Regex expects DTO, not string
     $regex = new \StringEncoder\MB\Regex();
     $regex->replace('[^A-Za-z]', '', "Café"); // Fails
     

   • Fix:

     $dto = $encoder->convert()->fromString("Café")->toDTO();
     $regex->replace('[^A-Za-z]', '', $dto)->getString();
     

3. File Handling Quirks:

   • Permissions: Writing to files requires proper permissions (e.g., storage/logs/ may need chmod 775).
   • BOM Handling: The removeUTF8BOM option is off by default. Enable it if your files include BOMs:

     $encoder->setOptions((new \StringEncoder\Options())->setRemoveUTF8BOM(true));
     

4. Case Sensitivity:

   • Encoding names are case-sensitive by default (e.g., utf-8 ≠ UTF-8). Use setCaseSensitiveEncoding(false) to normalize:

     $encoder->setOptions((new \StringEncoder\Options())->setCaseSensitiveEncoding(false));
     $encoder->setTargetEncoding('utF-8'); // Auto-corrected to "UTF-8"
     

5. Proxy Caching:

   • The mountFromEncoding() method creates static aliases. Overwriting them requires unmounting first:

     \StringEncoder\Proxy\Encoder::unmount();
     \StringEncoder\Proxy\Encoder::mountFromEncoding('ISO-8859-1', 'UTF-8');
     

Debugging Tips

1. Verify Encodings: Use getEncodingDTO() to inspect encoding metadata:

   $dto = $encoder->convert()->fromString($input)->toDTO();
   dump($dto->getEncodingDTO()->getEncoding()); // Debug current encoding
   

2. Handle Exceptions: Catch InvalidEncodingException for unsupported encodings:

   try {
       $encoder->setTargetEncoding('INVALID-ENCODING');
       $encoder->convert()->fromString("Test")->toString();
   } catch (\StringEncoder\Exceptions\InvalidEncodingException $e) {
       Log::error("Unsupported encoding: " . $e->getEncoding());
   }
   

3. Regex Debugging: Test patterns with preg_match first to ensure compatibility:

   if (!preg_match('/[^\p{L}]/u', "Café")) {
       throw new \RuntimeException("Regex pattern unsupported");
   }
   

4. Performance:

   • Avoid repeated conversions: Cache Encoder instances (e.g., as a singleton).
   • Batch processing: For large files, read/write in chunks: