Laravel Persian Slug Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pishran/laravel-persian-slug
   

   For Laravel 7, use pishran/laravel-persian-slug:1.4.

2. Publish Config (Optional):

   php artisan vendor:publish --provider="Pishran\LaravelPersianSlug\LaravelPersianSlugServiceProvider"
   

   (Default config is minimal; only publish if customizing behavior.)

3. First Use Case: Add HasPersianSlug trait to an Eloquent model (e.g., Post) and define getSlugOptions():

   use Pishran\LaravelPersianSlug\HasPersianSlug;
   use Spatie\Sluggable\SlugOptions;
   
   class Post extends Model
   {
       use HasPersianSlug;
   
       public function getSlugOptions(): SlugOptions
       {
           return SlugOptions::create()
               ->generateSlugsFrom('title') // Field to slugify
               ->saveSlugsTo('slug');      // Column to store slug
       }
   }
   

4. Generate Slugs:

   • Manually:

     $post = new Post(['title' => 'مقاله نمونه']);
     $post->save(); // Slug auto-generated (e.g., "maqaleh-namune")
     

   • Via Mass Assignment:

     $post = Post::create(['title' => 'مقاله دیگر']);
     

Implementation Patterns

Core Workflows

1. Slug Generation:

   • Dynamic Fields: Use generateSlugsFrom() with multiple fields:

     ->generateSlugsFrom(['title', 'subtitle'])
     

   • Custom Separator: Override default - (e.g., _):

     ->slugs(['separator' => '_'])
     

2. Integration with Spatie Sluggable:

   • Leverage Spatie’s features (e.g., unique slugs, custom callbacks):

     ->unique()
     ->on('posts')
     ->saveSlugsTo('slug')
     

3. Model Events:

   • Hook into creating/updating to enforce slugs:

     protected static function boot()
     {
         parent::boot();
         static::creating(fn ($model) => $model->generateSlug());
     }
     

4. API/Forms:

   • Use generateSlug() method explicitly for validation:

     $request->validate(['title' => 'required']);
     $post->generateSlug(); // Ensure slug exists before saving
     

Advanced Patterns

• Custom Slug Logic: Override generateSlug() in the model:

  public function generateSlug(): void
  {
      $this->slug = Str::persianSlug($this->title, '-', true);
  }
  

• Seeding: Use factory() with slugs:

  Post::factory()->create(['title' => 'مقاله تستی']);
  

• API Resources: Expose slugs in responses:

  public function toArray($request)
  {
      return [
          'slug' => $this->slug,
          // ...
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Locale Conflicts:

   • Ensure app.php locale is set to Persian ('locale' => 'fa') if using Persian-specific rules (e.g., Str::persianSlug()).
   • Fix: Explicitly pass locale to Str::persianSlug():

     Str::persianSlug($title, '-', true, 'fa');
     

2. Unique Slugs:

   • Spatie’s unique() requires a slug column. If missing, slugs may collide.
   • Fix: Add unique() to getSlugOptions():

     ->unique()
     

3. Database Collation:

   • Persian characters may not sort correctly in utf8mb4_unicode_ci. Use utf8mb4_general_ci for slugs.
   • Fix: Alter table column:

     ALTER TABLE posts MODIFY slug VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
     

4. Caching:

   • Slugs are generated on-the-fly. For high-traffic apps, cache slugs in Redis:

     Cache::remember("slug_{$model->id}", now()->addHours(1), fn () => $model->slug);
     

Debugging Tips

• Log Slugs: Add a temporary method to inspect slug generation:

  public function debugSlug()
  {
      dd(Str::persianSlug($this->title, '-', true));
  }
  

• Check Config: Verify config/persian-slug.php if slugs appear malformed (e.g., separator or limit settings).

Extension Points

1. Custom Rules: Extend Pishran\LaravelPersianSlug\Rules\PersianSlug for validation:

   use Pishran\LaravelPersianSlug\Rules\PersianSlug;
   
   $request->validate([
       'slug' => ['required', new PersianSlug],
   ]);
   

2. Service Provider: Bind custom slug generators:

   $this->app->bind('slug', fn () => new CustomPersianSlugGenerator());
   

3. Testing: Mock slug generation in tests:

   $post = Post::factory()->make(['title' => 'test']);
   $post->shouldReceive('generateSlug')->once();