Character Solver Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require juy/character-solver
   

2. Register Service Provider: Add Juy\CharacterSolver\ServiceProvider::class to config/app.php under providers.
3. Publish Config (Optional):

   php artisan vendor:publish --provider="Juy\CharacterSolver\ServiceProvider" --tag="config"
   

4. First Use Case: The package automatically converts HTML entities (e.g., ç) to their character equivalents (e.g., ç) globally via middleware. No additional code is needed for basic usage.

Implementation Patterns

Global Middleware Integration

• Automatic Conversion: The package registers a middleware (Juy\CharacterSolver\Middleware\CharacterSolver) by default in Laravel’s HTTP kernel (app/Http/Kernel.php). This middleware runs on every request, converting HTML entities in the response.
• Workflow:
  1. Request → Middleware → Response (with converted characters).
  2. Useful for APIs or frontend responses where entities are unintentionally encoded (e.g., from databases or third-party sources).

Custom Character Replacements

• Extend Config: Modify config/character-solver.php to add/remove replacements:

  'replacements' => [
      'é' => 'é',
      'É' => 'É',
  ],
  

• Dynamic Overrides: Override the config in config/app.php or boot the service provider:

  public function boot()
  {
      $this->app['config']->set('character-solver.replacements', [
          '&custom;' => 'value',
      ]);
  }
  

Manual Conversion (Non-Middleware Use)

• Service Container: Access the solver directly via the container:

  $solver = app('character-solver');
  $converted = $solver->solve('ç ö'); // Returns "ç ö"
  

• Use Case: Convert strings outside HTTP requests (e.g., CLI commands, background jobs).

Integration with Blade Templates

• View Helper: Create a Blade directive for manual conversion:

  Blade::directive('solve', function ($expression) {
      return "<?php echo app('character-solver')->solve({$expression}); ?>";
  });
  

  Usage:

  @solve('ç is converted to ç')
  

Gotchas and Tips

Pitfalls

1. Middleware Overhead:
   • The middleware runs on every request, which may impact performance for high-traffic APIs. Disable it if unused:

     // Remove from $middleware in app/Http/Kernel.php
     \Juy\CharacterSolver\Middleware\CharacterSolver::class,
     

2. Double Conversion:
   • If entities are already converted (e.g., by another package), the solver may produce incorrect results. Test edge cases like ç (should remain ç if not configured).
3. Deprecated Laravel Versions:
   • Only tested on Laravel 5.1–5.3. May require adjustments for newer versions (e.g., middleware registration changes).

Debugging

• Log Unhandled Entities: Extend the solver to log unknown entities:

  // In ServiceProvider::boot()
  $solver = $this->app->make('character-solver');
  $solver->setCallback(function ($entity) {
      Log::warning("Unhandled entity: {$entity}");
  });
  

• Test Config: Verify replacements work as expected:

  $this->assertEquals('ç', app('character-solver')->solve('ç'));
  

Extension Points

1. Custom Solver Logic: Replace the default solver by binding a new instance in the service provider:

   $this->app->bind('character-solver', function () {
       return new \App\CustomCharacterSolver();
   });
   

2. Add Context-Aware Replacements: Use the callback to conditionally replace entities based on request context (e.g., locale):

   $solver->setCallback(function ($entity, $context) {
       if ($context['locale'] === 'tr' && $entity === '&i') {
           return 'ı';
       }
       return null; // Skip default replacement
   });
   

3. Database Integration: Use the solver in model observers or accessors to normalize stored entities:

   public function getNameAttribute($value)
   {
       return app('character-solver')->solve($value);
   }
   

Configuration Quirks

• Case Sensitivity: The default config uses uppercase entity names (e.g., Ç). Ensure consistency when adding new replacements.
• Priority: Custom replacements in the config override defaults. Order matters if using the callback.

Performance Tips

• Cache Config: Publish the config and cache it to avoid reloading on every request:

  php artisan config:cache
  

• Selective Middleware: Restrict the middleware to specific routes:

  Route::middleware(['character-solver'])->group(function () {
      // Routes where conversion is needed
  });