User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require black/user-bundle
   

   Publish the migration and config files:

   php artisan vendor:publish --provider="Black\UserBundle\UserBundleServiceProvider"
   

   Run migrations:

   php artisan migrate
   

2. First Use Case: User Registration Use the User model (auto-registered via the bundle) and its traits:

   use Black\UserBundle\Models\User;
   
   $user = User::create([
       'email' => 'user@example.com',
       'password' => bcrypt('secure123'),
       'name' => 'John Doe',
   ]);
   

3. Where to Look First

   • Models: app/Models/User.php (auto-generated by the bundle).
   • Traits: Check Black\UserBundle\Traits\* for reusable logic (e.g., HasRoles, HasPermissions).
   • Middleware: app/Http/Middleware/Authenticate.php (if extended by the bundle).
   • Routes: routes/web.php (for auth endpoints like register, login).

Implementation Patterns

Core Workflows

1. Authentication Use the bundle’s built-in guards (if configured). Example login logic:

   use Black\UserBundle\Services\AuthService;
   
   $auth = app(AuthService::class);
   $user = $auth->attempt('email@example.com', 'password');
   

2. Role/Permission Management Assign roles to users via the HasRoles trait:

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

   Check permissions:

   if ($user->can('edit_articles')) { ... }
   

3. API Integration Extend the UserResource (if provided) for API responses:

   use Black\UserBundle\Http\Resources\UserResource;
   
   return new UserResource($user);
   

4. Event Listeners Listen to user events (e.g., user.created):

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

Integration Tips

• Custom Fields: Extend the User model to add fields:

  class User extends \Black\UserBundle\Models\User
  {
      protected $casts = [
          'is_active' => 'boolean',
      ];
  }
  

• Validation: Use the bundle’s UserRequest (if available) or extend it:

  use Black\UserBundle\Http\Requests\UserRequest;
  
  class CustomUserRequest extends UserRequest { ... }
  

• Testing: Mock the AuthService or use the UserFactory (if provided):

  $user = User::factory()->create();
  

Gotchas and Tips

Pitfalls

1. Archived Status The package is archived (no active maintenance). Expect:

   • Missing Laravel 10+ compatibility.
   • Undocumented breaking changes.
   • No official support (use GitHub issues cautiously).

2. Incomplete Features

   • No Readme/Documentation: Assume undocumented methods may break.
   • Lack of Tests: Edge cases (e.g., password resets) may fail silently.
   • No API Tokens: If using Sanctum/Passport, implement manually.

3. Migration Conflicts The bundle’s migrations may clash with existing users tables. Backup first:

   php artisan migrate:status
   

Debugging Tips

• Dump the User Model:

  dd(app('config')->get('user-bundle.models.user'));
  

• Check Published Config:

  dd(config('user-bundle'));
  

• Enable Query Logging:

  \DB::enableQueryLog();
  $user->roles(); // Trigger query
  \DB::getQueryLog();
  

Extension Points

1. Override Models Replace the default User model in config/user-bundle.php:

   'models' => [
       'user' => App\Models\CustomUser::class,
   ],
   

2. Custom Auth Logic Extend AuthService:

   class CustomAuthService extends \Black\UserBundle\Services\AuthService {
       public function attempt($email, $password) {
           // Custom logic
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(
       \Black\UserBundle\Services\AuthService::class,
       CustomAuthService::class
   );
   

3. Add Policies Use Laravel’s policy system:

   use Black\UserBundle\Models\User;
   
   class PostPolicy {
       public function update(User $user, Post $post) {
           return $user->can('edit_posts');
       }
   }
   

Pro Tips

• Use Tinker for Quick Tests:

  php artisan tinker
  >>> $user = \Black\UserBundle\Models\User::first();
  >>> $user->roles
  

• Monitor Deprecations: Wrap bundle calls in try-catch for future-proofing.
• Fork the Repo: If critical, fork and maintain your own version.