Laravel Username Generator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require taylornetwork/laravel-username-generator
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="TaylorNetwork\LaravelUsernameGenerator\UsernameGeneratorServiceProvider"
   

2. Basic Usage:

   • Ensure your User model extends TaylorNetwork\LaravelUsernameGenerator\HasUsername.
   • Run migrations to add the username column (if not already present):

     php artisan vendor:publish --provider="TaylorNetwork\LaravelUsernameGenerator\UsernameGeneratorServiceProvider" --tag=migrations
     

   • Generate a username for a new user:

     $user = User::create([
         'name' => 'John Doe',
         'email' => 'john@example.com',
     ]);
     $user->generateUsername(); // Auto-generates username (e.g., "johndoe123")
     $user->save();
     

3. First Use Case:

   • Use in UserObserver or Creating event listener to auto-generate usernames during registration:

     use TaylorNetwork\LaravelUsernameGenerator\Events\UsernameGenerated;
     
     User::created(function ($user) {
         if (empty($user->username)) {
             $user->generateUsername();
             $user->save();
         }
     });
     

Implementation Patterns

Common Workflows

1. Registration Flow:

   • Trigger username generation in UserObserver or Creating event:

     User::created(function ($user) {
         $user->generateUsername()->save();
     });
     

   • Customize generation logic via config (config/username-generator.php):

     'generator' => 'TaylorNetwork\LaravelUsernameGenerator\Generators\DefaultGenerator',
     'prefix' => 'user_',
     'suffix_length' => 3,
     'separator' => '_',
     

2. Manual Generation:

   • Generate on-demand for existing users:

     $user = User::find(1);
     $user->generateUsername(); // Overwrites existing username
     $user->save();
     

3. Validation Integration:

   • Combine with Laravel validation to ensure uniqueness:

     $request->validate([
         'name' => 'required|string',
         'email' => 'required|email|unique:users',
         'username' => 'required|unique:users', // Auto-filled by package
     ]);
     

4. Custom Generators:

   • Extend TaylorNetwork\LaravelUsernameGenerator\Generators\Generator:

     namespace App\Generators;
     
     use TaylorNetwork\LaravelUsernameGenerator\Generators\Generator;
     
     class CustomGenerator extends Generator {
         public function generate($name, $email) {
             return strtolower(str_replace(' ', '.', $name)) . rand(100, 999);
         }
     }
     

   • Bind in AppServiceProvider:

     public function register() {
         $this->app->bind('username-generator', function () {
             return new \App\Generators\CustomGenerator();
         });
     }
     

5. Seeding:

   • Generate usernames for seed data:

     $users = User::factory()->count(10)->create();
     foreach ($users as $user) {
         $user->generateUsername()->save();
     }
     

Integration Tips

• APIs: Use in RegisterController to auto-generate usernames during API registration.
• Admin Panels: Trigger generation when manually creating users in admin interfaces (e.g., Nova, Filament).
• Testing: Mock the generator in unit tests:

  $this->app->instance('username-generator', MockGenerator::class);
  

• Localization: Customize separators/prefixes for multilingual apps (e.g., separator = – for German).

Gotchas and Tips

Pitfalls

1. Duplicate Usernames:

   • The package checks for uniqueness, but race conditions can occur. Use database transactions:

     DB::transaction(function () use ($user) {
         $user->generateUsername();
         $user->save();
     });
     

   • For high-traffic apps, consider adding a username index in migrations:

     Schema::table('users', function (Blueprint $table) {
         $table->string('username')->unique()->after('email');
     });
     

2. Overwriting Usernames:

   • generateUsername() overwrites existing values. Use generateUniqueUsername() for safer updates:

     if (empty($user->username)) {
         $user->generateUsername();
     } else {
         $user->generateUniqueUsername(); // Skips if username exists
     }
     

3. Generator Cache:

   • The default generator caches generated usernames to avoid collisions. Clear cache if behavior changes unexpectedly:

     app('username-generator')->clearCache();
     

4. Case Sensitivity:

   • Usernames are case-insensitive by default. Ensure your username column collation supports this (e.g., utf8mb4_unicode_ci).

5. Performance:

   • Avoid generating usernames in loops without batching. Use generateUsername() sparingly in bulk operations.

Debugging

• Log Generation: Enable debug mode in config to log generated usernames:

  'debug' => env('USERNAME_GENERATOR_DEBUG', false),
  

• Check Cache: Inspect cached usernames:

  dd(app('username-generator')->getCache());
  

• Test Locally: Use taylordev/laravel-username-generator's test helpers:

  $this->assertUsernameGenerated($user, 'johndoe');
  

Extension Points

1. Custom Validation: Override validation rules in User model:

   protected static function booted() {
       static::updating(function ($user) {
           if ($user->isDirty('name') && $user->username) {
               $user->generateUniqueUsername();
           }
       });
   }
   

2. Event Listeners: Listen for UsernameGenerated events:

   UsernameGenerated::listen(function ($user) {
       Log::info("Generated username for {$user->name}: {$user->username}");
   });
   

3. Dynamic Config: Override config dynamically (e.g., per tenant):

   config(['username-generator.prefix' => 'tenant_' . $tenant->slug]);
   

4. Fallback Generators: Chain generators for fallback logic:

   $generator = app('username-generator');
   $username = $generator->generate($name, $email);
   if (empty($username)) {
       $username = $generator->fallbackGenerate($name, $email);
   }
   

5. API Responses: Exclude username from API responses if sensitive:

   protected $hidden = ['password', 'remember_token'];
   protected $appends = ['username']; // Or exclude via API resources