Clockwork Laravel Package

Getting Started

Start by installing via Composer: composer require itsgoingd/clockwork. For Laravel, publish the config with php artisan vendor:publish --tag=clockwork. In development (APP_DEBUG=true), Clockwork works immediately—visit /clockwork to see collected data. For immediate first use, add clock('Hello, Clockwork!') anywhere in a controller or route closure, refresh the page, and open the Clockwork panel in your browser to see the log. Enable collection for Artisan commands, queue jobs, or tests via config/clockwork.php and the corresponding collect_... flags.

Implementation Patterns

• Inline debugging: Replace dd()/var_dump() with clock($data)—it returns the passed value, so use it in method chains: User::create(clock($request->validated())).
• Timeline profiling: Wrap critical operations with clock()->event('Importing tweets')->color('purple')->begin(); ... clock()->event('Importing tweets')->end(); or use clock()->event('Cache refresh', ['color' => 'green'])->run(fn() => $this->refreshCache()).
• Structured logging: Use context-aware logs: clock()->info('User login', ['user_id' => $user->id])—this appears in the Logs tab with rich metadata.
• Targeted collection: In clockwork.php, configure collect_data and collect_requests to use modes like on_demand, errors_only, or slow_only. Set a custom closure in should_collect to restrict profiling to specific IPs, routes, or headers (e.g., only when X-Clockwork-Request: 1).
• Testing integration: Enable collect_tests => true and run php artisan test --clockwork; tests will appear in the Clockwork UI—great for debugging feature test failures.

Gotchas and Tips

• Security note: By default (v5.2+), Clockwork only runs on local domains (localhost, test, wip, etc.). To use on staging/qa, set CLOCKWORK_ENABLE=true or set 'enable' => true in config.
• Octane warnings: If using Laravel Octane, ensure clockwork.php’s storage driver is set to file or redis (SQL storage may cause issues). Clear cached routes/middleware after enabling Clockwork middleware manually.
• Middleware ordering: If registering Clockwork\Support\Laravel\ClockworkMiddleware manually (e.g., in Laravel 10+), place it after TrustProxies but before SubstituteBindings to ensure correct client IP and route resolution.
• Debugging empty panels: Check if /clockwork/meta returns JSON—nil response indicates middleware disabled or config 'collect_data' => false. Also verify storage_path('clockwork') is writable.
• Performance: Timeline and stack traces add overhead—consider disabling 'collect_stack_traces' or reducing 'stack_traces_limit' in production-like dev environments.
• Pest + PHPUnit: When collecting tests, ensure phpunit.xml includes clockwork in php <env> or use clock()->collectTest(true) inside test methods for granular control.
• CORS preflight: These are ignored by default—no config needed unless explicitly collected via collect_requests.