User Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require bisonlab/user-bundle
   php artisan vendor:publish --provider="BisonLab\UserBundle\UserBundle" --tag="config"
   php artisan vendor:publish --provider="BisonLab\UserBundle\UserBundle" --tag="migrations"
   php artisan migrate
   

2. Generate User Model & Controller Since the bundle prefers maker-bundle (a common Laravel package), ensure it’s installed:

   composer require --dev orbitale/maker-bundle
   php artisan make:user User --bundle=BisonLab\UserBundle
   

   This creates a User model, controller, and related files with preconfigured traits.

3. First Use Case

   • Authentication: Use the pre-built AuthController (or extend it) for login/logout.
   • Registration: Extend AuthController to handle registration via the User model.
   • Middleware: Apply @auth or @guest directives in Blade templates (if using Laravel’s auth system).

Where to Look First

• Config: config/user-bundle.php (customize user model, guards, and providers).
• Migrations: database/migrations/[timestamp]_create_users_table.php (adjust fields as needed).
• Traits: app/Models/Traits/UserTrait.php (core logic like findByEmail() or validatePassword()).

Implementation Patterns

Core Workflows

1. User Creation & Registration

   // Extend AuthController or create a custom service
   $user = User::create([
       'email' => 'user@example.com',
       'password' => bcrypt('password123'),
       'name' => 'John Doe',
   ]);
   

   • Validation: Use the User model’s built-in rules (e.g., unique:users,email).

2. Authentication

   • Login: Override AuthController@login() to use the bundle’s authenticate() method.
   • Logout: Redirect after auth()->logout() (standard Laravel).

3. Authorization

   • Roles/Permissions: Extend the User model with hasRole() or can() methods (not built-in; add via traits).
   • Middleware: Bind custom middleware to routes:

     Route::get('/admin', function () {
         // ...
     })->middleware('can:admin-access'); // Requires custom middleware
     

4. API Integration

   • Use Laravel’s Sanctum or Passport alongside the bundle for API auth.
   • Example Sanctum guard in config/user-bundle.php:

     'guards' => [
         'api' => [
             'driver' => 'sanctum',
             'provider' => 'users',
         ],
     ],
     

Integration Tips

• Custom Fields: Add fields to the users table via migrations, then update the User model’s $fillable.
• Event Listeners: Attach listeners for Creating, Created, etc.:

  // app/Providers/EventServiceProvider.php
  protected $listen = [
      'BisonLab\UserBundle\Events\UserCreated' => [
          'App\Listeners\SendWelcomeEmail',
      ],
  ];
  

• Testing: Use Laravel’s actingAs() or fake() for auth tests:

  $user = User::factory()->create();
  $this->actingAs($user)->get('/profile');
  

Gotchas and Tips

Pitfalls

1. Maker-Bundle Dependency

   • The bundle assumes maker-bundle for scaffolding. If missing, manually create the User model/controller or adjust the bundle’s setup.
   • Fix: Install orbitale/maker-bundle or generate files manually.

2. Migration Conflicts

   • If the users table already exists, the bundle’s migrations may fail. Use --force or resolve column conflicts:

     php artisan migrate --force
     

   • Tip: Check database/migrations/[timestamp]_create_users_table.php for required fields (email, password, etc.).

3. Auth Guard Misconfiguration

   • The bundle defaults to Laravel’s session guard. For API auth, update config/user-bundle.php:

     'defaults' => [
         'guard' => 'api', // Change from 'web' to 'api'
     ],
     

4. Password Hashing

   • The bundle uses Laravel’s default bcrypt hashing. For custom hashing (e.g., Argon2), override the User model’s setPasswordAttribute():

     public function setPasswordAttribute($password) {
         $this->attributes['password'] = Hash::make($password);
     }
     

Debugging

• Auth Failures: Check config/user-bundle.php for correct provider/guard names. Verify the users table has the expected columns.
• Route Conflicts: The bundle registers routes in routes/web.php. Override or rename them if needed:

  // Disable bundle routes
  Route::get('/login', [AuthController::class, 'login'])->name('login');
  

• Logs: Enable Laravel’s debug mode (APP_DEBUG=true) and check storage/logs/laravel.log for auth errors.

Extension Points

1. Custom User Model

   • Extend the User model to add methods:

     namespace App\Models;
     
     use BisonLab\UserBundle\Models\User as BaseUser;
     
     class User extends BaseUser {
         public function getFullName() {
             return "{$this->first_name} {$this->last_name}";
         }
     }
     

   • Update config/user-bundle.php to point to your custom model:

     'model' => App\Models\User::class,
     

2. Custom Validation

   • Override the User model’s rules() method or use Laravel’s FormRequest:

     namespace App\Http\Requests;
     
     use Illuminate\Validation\Rule;
     
     class StoreUserRequest extends FormRequest {
         public function rules() {
             return [
                 'email' => ['required', Rule::unique('users')->ignore($this->user)],
             ];
         }
     }
     

3. API Resources

   • Create a custom UserResource for API responses:

     namespace App\Http\Resources;
     
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class UserResource extends JsonResource {
         public function toArray($request) {
             return [
                 'id' => $this->id,
                 'email' => $this->email,
                 'name' => $this->name,
             ];
         }
     }
     

   • Use in controllers:

     return new UserResource($user);
     

4. Testing Utilities

   • Add helper methods to tests/TestCase.php:

     protected function loginAsUser() {
         $user = User::factory()->create();
         $this->actingAs($user);
         return $user;
     }