Laravel Totem Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require studio/laravel-totem
   php artisan migrate
   php artisan totem:assets
   

2. Cron Configuration: Ensure your server runs:

   * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
   

3. Access Dashboard: Visit /totem in your local environment (or configure auth via Totem::auth() in AppServiceProvider).

First Use Case

Schedule a command (e.g., email:send-welcome):

1. Navigate to /totem.
2. Click "Create Task".
3. Select the command from the dropdown.
4. Define a schedule (e.g., dailyAt('09:00')).
5. Save. The task now appears in the dashboard and runs per your cron schedule.

Implementation Patterns

Core Workflows

1. Command Scheduling

• Dynamic UI: Use the dashboard to create/edit schedules without touching app/Console/Kernel.php.
• Parameters: Pass arguments/options via the "Command Parameters" field (e.g., name=John --force).
• Hidden Commands: Exclude commands by setting protected $hidden = true in the command class.

2. Task Management

• Enable/Disable: Toggle tasks via the dashboard UI (no code changes).
• View Output: Click a task to see execution logs, duration, and status.
• Bulk Actions: Select multiple tasks to enable/disable or delete them.

3. Notifications

• Email: Built-in (configure via Laravel’s mail settings).
• SMS/Slack: Install laravel/vonage-notification-channel or laravel/slack-notification-channel and configure in config/totem.php.

4. CLI Integration

• List all scheduled tasks:

  php artisan schedule:list
  

• Useful for scripts or CI/CD pipelines.

Integration Tips

Custom Authentication

Override default auth (e.g., for team access):

Totem::auth(function ($request) {
    return $request->user()->hasRole('admin');
});

Cache Configuration

For multi-server setups (e.g., separate Redis for UI/workers):

TOTEM_CACHE_STORE=redis-shared

Disable caching entirely (direct DB queries):

TOTEM_CACHE_STORE=array

Command Filtering

Reduce dropdown clutter in the UI:

'artisan' => [
    'command_filter' => ['stats:*', 'email:daily-reports'],
    'whitelist' => true, // Default; set to false for blacklist
],

Middleware Customization

Change from web middleware (e.g., to api):

TOTEM_WEB_MIDDLEWARE=api

Table Prefix

Avoid conflicts with existing tables:

TOTEM_TABLE_PREFIX=totem_

Gotchas and Tips

Pitfalls

1. Cron Misconfiguration:

   • Issue: Tasks don’t run.
   • Fix: Verify cron is set to * * * * * cd /path && php artisan schedule:run >> /dev/null 2>&1.
   • Debug: Check logs with php artisan schedule:work (manual test).

2. Cache Inconsistency:

   • Issue: UI shows stale task status.
   • Fix: Ensure TOTEM_CACHE_STORE points to a shared cache (e.g., Redis) or disable caching (array).

3. SQLite Rollback:

   • Issue: migrate:rollback fails.
   • Fix: Use php artisan totem:migrate:fresh or manually drop tables.

4. Hidden Commands:

   • Issue: Commands don’t appear in the dropdown.
   • Fix: Ensure protected $hidden = false in the command class.

5. Parameter Parsing:

   • Issue: Command arguments/options fail.
   • Fix: Use the exact format:

     name=value --option=value
     

     Avoid spaces around = or --.

Debugging Tips

1. Task Output:

   • Empty output? Check for malformed JSON in logs (fixed in v12.0.2 with Js::from()).
   • Use php artisan totem:clear-cache to refresh the UI.

2. Route Conflicts:

   • Issue: /totem conflicts with other routes.
   • Fix: Override the route in routes/web.php:

     Route::prefix('admin')->group(function () {
         Route::get('totem', [\Studio\Totem\Http\Controllers\TaskController::class, 'index']);
     });
     

3. Vue 3 Migration:

   • Issue: UI breaks after updating to v12.0.0+.
   • Fix: Clear Vite cache:

     npm run dev
     

Extension Points

1. Custom Notifications:

   • Extend Studio\Totem\Notifications\TaskCompleted to add logic (e.g., Discord webhooks).

2. Task Events:

   • Listen for task:scheduled, task:completed, or task:failed events in EventServiceProvider.

3. UI Customization:

   • Override Blade views in resources/views/vendor/totem.
   • Extend Vue components in resources/js/totem.

4. Database Connection:

   • Use TOTEM_DB_CONNECTION in .env for multi-database setups.

Pro Tips

• Calendar View: Use the upcoming calendar (v11.3.0+) to visualize schedules.
• Environment Restrictions: Restrict /totem to local or staging in config/totem.php:

  'environments' => ['local', 'staging'],
  

• Backup Tasks: Export/import schedules via php artisan totem:export/import.