php dev tools integrated to your browser

Clockwork screenshot Clockwork screenshot Clockwork screenshot


This section describes how Clockwork internals work. While not needed for normal usage, this can be useful if you are planning on extending Clockwork with custom data sources, storage implementations, adding more in-depth support for your custom applications or unsupported frameworks or even writing a custom Clockwork client apps.

Clockwork consists of two components:

The communication between the two components happens via a rest-like HTTP API using JSON metadata format.

Server-side library

The Clockwork server-side library consists of several components:

Clockwork also has a main Clockwork class that ties everything together and includes bunch of helper methods.

While different Clockwork integrations work in different ways a typical usage looks like this:

Check out the "extending data sources" and "extending metadata storage" for information on writing your custom data sources and storage implementations.

Metadata HTTP API

The metadata HTTP API is the glue between the server-side data collecting library and the application presenting the data. By having a well specified rest-like API we can keep different versions of the Clockwork applications and the server-side library compatible and you could event write a fully custom Clockwork application compatible with the official server-side or vice-versa.

/__clockwork/{id} is the main and most important API endpoint. Application requests metadata about request identified by a particular ID, server-side returns the metadata in a JSON format.

While this is the only endpoint that is really required for the browser extensions to work and was the only endpoint available in the first version, there is a couple more endpoints required for various application features.

/__clockwork/latest returns the metadata about the last executed request. Used in extension to show the last request when first time opened and required for web UI.

/__clockwork/{id}|latest/next/{limit?} returns metadata for requests executed after request with specified ID or the latest request, with an optional limit. Required for the web UI.

/__clockwork/{id}|latest/previous/{limit?} returns metadata for requests executed before request with specified ID or the latest request, with an optional limit. Used to load older requests in applications.

Browser extension

The browser extension checks HTTP responses for the X-Clockwork-Version and X-Clockwork-Id headers. The X-Clockwork-Version header contains the version of the server-side component, while the header is required, the content is not important and is used only for new version notifications. More important is the X-Clockwork-Id which contains the unique identifier for the current HTTP request.

Once a request containing both of these headers is received, Clockwork retrieves the request metadata via a HTTP GET request to /__clockwork/{ID}. The metadata endpoint URI can be overridden via a X-Clockwork-Path header, if present, the request ID will be appended to the end of the header value. This endpoint should return the request metadata in the Clockwork metadata format.

Web UI

The web UI uses the same code as the browser extension, with only difference in the metadata retrieval. As we are not running as a browser extension and can't observe all executed HTTP requests, we use ajax polling instead.

When opened, the application makes a request to the /__clockwork/latest endpoint to load the latest request. After that we poll the /__clockwork/{id}/next endpoint with the last request id to get all newer requests.