Laravel Admin Users Laravel Package

Getting Started

Install the package via Composer:

composer require snoeren-development/laravel-admin-users

Publish the package's configuration and migrations (if needed):

php artisan vendor:publish --provider="SnoerenDevelopment\AdminUsers\AdminUsersServiceProvider"

For Laravel 10/11/12/13, register the service provider in config/app.php under providers. The package now supports Laravel 13 (tested with latest stable). Start by defining admin users in config/admin-users.php and use the AdminUser facade or service container to interact with admin users:

use SnoerenDevelopment\AdminUsers\Facades\AdminUser;

// Create an admin user
AdminUser::create(['name' => 'Admin', 'email' => 'admin@example.com']);

// Check if current user is an admin
if (AdminUser::isAdmin()) { ... }

Implementation Patterns

Core Workflows

1. Admin User Management Use the AdminUser facade or service container to manage admin users:

   // Create
   AdminUser::create(['name' => 'Super Admin', 'email' => 'super@example.com']);
   
   // Find
   $admin = AdminUser::find(1);
   
   // Check permissions (if using middleware)
   if (AdminUser::can('manage_users')) { ... }
   

2. Middleware Integration Attach the AdminUserMiddleware to routes requiring admin access:

   Route::middleware(['web', 'admin'])->group(function () {
       // Admin-only routes
   });
   

3. Policy-Based Permissions Define policies in app/Policies/AdminUserPolicy.php:

   public function canManageUsers(User $user) {
       return $user->isAdmin();
   }
   

4. Laravel 13 Support

   • Use the new app/Providers/AppServiceProvider for bootstrapping.
   • Leverage Laravel 13’s improved dependency injection:

     public function register()
     {
         $this->app->bind(\SnoerenDevelopment\AdminUsers\Contracts\AdminUserContract::class, \SnoerenDevelopment\AdminUsers\Services\AdminUserService::class);
     }
     

5. Customizing Admin Users Extend the AdminUser model:

   namespace App\Models;
   
   use SnoerenDevelopment\AdminUsers\Models\AdminUser as BaseAdminUser;
   
   class AdminUser extends BaseAdminUser
   {
       protected $casts = [
           'is_super_admin' => 'boolean',
       ];
   }
   

Gotchas and Tips

Breaking Changes & Quirks

• Laravel 13 Compatibility: Ensure your composer.json requires Laravel 13 if upgrading. Test thoroughly, as some internal changes (e.g., Illuminate\Foundation\Application) may affect package behavior.
• Dependency Updates: While the package bumps minor versions of dependencies (e.g., Symfony 7.4.x), no breaking changes are expected. However, test if your app uses:
  • symfony/process (e.g., for background jobs or CLI commands).
  • league/commonmark (if using Markdown parsing in admin panels).

Debugging

• Permission Issues: If AdminUser::isAdmin() returns false unexpectedly, verify:
  • The admin_users table exists and is populated.
  • The AdminUserMiddleware is correctly attached to routes.
  • No custom policies are overriding permissions.
• Middleware Conflicts: If using Laravel’s built-in auth middleware, ensure AdminUserMiddleware runs after auth:

  Route::middleware(['web', 'auth', 'admin'])->group(...);
  

Extension Points

1. Custom Guard: Override the default guard in config/admin-users.php:

   'guard' => 'admin',
   

   Then configure the guard in config/auth.php.

2. Event Listeners: Listen for AdminUserCreated, AdminUserDeleted, etc., in EventServiceProvider:

   protected $listen = [
       \SnoerenDevelopment\AdminUsers\Events\AdminUserCreated::class => [
           \App\Listeners\LogAdminCreation::class,
       ],
   ];
   

3. API Resources: Extend the default AdminUserResource for API responses:

   namespace App\Http\Resources;
   
   use SnoerenDevelopment\AdminUsers\Http\Resources\AdminUserResource as BaseResource;
   
   class AdminUserResource extends BaseResource
   {
       public function toArray($request)
       {
           return array_merge(parent::toArray($request), [
               'custom_field' => $this->custom_field,
           ]);
       }
   }
   

4. Testing: Use the AdminUserFactory for testing:

   use SnoerenDevelopment\AdminUsers\Database\Factories\AdminUserFactory;
   
   AdminUserFactory::new()->create();
   

Performance

• Eager Loading: Avoid N+1 queries when fetching admins with relationships:

  $admins = AdminUser::with('roles', 'permissions')->get();
  

• Caching: Cache admin checks if performance is critical:

  if (cache()->remember('user-is-admin', now()->addHours(1), fn() => AdminUser::isAdmin())) { ... }
  

Configuration

• Table Name: Customize the table name in config/admin-users.php:

  'table' => 'custom_admin_users',
  

• Soft Deletes: Enable soft deletes by setting:

  'soft_deletes' => true,
  

  Then use AdminUser::withTrashed() for queries.

Common Pitfalls

• Migration Conflicts: If manually modifying migrations, ensure they align with the package’s schema. Run php artisan vendor:publish --tag=migrations to republish.
• Role/Permission Systems: If integrating with packages like spatie/laravel-permission, ensure the AdminUser model is properly linked to roles/permissions.
• CSRF on API Routes: If using admin APIs, ensure CSRF protection is disabled for API routes (use api middleware group) or configure AdminUserMiddleware accordingly.