Pando User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blackboxcode/pando-user-bundle
   

   Add to config/bundles.php:

   BlackBoxCode\PandoUserBundle\PandoUserBundle::class => ['all' => true],
   

2. Publish Configuration

   php artisan vendor:publish --provider="BlackBoxCode\PandoUserBundle\PandoUserBundle" --tag="config"
   

   Edit config/pando_user.php to define:

   • User model (model)
   • Auth driver (driver)
   • Default roles (roles)

3. First Use Case: User Registration

   use BlackBoxCode\PandoUserBundle\Services\UserService;
   
   $userService = app(UserService::class);
   $user = $userService->create([
       'email' => 'user@example.com',
       'password' => 'secure123',
       'name' => 'John Doe',
       'roles' => ['ROLE_USER'] // Default role
   ]);
   

4. Authentication Use Laravel's built-in auth facade:

   Auth::login($user);
   

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

   // Assign role to user
   $userService->addRole($user, 'ROLE_ADMIN');
   
   // Check permissions
   if ($userService->hasRole($user, 'ROLE_ADMIN')) {
       // Admin-only logic
   }
   

2. User Management

   // Update user
   $userService->update($user, ['name' => 'Jane Doe']);
   
   // Delete user (soft delete)
   $userService->delete($user);
   

3. Event Listeners The bundle dispatches events for:

   • user.created
   • user.updated
   • user.deleted
   • user.login
   • user.logout

   Register listeners in EventServiceProvider:

   protected $listen = [
       'user.created' => [
           'App\Listeners\SendWelcomeEmail',
       ],
   ];
   

4. API Integration Use the UserResource for API responses:

   use BlackBoxCode\PandoUserBundle\Http\Resources\UserResource;
   
   return new UserResource($user);
   

Integration Tips

• Custom User Model Extend the default model:

  namespace App\Models;
  
  use BlackBoxCode\PandoUserBundle\Models\User as BaseUser;
  
  class User extends BaseUser
  {
      protected $casts = [
          'is_active' => 'boolean',
      ];
  }
  

  Update config/pando_user.php to point to App\Models\User.

• Custom Roles Define roles in config/pando_user.php:

  'roles' => [
      'ROLE_USER' => ['description' => 'Basic user'],
      'ROLE_ADMIN' => ['description' => 'Administrator'],
  ],
  

• Middleware Use the provided middleware for role checks:

  Route::middleware(['role:ROLE_ADMIN'])->group(function () {
      // Admin-only routes
  });
  

Gotchas and Tips

Pitfalls

1. Role Hierarchy Not Enforced The bundle does not support role inheritance (e.g., ROLE_ADMIN does not automatically include ROLE_USER permissions). Implement custom logic if needed:

   $userService->hasAnyRole($user, ['ROLE_ADMIN', 'ROLE_USER']);
   

2. Password Hashing Ensure your App\User model (or custom model) uses Laravel's HasApiTokens and Notifiable traits if extending functionality:

   use Illuminate\Foundation\Auth\User as Authenticatable;
   use Illuminate\Notifications\Notifiable;
   use Laravel\Sanctum\HasApiTokens;
   
   class User extends Authenticatable
   {
       use HasApiTokens, Notifiable;
   }
   

3. Configuration Overrides Avoid overriding the entire config/pando_user.php file. Use the merge method in a service provider:

   $this->mergeConfigFrom(__DIR__.'/pando_user.php', 'pando_user');
   

4. Database Migrations The bundle does not include migrations. Ensure your users table has:

   • email (unique)
   • password
   • remember_token
   • roles (JSON or pivot table for many-to-many)

   Example migration:

   Schema::create('users', function (Blueprint $table) {
       $table->id();
       $table->string('email')->unique();
       $table->string('password');
       $table->json('roles')->default('[]');
       $table->timestamps();
       $table->softDeletes();
   });
   

Debugging

• Role Assignment Issues Verify roles are stored as an array or JSON in the database. Use:

  $user->roles; // Check the value
  

• Authentication Failures Ensure the auth.driver in config/auth.php matches the driver defined in config/pando_user.php.

• Event Dispatching Check if events are being dispatched by adding a listener:

  event(new \Symfony\Component\Debug\DebugClassLoader());
  

Extension Points

1. Custom User Service Bind your own service to replace the default:

   $this->app->bind(
       BlackBoxCode\PandoUserBundle\Services\UserService::class,
       App\Services\CustomUserService::class
   );
   

2. Custom Role Provider Implement BlackBoxCode\PandoUserBundle\Contracts\RoleProvider:

   class CustomRoleProvider implements RoleProvider
   {
       public function getRoles(): array
       {
           return ['CUSTOM_ROLE_1', 'CUSTOM_ROLE_2'];
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(
       BlackBoxCode\PandoUserBundle\Contracts\RoleProvider::class,
       CustomRoleProvider::class
   );
   

3. Custom Middleware Extend the RoleMiddleware:

   namespace App\Http\Middleware;
   
   use BlackBoxCode\PandoUserBundle\Http\Middleware\RoleMiddleware as BaseRoleMiddleware;
   
   class CustomRoleMiddleware extends BaseRoleMiddleware
   {
       protected function roles(): array
       {
           return ['CUSTOM_ROLE'];
       }
   }
   

4. API Resources Extend UserResource for additional fields:

   namespace App\Http\Resources;
   
   use BlackBoxCode\PandoUserBundle\Http\Resources\UserResource as BaseUserResource;
   
   class UserResource extends BaseUserResource
   {
       public function toArray($request)
       {
           return array_merge(parent::toArray($request), [
               'custom_field' => $this->resource->custom_field,
           ]);
       }
   }