String Extra Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package and Symfony String component to your Laravel project:

   composer require twig/string-extra symfony/string
   

2. Register the Extension If using Twig (via laravel-twig package), add the extension in config/twig.php:

   'extensions' => [
       \Twig\Extra\String\StringExtension::class,
   ],
   

   If using Blade, create a custom directive in a service provider:

   use Symfony\Component\String\UnicodeString;
   
   Blade::directive('slugify', function ($expression) {
       return "<?php echo app(UnicodeString::class)->from({$expression})->slug(); ?>";
   });
   

3. First Use Case In a Twig template:

   {{ 'Laravel is Awesome!' | slugify }}
   

   Output: laravel-is-awesome

   In a Blade template:

   @slugify($post->title)
   

Implementation Patterns

Twig Integration Patterns

1. String Filtering Use built-in filters for common operations:

   {{ '  hello  ' | trim | title }}          {# "Hello" #}
   {{ 'Laravel' | snake_case }}              {# "laravel" #}
   {{ '1000' | int }}                       {# 1000 #}
   

2. Slug Generation Generate SEO-friendly URLs:

   {{ 'Laravel 10 Features' | slugify }}    {# "laravel-10-features" #}
   

3. Text Truncation Limit text length with ellipsis:

   {{ 'This is a long text...' | truncate(10, '...') }}
   {# "This is a..." #}
   

4. Unicode Handling Normalize and manipulate Unicode strings:

   {{ 'Café' | ascii }}                     {# "Cafe" #}
   {{ 'café' | title }}                    {# "Café" #}
   

Blade Integration Patterns

1. Custom Directives Extend Blade with Symfony String methods:

   // app/Providers/AppServiceProvider.php
   use Symfony\Component\String\UnicodeString;
   
   public function boot()
   {
       Blade::directive('slugify', function ($expression) {
           return "<?php echo app(UnicodeString::class)->from({$expression})->slug(); ?>";
       });
   }
   

   Usage:

   <a href="/@slugify($post->title)">{{ $post->title }}</a>
   

2. Helper Functions Create reusable helpers in app/Helpers/StringHelper.php:

   if (!function_exists('slugify')) {
       function slugify($string)
       {
           return UnicodeString::from($string)->slug();
       }
   }
   

   Register in AppServiceProvider:

   require app_path('Helpers/StringHelper.php');
   

   Usage:

   <a href="/{{ slugify($post->title) }}">{{ $post->title }}</a>
   

3. Form Input Sanitization Clean user input before processing:

   @php
       $cleanedInput = UnicodeString::from($request->input('bio'))
           ->replace(['*', '#'], '')
           ->trim();
   @endphp
   

Laravel-Specific Patterns

1. Model Accessors Use the package in Eloquent model accessors:

   // app/Models/Post.php
   public function getSlugAttribute()
   {
       return UnicodeString::from($this->title)->slug();
   }
   

   Usage in Blade:

   <a href="/{{ $post->slug }}">{{ $post->title }}</a>
   

2. Request Validation Sanitize input during validation:

   use Symfony\Component\String\UnicodeString;
   
   $validated = $request->validate([
       'title' => 'required|string',
   ]);
   $validated['slug'] = UnicodeString::from($validated['title'])->slug();
   

3. API Responses Format responses with consistent string handling:

   return response()->json([
       'title' => $post->title,
       'slug' => UnicodeString::from($post->title)->slug(),
   ]);
   

Gotchas and Tips

Common Pitfalls

1. Blade Directive Caching

   • Blade directives may not update immediately due to caching. Clear the view cache after adding new directives:

     php artisan view:clear
     

2. Symfony Version Conflicts

   • Ensure symfony/string is compatible with your Laravel version. Laravel 10+ works with Symfony 6.x:

     composer require symfony/string:^6.0
     

   • Avoid conflicts with other Symfony packages by pinning versions in composer.json:

     "conflict": {
         "symfony/*": "6.*"
     }
     

3. Unicode Edge Cases

   • Some methods (e.g., slugify) may not handle all Unicode characters as expected. Test with non-ASCII input:

     {{ 'Café au Lait' | slugify }}  {# "cafe-au-lait" #}
     

4. Performance in Loops

   • Avoid heavy string operations in template loops (e.g., {{ item | slugify }} for 1000 items). Offload to the controller:

     // Controller
     $items = $items->map(fn ($item) => [
         'slug' => UnicodeString::from($item->title)->slug(),
         'title' => $item->title,
     ]);
     

5. Twig vs. Blade Syntax

   • Twig uses | for filters (e.g., {{ 'text' | slugify }}), while Blade uses @directives (e.g., @slugify($var)). Mixing them requires careful setup.

Debugging Tips

1. Check Registered Extensions Verify the Twig extension is loaded:

   // In a Twig template
   {{ dump(app('twig')->getExtensions()) }}
   

   Look for \Twig\Extra\String\StringExtension.

2. Blade Directive Debugging If a directive fails silently, add error handling:

   Blade::directive('slugify', function ($expression) {
       try {
           return "<?php echo app(UnicodeString::class)->from({$expression})->slug(); ?>";
       } catch (\Exception $e) {
           return "<?php echo 'ERROR: ' . htmlspecialchars($e->getMessage()); ?>";
       }
   });
   

3. Symfony String Methods Explore available methods in the Symfony String documentation. Example:

   {{ 'Laravel' | camel_case }}      {# "laravel" #}
   {{ 'laravel' | upper_case }}      {# "LARAVEL" #}
   {{ 'Laravel' | lower_case }}      {# "laravel" #}
   

Extension Points

1. Custom Filters Extend the Twig extension by creating a custom filter:

   use Twig\TwigFilter;
   use Symfony\Component\String\UnicodeString;
   
   $twig->addFilter(new TwigFilter('custom_slug', function ($string) {
       return UnicodeString::from($string)->slug()->lower();
   }));
   

   Usage:

   {{ 'Hello World' | custom_slug }}  {# "hello-world" #}
   

2. Blade Macro Extensions Add string methods to Blade components:

   use Illuminate\Support\Facades\Blade;
   use Symfony\Component\String\UnicodeString;
   
   Blade::extend(function ($value) {
       $value->slugify = function ($expression) {
           return "<?php echo app(UnicodeString::class)->from({$expression})->slug(); ?>";
       };
       return $value;
   });
   

3. Laravel Facade Create a facade for global access:

   // app/Facades/StringFacade.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   use Symfony\Component\String\UnicodeString;
   
   class StringFacade extends Facade
   {
       protected static function getFacadeAccessor()
       {
           return UnicodeString::class;
       }
   }
   

   Register in AppServiceProvider:

   $this->app->singleton(UnicodeString::class, function () {
       return new UnicodeString('');
   });
   

   Usage:

   use App\Facades\String;
   
   $slug = String::from($title)->slug();
   

Configuration Quirks

1. Case Sensitivity