Voyager Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tcg/voyager
   php artisan voyager:install --author="Your Name" --email="your@email.com"
   

   • Follow prompts for database configuration (MySQL recommended).
   • Run migrations:

     php artisan migrate
     

2. First Use Case:

   • Access the admin panel at /admin (default credentials: admin@admin.com / password).
   • Use the BREAD (Browse, Read, Edit, Add, Delete) interface to manage built-in models (Settings, Users, Roles, Permissions).

3. Key Files to Explore:

   • app/Voyager/ – Core models, policies, and service providers.
   • resources/views/voyager/ – Blade templates for admin UI.
   • config/voyager.php – Configuration for routes, menus, and BREAD settings.

Implementation Patterns

Core Workflows

1. BREAD Management:

   • Create a BREAD for a Model:

     php artisan voyager:make {ModelName}
     

     • Generates CRUD scaffolding (Vue + Bootstrap) for App\{ModelName}.
     • Customize in app/Voyager/{ModelName}Controller.php and resources/views/voyager/{model-name}/.
   • Field Customization:
     • Use addRow() in the controller to modify fields:

       public function setDisplayColumn($data)
       {
           return $data->title; // Override default display column
       }
       

2. Menu and Dashboard:

   • Add Menu Items:

     // In a Service Provider (e.g., AppServiceProvider)
     Voyager::addMenuItem('dashboard', 'Reports', route('voyager.reports.index'));
     

   • Custom Dashboard Widgets:
     • Extend Voyager\Widgets\BaseWidget and register in config/voyager.php under dashboard.

3. Permissions & Roles:

   • Assign permissions via the Roles & Permissions BREAD.
   • Use middleware to restrict routes:

     Route::group(['middleware' => ['voyager.auth']], function () {
         // Admin-only routes
     });
     

4. API Integration:

   • Use Voyager’s built-in API endpoints (e.g., /api/voyager/{model}) or create custom API routes:

     Route::apiResource('custom-api', 'CustomApiController');
     

Integration Tips

• Laravel Mix/Webpack:

  • Override default assets by publishing and extending:

    php artisan vendor:publish --tag=voyager-assets
    

  • Customize SCSS in resources/assets/sass/voyager/custom.scss.

• Multi-Tenancy:

  • Use Voyager’s tenant() helper or middleware to scope data per tenant.

• Localization:

  • Publish language files:

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

  • Extend config/voyager.php for custom locales.

Gotchas and Tips

Pitfalls

1. Vue/JS Dependencies:

   • Voyager uses Vue 2 and Bootstrap 3. Conflicts may arise with modern Laravel (Vue 3/Tailwind).
   • Fix: Isolate Voyager’s assets or override globally:

     // In resources/js/app.js
     window.Voyager = { /* Override defaults */ };
     

2. Database Schema Assumptions:

   • Voyager expects id, created_at, updated_at fields. Custom models may need adjustments:

     public function setTable()
     {
         return 'custom_table_name';
     }
     

3. Caching Issues:

   • Clear Voyager’s cache after major changes:

     php artisan voyager:clear-cache
     

4. Permission Overrides:

   • Avoid hardcoding permissions in routes. Use Voyager’s Policy system:

     // app/Policies/VoyagerPolicy.php
     public function viewAny(User $user)
     {
         return $user->hasRole('admin');
     }
     

Debugging

• Log Viewer:

  • Access /admin/log-viewer to debug BREAD actions or API calls.

• Query Logging:

  • Enable in config/voyager.php:

    'debug' => env('APP_DEBUG', true),
    

• Common Errors:

  • 404 on BREAD Routes:
    • Ensure RouteServiceProvider includes Voyager’s routes:

      Route::group(['prefix' => 'admin'], function () {
          Voyager::routes();
      });
      

  • CSRF Token Mismatch:
    • Regenerate session key:

      php artisan session:clear
      

Extension Points

1. Custom BREAD Actions:

   • Add buttons to the BREAD toolbar:

     public function getBreadActions()
     {
         return [
             'edit' => [
                 'title' => 'Custom Action',
                 'icon' => 'voyager-edit',
                 'route' => ['voyager.{resource}.custom', $this->data],
             ],
         ];
     }
     

2. Event Listeners:

   • Listen to Voyager events (e.g., voyager.data.displaying):

     VoyagerEvents::addListener('voyager.data.displaying', function ($event) {
         $event->data->custom_field = 'modified';
     });
     

3. API Extensions:

   • Override API responses in app/Http/Controllers/Voyager/{Model}ApiController.php.

4. Theme Customization:

   • Extend the default theme by copying resources/views/vendor/voyager/ to resources/views/voyager/.