User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require customscripts/user-bundle
   

   Register the bundle in config/bundles.php (Symfony) or AppServiceProvider (Laravel via Bridge):

   // Laravel (via Bridge)
   $this->mergeConfigFrom(__DIR__.'/../../vendor/customscripts/user-bundle/config/config.php', 'user-bundle');
   

2. Publish Config Publish the default configuration:

   php artisan vendor:publish --provider="CustomScripts\UserBundle\CSUserBundleServiceProvider"
   

   Update config/user-bundle.php as needed (e.g., guard_name, model_paths).

3. Run Migrations Execute the provided migrations:

   php artisan migrate
   

   (Note: Check database/migrations/ for users_table and roles_table if not auto-generated.)

4. First Use Case: User Registration Use the UserManager facade to create a user:

   use CustomScripts\UserBundle\Facades\UserManager;
   
   $user = UserManager::create([
       'name' => 'John Doe',
       'email' => 'john@example.com',
       'password' => 'secure123',
   ]);
   

Implementation Patterns

Core Workflows

1. Authentication

   • Login/Logout: Use the Auth facade (if provided) or leverage Laravel’s built-in Auth::attempt().
   • Middleware: Protect routes with auth:user-bundle (if the bundle registers middleware).

     Route::get('/dashboard', function () {
         // ...
     })->middleware('auth:user-bundle');
     

2. Role-Based Access Control (RBAC)

   • Assign Roles:

     $user->assignRole('admin'); // Assuming `Role` model methods exist.
     

   • Check Permissions:

     if (auth()->user()->hasRole('editor')) {
         // Grant access.
     }
     

   • Policy Integration: Extend Laravel’s Gate or Policy classes to use the bundle’s role checks:

     Gate::define('edit-post', function ($user) {
         return $user->hasRole('admin') || $user->hasRole('editor');
     });
     

3. Password Reset

   • Trigger reset via facade:

     UserManager::sendPasswordResetLink('user@example.com');
     

   • Handle reset requests in routes:

     Route::post('/reset-password', [ResetPasswordController::class, 'handleReset']);
     

4. User CRUD

   • List Users:

     $users = UserManager::all();
     

   • Update User:

     UserManager::update($user->id, ['email' => 'new@example.com']);
     

Integration Tips

• Event Listeners: Listen for user events (e.g., UserCreated, RoleAssigned) via Laravel’s event system:

  event(new UserCreated($user));
  

• API Resources: Transform models into API responses using UserResource (if provided):

  return new UserResource(UserManager::find($id));
  

• Testing: Mock the UserManager facade in tests:

  $this->app->instance('CustomScripts\UserBundle\Facades\UserManager', Mockery::mock());
  

Gotchas and Tips

Pitfalls

1. Archived Status

   • The bundle is archived (no active maintenance). Validate features against your needs before adoption.
   • Expect undocumented behaviors or missing features (e.g., "some features still in development").

2. Configuration Quirks

   • Guard Name: Ensure config/user-bundle.php sets guard_name to match your auth guard (e.g., web or api).
   • Model Paths: If using custom user/role models, explicitly set model_paths in config:

     'models' => [
         'user' => App\Models\User::class,
         'role' => App\Models\Role::class,
     ],
     

3. Migration Conflicts

   • The bundle’s migrations may conflict with Laravel’s default users table. Backup your database before running:

     php artisan migrate --pretend
     

   • Manually merge tables if needed (e.g., add role_id to Laravel’s users table).

4. Facade vs. Service Container

   • Prefer dependency injection over facades for testability:

     // Bad (facade)
     $user = UserManager::find(1);
     
     // Good (injected)
     public function __construct(UserManager $userManager) {
         $this->userManager = $userManager;
     }
     

5. Role Assignment

   • No built-in role hierarchy: If roles need inheritance (e.g., admin > editor), implement logic manually:

     $user->roles()->attach('admin', ['inherits' => ['editor']]);
     

Debugging Tips

1. Enable Logging Add to config/logging.php to debug bundle interactions:

   'channels' => [
       'user-bundle' => [
           'driver' => 'single',
           'path' => storage_path('logs/user-bundle.log'),
           'level' => 'debug',
       ],
   ],
   

   Then log events:

   \Log::channel('user-bundle')->info('Custom event', ['user_id' => $user->id]);
   

2. Check for Deprecated Methods

   • The bundle may use outdated Laravel syntax (e.g., Auth::user() instead of auth()->user()). Override methods in a trait:

     use CustomScripts\UserBundle\Traits\UserTrait;
     
     class User extends Authenticatable {
         use UserTrait {
             UserTrait::getAuthUser insteadOf getUser;
         }
     }
     

3. Database Seed Issues

   • If seeding roles/users fails, manually seed via tinker:

     php artisan tinker
     >>> $role = \App\Models\Role::create(['name' => 'admin']);
     >>> $user = \App\Models\User::create(['email' => 'admin@example.com']);
     >>> $user->assignRole($role);
     

Extension Points

1. Custom User Model Extend the bundle’s User model:

   namespace App\Models;
   
   use CustomScripts\UserBundle\Models\User as BaseUser;
   
   class User extends BaseUser {
       protected $casts = [
           'is_active' => 'boolean', // Custom field
       ];
   }
   

2. Add Fields to Users Modify the migration or use a trait to add columns:

   Schema::table('users', function (Blueprint $table) {
       $table->string('phone')->nullable();
   });
   

3. Override Auth Logic Replace the bundle’s auth controller with a custom one:

   // config/auth.php
   'providers' => [
       'users' => [
           'driver' => 'eloquent',
           'model' => App\Models\User::class,
       ],
   ],
   

4. API Endpoints If the bundle lacks API routes, create them manually:

   Route::post('/api/register', [RegisterController::class, 'store']);