Voyager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yellow-three/voyager
   php artisan voyager:install
   

   • Follow prompts (DB config, admin user credentials).
   • Publish assets:

     php artisan voyager:assets
     

2. First Use Case

   • Access /admin to log in with the generated credentials.
   • Navigate to BREADs (CRUD interfaces) under Content to manage models.
   • Use Settings > BREADs to configure new admin panels for Eloquent models.

Where to Look First

• Documentation: Voyager Docs (if available) or /resources/docs (if published).
• Admin Dashboard: /admin for pre-built UI.
• BREAD Configuration: /storage/database/voyager_breads.json (auto-generated CRUD settings).
• Middleware: app/Http/Middleware/VoyagerAdminMiddleware.php (customize admin access).

Implementation Patterns

Core Workflows

1. Model Integration (BREADs)

   • Auto-Generated CRUD:

     php artisan voyager:make-bread ModelName
     

   • Manual Configuration: Edit /storage/database/voyager_breads.json or use the Settings > BREADs UI.
   • Custom Fields: Extend tcg\Voyager\Traits\BreadTraits or use addColumn() in BreadServiceProvider.

2. Customizing Views

   • Override default templates in resources/views/voyager/ (e.g., breads/create.blade.php).
   • Use @include('voyager::multilingual.fields') for multilingual support.

3. API & Frontend Sync

   • REST API: Enable via config/voyager.php (api_enabled = true). Endpoints: /api/voyager/{model}.
   • Frontend Integration: Use Voyager’s JS assets (/vendor/tcg/voyager/js/voyager.js) or fetch data via API.

4. Media Management

   • Upload files via Media Manager (/admin/media).
   • Attach media to models using many-to-many relationships or morph-to (for polymorphic).

5. Permissions & Roles

   • Assign roles via Settings > Users & Permissions.
   • Gate access programmatically:

     if (Voyager::can('browse_content')) { ... }
     

Integration Tips

• Laravel Mix/Webpack: Compile Voyager’s SCSS/JS alongside your assets.
• Service Providers: Bind custom services in VoyagerServiceProvider:

  $this->app->bind('custom.service', function () { ... });
  

• Events: Listen to Voyager events (e.g., voyager.bread.added):

  Event::listen('voyager.bread.added', function ($bread) { ... });
  

Gotchas and Tips

Pitfalls

1. Database Migrations

   • Voyager auto-generates tables for voyager_users, voyager_roles, etc. Do not manually alter these.
   • For custom tables, use php artisan voyager:make-bread to scaffold BREADs.

2. Asset Conflicts

   • Clear cached assets after updates:

     php artisan voyager:assets --force
     

   • If JS/CSS fails to load, check public/vendor/tcg/voyager/ permissions.

3. Permission Caching

   • Clear Voyager’s permission cache after role changes:

     php artisan voyager:clear-cache
     

4. Multilingual Quirks

   • Ensure config/voyager.php has multilingual_support = true.
   • Translations must be published:

     php artisan voyager:translations
     

5. Model Relationships

   • Voyager assumes id as the primary key. For UUIDs, override getKey() in your model:

     public function getKey() { return $this->uuid; }
     

Debugging Tips

• Log Viewer: Use /admin/log-viewer to debug Voyager-related errors.
• SQL Queries: Enable Voyager’s query logging in config/voyager.php:

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

• Browser Console: Check for 404s on /vendor/tcg/voyager/ assets.

Extension Points

1. Custom BREAD Fields

   • Add fields via addColumn() in BreadServiceProvider:

     public function boot() {
         $this->addColumn('posts', [
             'type' => 'morph',
             'name' => 'author',
             'model' => 'User',
         ]);
     }
     

2. Override Controllers

   • Extend tcg\Voyager\Http\Controllers\BreadController:

     namespace App\Http\Controllers;
     use tcg\Voyager\Http\Controllers\BreadController as BaseController;
     
     class CustomBreadController extends BaseController {
         public function customMethod() { ... }
     }
     

   • Bind in VoyagerServiceProvider:

     $this->app->bind('voyager.bread.controller', function () {
         return new \App\Http\Controllers\CustomBreadController();
     });
     

3. Hooks & Filters

   • Use voyager.bread.read or voyager.bread.add events to modify data:

     Event::listen('voyager.bread.read', function ($data, $model) {
         $data->custom_field = 'modified';
         return $data;
     });
     

4. Custom Routes

   • Add routes in routes/voyager.php:

     Voyager::addRoute(['GET', 'POST'], 'custom', 'CustomController@method');
     

5. Theming

   • Override SCSS variables in resources/sass/voyager/_variables.scss.
   • Compile with:

     npm run dev