Mmadminbundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require xlabs/mmadminbundle
   

   Add to config/app.php under extra.bundles:

   XLabs\MMAdminBundle\XLabsMMAdminBundle::class
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="XLabs\MMAdminBundle\XLabsMMAdminBundle" --tag=config
   

   Update config/mmadmin.php to match your admin panel URL (e.g., /admin).

3. First Use Case

   • Route Protection: Secure admin routes by adding the middleware:

     Route::group(['middleware' => ['mmadmin']], function () {
         Route::get('/admin/dashboard', 'AdminController@dashboard');
     });
     

   • Extension Setup: Install the MMAdmin Browser Extension to manage admin sessions.

Implementation Patterns

Core Workflows

1. Admin Session Management

   • Use the MMAdmin facade to check admin status:

     if (\XLabs\MMAdminBundle\Facades\MMAdmin::isAdmin()) {
         // Admin-only logic
     }
     

   • Revoke sessions via the extension or programmatically:

     \XLabs\MMAdminBundle\Facades\MMAdmin::revokeSession($sessionId);
     

2. Route Integration

   • Protected Routes: Apply middleware to all admin routes:

     Route::prefix('admin')->middleware(['mmadmin'])->group(function () {
         // Admin routes
     });
     

   • Dynamic Permissions: Use the canAccess method in controllers:

     if (\XLabs\MMAdminBundle\Facades\MMAdmin::canAccess('edit_users')) {
         return view('admin.users.edit');
     }
     

3. Event Listeners

   • Extend functionality by listening to events (e.g., AdminLogin, AdminLogout):

     use XLabs\MMAdminBundle\Events\AdminLogin;
     
     event(new AdminLogin($userId, $ipAddress));
     

Integration Tips

• Laravel Mix/Webpack: Customize the extension’s UI by overriding the resources/views/mmadmin/ templates.
• Multi-Tenancy: Use the tenant() method to scope admin sessions:

  \XLabs\MMAdminBundle\Facades\MMAdmin::setTenant($tenantId);
  

• Logging: Enable debug logs in config/mmadmin.php for troubleshooting:

  'debug' => env('MMADMIN_DEBUG', false),
  

Gotchas and Tips

Pitfalls

1. Extension Dependency

   • The package requires the browser extension for session management. Without it, admin features (e.g., session revocation) won’t work.
   • Fix: Ensure all admins install the extension and whitelist your domain in config/mmadmin.php:

     'allowed_domains' => ['yourdomain.com', 'admin.yourdomain.com'],
     

2. CSRF Token Mismatch

   • If using the extension with traditional Laravel forms, ensure the _token field is included. The extension handles AJAX CSRF automatically but may conflict with form submissions.
   • Tip: Exclude admin routes from CSRF verification if needed:

     Route::group(['middleware' => ['csrf', 'mmadmin']], function () {
         // Exclude routes where CSRF is handled by the extension
     });
     

3. Session Expiry

   • Sessions expire after 24 hours by default. Customize in config/mmadmin.php:

     'session_lifetime' => 3600, // 1 hour
     

   • Warning: Short lifetimes may cause frequent logins for admins.

Debugging

• Extension Not Connecting:

  • Verify the extension’s manifest.json includes your domain.
  • Check browser console for errors (e.g., CORS issues).
  • Enable debug mode ('debug' => true) and inspect logs in storage/logs/laravel.log.

• Middleware Failing:

  • Ensure the mmadmin middleware is registered in app/Http/Kernel.php:

    protected $routeMiddleware = [
        'mmadmin' => \XLabs\MMAdminBundle\Http\Middleware\MMAdminMiddleware::class,
    ];
    

Extension Points

1. Custom Permissions

   • Override the default permission logic by extending the PermissionManager:

     use XLabs\MMAdminBundle\Services\PermissionManager;
     
     class CustomPermissionManager extends PermissionManager {
         public function canAccess($permission) {
             // Custom logic
             return parent::canAccess($permission);
         }
     }
     

   • Bind the service in config/mmadmin.php:

     'permission_manager' => \App\Services\CustomPermissionManager::class,
     

2. Session Storage

   • Switch from the default session driver to a custom store (e.g., Redis):

     'session_driver' => 'redis',
     

   • Implement XLabs\MMAdminBundle\Contracts\SessionStore for full control.

3. UI Customization

   • Override the extension’s UI by copying vendor/xlabs/mmadminbundle/resources/views/mmadmin/ to resources/views/mmadmin/ and modifying templates.
   • Note: Changes to the extension’s frontend require rebuilding the extension (see wiki).