Clockwork: PHP Debugging Data in the Browser, Explained for Laravel and Plain PHP

What Clockwork's server-side component actually collects

Clockwork is a development tool for PHP that runs in the browser. The repository holds the server-side component, which means the part that gathers data inside your application and exposes it for a client to read. The README lists what that data includes: request data, performance metrics, log entries, database queries, cache queries, redis commands, dispatched events, queued jobs and rendered views. Collection is not limited to HTTP requests either. According to the README, artisan commands, queue jobs and tests can also be collected, and that requires enabling the feature in the config file.

The audience is narrow and specific. If you write Laravel applications and want to see why a page is slow or which query fired, Clockwork targets you directly. If you write framework-free PHP, the library still installs, but the README's examples lean on Laravel idioms such as the vendor:publish and route:cache Artisan commands, and the helper functions assume a Laravel-style application context. The value proposition is not a new runtime or a new extension. It is a data collector plus a viewer, and the viewer is where the product lives.

How data flows from your app to the Clockwork interface

The architecture is a producer and a set of consumers. The server-side component sits inside your application and records events as they happen: a query executes, a log line is written, a timeline event begins and ends. That recorded data is stored, and three clients can read it. The web interface at the /clockwork route shows all executed requests, which the README notes is useful when the request is not made by a browser, for example an API you are developing for a mobile client. A browser extension for Chrome and Firefox reads the same data from dev tools. A toolbar can also be embedded in your app, and the README states it is fully rendered client-side and needs a small JavaScript library installed.

Collection is governed by mode and filters rather than by a single on/off switch. Clockwork is only active when the app is in debug mode by default, and the README describes alternatives: explicitly enable or disable it, or set it to always collect data without exposing it for analysis. On-demand mode collects only while the Clockwork app is open, and you can set a secret in the app settings to authorize collection. Errors-only mode records only requests ending in 4xx and 5xx responses. Slow-only mode records requests above a configured slow threshold. A custom closure can filter collected and recorded requests, and CORS pre-flight requests are skipped by default. Stack traces are collected for log messages and database queries, with the last 10 frames kept by default; the frame limit can be changed or the feature turned off.

Installing Clockwork with Composer and making a first request

Installation is one Composer command. The README gives it directly and then says you are done.

composer require itsgoingd/clockwork

After that, the README states Clockwork is active when the app is in debug mode by default, so the first thing to confirm is that debug mode is on in your environment. Then make any request to your application and visit the /clockwork route in the browser. You should see the request you just made listed, and opening it shows the collected data for that request.

If you want command, queue job or test profiling, the README says to publish the configuration file via the vendor:publish Artisan command, then enable the relevant features in that file. There is one gotcha the README calls out explicitly: if you use the Laravel route cache, refresh it with the route:cache Artisan command.

php artisan vendor:publish
php artisan route:cache

For inline debugging, the clock() helper is the shortest path. The README shows that it returns its first argument, which lets you wrap a value in place without restructuring the surrounding code.

clock(User::first(), auth()->user(), $username)

The README also shows wrapping a call in place, so the logged value passes straight through.

User::create(clock($request->all()))

To set a log level, the README uses the long-form call.

clock()->info("User {$username} logged in!")

For timing a block of work, the timeline API uses a begin and end pair, or a closure with array-based configuration.

clock()->event('Importing tweets')->color('purple')->begin();
clock()->event('Importing tweets')->end();

The README also documents a closure form, which is easier to keep correct because the end call cannot be missed on an early return.

clock()->event('Updating cache', [ 'color' => 'green' ])->run(function () {
});

Where Clockwork stops being the right tool

Clockwork is a development aid, and the README's defaults enforce that. Because it is only active in debug mode by default, a production deployment with debug off collects nothing unless you change the configuration. Turning collection on in production is possible, and the always-collect-without-exposing mode exists for that, but the data then has to go somewhere, and the README does not document retention, rotation or storage growth for the collected records. That silence matters if you are considering it as a lightweight production observability layer. It is not one, and the documentation does not claim it is.

The second boundary is stack traces. Collecting the last 10 frames of every log message and query is a real cost on a busy request, and the default is a compromise between useful context and overhead. The README offers a frame limit and a disable switch, which tells you the authors expect this to matter at some point. If your debugging question requires the full call chain, ten frames will not answer it.

The third boundary is the interface itself. The /clockwork route and the browser extension are built for a human looking at one request at a time. There is no aggregation view described in the README, no alerting, and no way to query across many requests. If your problem is a slow endpoint under load, or a query that only misbehaves for one percent of traffic, the slow-only and errors-only filters narrow what is recorded but do not give you distribution data. A dedicated APM tool answers that class of question; Clockwork answers the question of what happened in this one request, in detail.

Clockwork compared with Xdebug and Laravel Telescope

The closest alternatives differ in mechanism, not just in features. Xdebug is a PHP extension that hooks into the interpreter itself, which lets it do step debugging and full stack traces at a level Clockwork cannot reach from userland. The trade-off is setup: an extension has to be installed and configured at the PHP level, and step debugging changes how the request executes, which makes it a poor fit for looking at a page as it normally behaves. Clockwork records passively and shows a finished request, so it never alters execution flow, but it cannot pause and inspect a variable mid-request.

Laravel Telescope is the other natural comparison, since it is also a Laravel package that records requests, queries and logs for viewing in the browser. The difference in approach is scope and coupling: Telescope is built for Laravel and tracks Laravel-specific concepts closely, while Clockwork's server-side component is installable in plain PHP projects and reaches beyond HTTP into artisan commands, queue jobs and tests. If you are on Laravel and want a first-party-feeling debugging dashboard, Telescope is the more integrated choice. If you want one tool that also covers CLI commands and queued work, Clockwork's collection scope is wider. The README does not offer a comparison of the two, so treat that as a judgment about scope rather than a documented claim.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-08-29. The most recent tagged release listed is v5.2.0 from 2024-02-24, alongside v5.1.12 and v5.1.11 tagged the same day. That gap between the last release and the last push is worth noticing: the codebase is receiving commits, but the version you install from a version constraint may be older than what is on master. If you pin to ^5.2, you are pinning to a tag from early 2024.

The licence is MIT, which is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That is a statement about the licence text, not legal advice, and the LICENSE file in the repository root is the authoritative source. MIT imposes no copyleft obligation on your application, which is the practical reason a library like this can be dropped into a commercial codebase without a licensing review.

The upgrade cost is mostly configuration drift. Clockwork reads a published config file, and features such as command, queue job and test collection are opt-in there. When you upgrade across minor versions, the config file you published earlier does not update itself, so new options and changed defaults will not reach you until you republish and merge. The README does not document a rollback procedure, and the repository's CHANGELOG.md is the place to check what changed between tags before you move a constraint.

Editorial conclusion

Adopt Clockwork if you develop Laravel or PHP applications locally and want query, log and timeline data without wiring up a profiler by hand; the composer require itsgoingd/clockwork step and the /clockwork route are the whole setup in the default case. Do not adopt it as a production monitoring tool: the README states Clockwork is only active in debug mode by default, and the on-demand, errors-only and slow-only modes are collection filters, not an alerting system. Before relying on it, verify that your config file has been published, that you have refreshed the route cache if you use one, and that stack-trace collection at the default 10-frame limit is enough for the queries you care about.

Frequently asked questions

Official sources

1. itsgoingd/clockwork on GitHub
2. License: MIT
3. Project website
4. README
5. Releases