Urlizer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aferrandini/urlizer
   

   Add to config/app.php under providers (if not auto-discovered):

   Aferrandini\Urlizer\UrlizerServiceProvider::class,
   

2. Publish Config (optional):

   php artisan vendor:publish --provider="Aferrandini\Urlizer\UrlizerServiceProvider"
   

   Config file: config/urlizer.php (default: lowercase, hyphen separator, no accents).

3. First Use Case: Generate a slug from a title in a controller or blade:

   use Aferrandini\Urlizer\Facades\Urlizer;
   
   $slug = Urlizer::make('Hello World!'); // Output: "hello-world"
   

Where to Look First

• Facade: Urlizer::make($string) for quick usage.
• Config: config/urlizer.php for custom rules (e.g., separator, case).
• Service Provider: Registers the facade and config.

Implementation Patterns

Core Workflows

1. Slug Generation:

   • Basic Usage:

     $slug = Urlizer::make('Café au Lait'); // "cafe-au-lait" (default)
     

   • Custom Config:

     Urlizer::setOptions(['separator' => '_', 'lowercase' => false]);
     $slug = Urlizer::make('Test String'); // "Test_String"
     

2. Laravel Integration:

   • Model Accessors:

     class Post extends Model {
         public function getSlugAttribute() {
             return Urlizer::make($this->title);
         }
     }
     

   • Route Slugs:

     Route::get('/posts/{slug}', [PostController::class, 'show']);
     // Generate slugs dynamically in controllers:
     $slug = Urlizer::make(request('title'));
     

3. Batch Processing:

   • Useful for seeding or bulk updates:

     $titles = ['Post 1', 'Post 2!'];
     $slugs = collect($titles)->map(fn($title) => Urlizer::make($title));
     

Advanced Patterns

• Transliteration: Enable in config (transliterate: true) to convert special chars (e.g., ñ → n).

  Urlizer::setOptions(['transliterate' => true]);
  $slug = Urlizer::make('Resumé'); // "resume"
  

• Custom Rules: Extend the service provider to add pre-processing:

  // app/Providers/UrlizerServiceProvider.php
  public function boot() {
      Urlizer::extend(function($string) {
          return str_replace(['&', ''], '', $string); // Remove ampersands
      });
  }
  

• Validation: Combine with Laravel validation for slug uniqueness:

  $validator = Validator::make($request->all(), [
      'slug' => 'required|unique:posts|string',
  ]);
  $slug = Urlizer::make($request->title);
  

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • Last release in 2013: Test thoroughly for edge cases (e.g., Unicode, emojis).
   • Workaround: Fork or extend the package for modern PHP (8.x) support.

2. Config Overrides:

   • Global config (config/urlizer.php) applies to all calls. Reset with:

     Urlizer::setOptions([]); // Revert to defaults
     

3. Transliteration Quirks:

   • Default transliteration is basic. For robust handling, pair with symfony/string or ocramius/package-versions:

     use Symfony\Component\String\UnicodeString;
     $normalized = UnicodeString::from($string)->lower()->toString();
     

4. Separator Collisions:

   • Hyphens (-) in input strings may cause double separators:

     Urlizer::make('Hello-world'); // "hello-world" (default)
     // Fix: Pre-process or adjust config.
     

Debugging Tips

• Inspect Output: Log intermediate steps to debug:

  $steps = [
      'original' => $string,
      'lowercase' => mb_strtolower($string),
      'transliterated' => Urlizer::transliterate($string),
      'final' => Urlizer::make($string),
  ];
  

• Edge Cases:

  • Test with:
    • Emojis (may break; strip with preg_replace('/[^\P{C}\p{L}]/u', '', $string)).
    • Mixed scripts (e.g., Arabic + Latin).
    • Very long strings (truncate if needed: substr(Urlizer::make($string), 0, 50)).

Extension Points

1. Custom Transliteration: Override the transliterate() method in a subclass:

   class CustomUrlizer extends \Aferrandini\Urlizer\Urlizer {
       protected function transliterate($string) {
           // Custom logic here
           return parent::transliterate($string);
       }
   }
   

2. Event Hooks: Listen for slug generation (if the package supports events; otherwise, wrap calls):

   event(new SlugGenerated($original, $slug));
   

3. Database Indexes: Ensure slug fields are indexed for performance:

   Schema::table('posts', function (Blueprint $table) {
       $table->string('slug')->unique();
   });