User Management Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the package via Composer:

   composer require l5starter/user-management:5.4.x-dev
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       L5Starter\UserManagement\UserManagementServiceProvider::class,
   ],
   

2. Publish Configuration & Migrations Run the publisher command to generate config and migrations:

   php artisan vendor:publish --provider="L5Starter\UserManagement\UserManagementServiceProvider"
   

   Then migrate your database:

   php artisan migrate
   

3. Seed Initial Data Populate the database with default users and roles:

   php artisan db:seed --class=UsersTableSeeder
   php artisan db:seed --class=UserHasRolesTableSeeder
   

4. First Use Case: User CRUD Access the admin panel for users via the generated route:

   php artisan route:list | grep admin.users
   

   Navigate to /admin/users to interact with the built-in admin interface.

Implementation Patterns

Core Workflows

1. User Management

   • Create/Update Users: Use the User model (likely extended from L5Starter\UserManagement\Models\User).

     $user = User::create([
         'name' => 'John Doe',
         'email' => 'john@example.com',
         'password' => bcrypt('password'),
     ]);
     

   • Assign Roles: Leverage the hasRole() and attachRole() methods (assuming role-based permissions are implemented).

     $user->attachRole('admin'); // If using a role system
     

2. Authentication & Authorization

   • Integrate with Laravel’s built-in auth scaffolding:

     php artisan make:auth
     

   • Extend the AuthenticatesUsers trait in your LoginController to use the custom User model:

     protected $redirectTo = '/admin/dashboard';
     protected $username = 'email'; // Use email for login
     

3. Admin Panel Integration

   • Sidebar Menu: Add the provided sidebar snippet to resources/views/vendor/l5starter/admin/partials/sidebar.blade.php to expose the user management section.
   • Customize Admin Views: Override default admin views by publishing and extending them:

     php artisan vendor:publish --tag=l5starter-views
     

4. API Endpoints (if applicable)

   • If the package includes API routes, register them in routes/api.php:

     Route::middleware('auth:api')->group(function () {
         Route::resource('users', 'UserController');
     });
     

Integration Tips

1. Customize User Model Extend the default User model to add custom fields or logic:

   namespace App;
   
   use L5Starter\UserManagement\Models\User as BaseUser;
   
   class User extends BaseUser
   {
       protected $fillable = ['name', 'email', 'password', 'custom_field'];
   }
   

2. Event Listeners Listen for user-related events (e.g., registered, updated) to trigger actions like notifications:

   // In EventServiceProvider
   protected $listen = [
       'L5Starter\UserManagement\Events\UserRegistered' => [
           'App\Listeners\SendWelcomeEmail',
       ],
   ];
   

3. Policy-Based Authorization Use Laravel’s policies to restrict access:

   php artisan make:policy UserPolicy --model=User
   

   Then attach the policy to the User model in AuthServiceProvider.

4. Localization Override translations by publishing the language files:

   php artisan vendor:publish --tag=l5starter-translations
   

   Then extend resources/lang/vendor/l5starter/.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The package may use User as a model name. Ensure your App\User does not conflict by either:
     • Renaming your default User model (e.g., App\Models\User).
     • Overriding the package’s model binding in AppServiceProvider:

       public function boot()
       {
           \App::bind('L5Starter\UserManagement\Models\User', function () {
               return new \App\Models\User;
           });
       }
       

2. Migration Overwrites

   • If you’ve already created a users table, manually merge the package’s migrations to avoid conflicts. Check database/migrations/ for overlapping columns.

3. Route Caching

   • After adding admin routes, clear the route cache:

     php artisan route:clear
     

4. Middleware Dependencies

   • The package may rely on middleware like auth.admin. Ensure these are registered in app/Http/Kernel.php before use.

Debugging

1. Check Published Config Verify the published config at config/l5starter.php matches your expectations. Override values as needed:

   'default_role' => 'user', // Example override
   

2. Log User Actions Add logging to debug user-related operations:

   \Log::info('User created', ['user' => $user->toArray()]);
   

3. Test Role Assignments If roles aren’t working, check:

   • The UserHasRoles pivot table exists.
   • The hasRole() method is correctly implemented (may need to extend the model).

Extension Points

1. Custom Fields Add fields to the users table via migration, then update the admin form:

   // In UserController (if extending)
   public function fields()
   {
       return parent::fields() + ['custom_field' => 'text'];
   }
   

2. API Resources Extend the default API resource for users:

   php artisan make:resource UserResource --model=User
   

   Then override the toArray() method to include/exclude fields.

3. Custom Admin Views Override the admin panel views by copying from vendor/l5starter/user-management/resources/views to resources/views/vendor/l5starter/admin/.

4. Seeding Extensions Extend the seeders to include default users with roles:

   // In UsersTableSeeder
   $user = User::create([...]);
   $user->attachRole('admin');