Vapor Ui Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (though note its deprecated status):

   composer require laravel/vapor-ui
   

   Publish the configuration:

   php artisan vendor:publish --provider="Laravel\VaporUI\VaporUIServiceProvider"
   

2. Configuration Update .env with your Vapor credentials:

   VAPOR_UI_KEY=your_vapor_ui_key
   VAPOR_UI_SECRET=your_vapor_ui_secret
   

   Ensure VAPOR_UI_ENABLED=true in .env.

3. First Use Case Access the dashboard via /vapor-ui (or your configured route). Authenticate using your Vapor credentials to view logs and failed jobs in real-time.

Implementation Patterns

Core Workflows

1. Log Management

   • Search & Filter: Use the dashboard’s search bar to filter logs by timestamp, level (e.g., error, info), or keyword.
   • Tail Logs: Enable "tail" mode to stream real-time logs for debugging live issues.
   • Export Logs: Download logs as JSON or plaintext for offline analysis.

2. Queue Job Monitoring

   • Failed Jobs: View failed queue jobs with stack traces and payloads. Retry or delete jobs directly from the UI.
   • Job History: Track job execution times and statuses (e.g., pending, processing, failed).

3. Integration with Laravel

   • Log Channels: Ensure your Laravel app uses the single log channel (default in Vapor) for seamless log aggregation.
   • Queue Workers: Use vapor:queue or vapor:queue:work Artisan commands to process jobs, which sync with the UI.

4. Customization

   • Routes: Override the default /vapor-ui route in routes/web.php:

     Route::middleware(['web', 'auth'])->group(function () {
         Route::get('/admin/logs', [VaporUIController::class, 'show']);
     });
     

   • Middleware: Restrict access with custom middleware (e.g., auth:admin).

5. CI/CD Pipelines

   • Deployment Hooks: Trigger log checks post-deployment to verify health:

     php artisan vapor-ui:check-logs --since=10m
     

Gotchas and Tips

Pitfalls

1. Deprecation Warning

   • The package is archived and lacks Laravel 11 support. Migrate to Vapor’s built-in dashboard for long-term use.
   • Workaround: Fork the repo and update dependencies if you must use it with newer Laravel versions.

2. AWS Permissions

   • Ensure your Vapor credentials have vapor:logs:read and vapor:jobs:read permissions. Misconfigured IAM roles may block UI access.
   • Debugging: Check /vapor-ui/logs for permission errors (e.g., AccessDeniedException).

3. Log Retention

   • Vapor retains logs for 30 days by default. For longer retention, configure CloudWatch Logs retention policies separately.

4. Queue Job Limits

   • The UI paginates failed jobs (default: 50 per page). For large queues, increase the limit in config/vapor-ui.php:

     'failed_jobs_per_page' => 100,
     

5. Performance

   • Heavy log searches may time out. Use since filters to narrow time ranges:

     Route::get('/vapor-ui/logs', [VaporUIController::class, 'show'])->with(['since' => now()->subHours(1)]);
     

Debugging Tips

1. Clear Cache If the UI appears blank, clear Vapor’s cache:

   php artisan vapor:cache:clear
   

2. Log Level Filtering Filter logs by level in the UI or via the API:

   // In a custom controller
   $logs = \Laravel\VaporUI\Facades\VaporUI::logs()->level('error');
   

3. Environment-Specific Config Use environment variables to toggle the UI per environment:

   # .env.production
   VAPOR_UI_ENABLED=false
   

4. Custom Views Override the default Blade views in resources/views/vendor/vapor-ui to modify the UI (e.g., add your logo or branding).

5. API Access The UI exposes a RESTful API for programmatic access. Example:

   $failedJobs = \Laravel\VaporUI\Facades\VaporUI::failedJobs()->limit(10)->get();
   

Extension Points

1. Add Custom Metrics Extend the dashboard by adding tabs for custom metrics (e.g., database query logs):

   // In a service provider
   VaporUI::extend(function ($ui) {
       $ui->addTab('database', function () {
           return view('vendor.vapor-ui.tabs.database');
       });
   });
   

2. Webhook Notifications Integrate with Slack/PagerDuty by listening to vapor-ui.failed-job events:

   \Laravel\VaporUI\Events\FailedJobProcessed::listen(function ($job) {
       // Send alert
   });
   

3. Theming Customize the UI’s Tailwind CSS by publishing assets:

   php artisan vendor:publish --tag=vapor-ui-assets
   

   Then override resources/css/vapor-ui.css.