Install the Clockwork library via Composer.
$ composer require itsgoingd/clockwork
Initialize Clockwork early in your application.
$clockwork = Clockwork\Support\Vanilla\Clockwork::init();
If you are using a dependency injection container it might be a good idea register the Clockwork instance.
Right before sending a response, we need to tell Clockwork to resolve and store metadata for current request.
$clockwork->requestProcessed();
We also need to setup a Clockwork REST API endpoint. This endpoint is used by the Clockwork clients to load metadata for your application requests.
By default Clockwork clients expect the data at /__clockwork
URI. If your application uses a router, you can simply setup a GET route for this URI and pass rest of the URL to Clockwork.
$router->get('/__clockwork/{request:.+}', function ($request) {
$clockwork = Clockwork\Support\Vanilla\Clockwork::init();
return new JsonResponse($clockwork->getMetadata($request));
}};
In a very simple app without router you can use a separate script. In this case we will also need to tell Clockwork where to load the data from using the api
option.
// clockwork.php
$clockwork = Clockwork\Support\Vanilla\Clockwork::init([ 'api' => '/clockwork.php?request=' ]);
$clockwork->returnMetadata();
In the first example we used the getMetadata
method which returns the metadata as an array, the returnMetadata
will also json-ecncode the data, send it to output and set appropriate headers.
Clockwork support in a PSR-7 application can be implemented as a middleware.
return $clockwork->usePsrMessage($request, $response)->requestProcessed();
In this case Clockwork will use the data from the PSR-7 request and return the PSR-7 response extended with Clockwork headers.
The vanilla Clockwork integration can be configured by passing a configuration array to the init
method.
$clockwork = Clockwork\Support\Vanilla\Clockwork::init([
'storage' => 'sql',
'storage_database' => 'sqlite:' . __DIR__ . '/clockwork.sqlite'
]);
You can find the full list of options with descriptions in the configuration file.
You can also configure most options via environment variables, in this case you don't have to pass them to the init
method.
Clockwork includes a clock
global helper function providing easy access to Clockwork features from anywhere in the app.
The clock
helper is disabled by default in the vanilla integration, to enable the helper, use the register_helpers
option.
$clockwork = Clockwork\Support\Vanilla\Clockwork::init([ 'register_helpers' => true ]);
clock('Log', 'something');
clock()->addDatabaseQuery('SELECT * FROM users WHERE id = 1', [], 10);
There are many ways to make database queries in a vanilla PHP application. That's why unlike a framework integration, it's up to you to register the executed database queries.
To do so, you can use the Clockwork addDatabaseQuery
method in your database abstraction layer. If you don't have one, you can write a simple helper function or class for making queries, eg. this helper function for executing queries using PDO and logging them to Clockwork.
function database_query($pdo, $query, $bindings) {
$time = microtime(true);
$stmt = $pdo->prepare($query);
$stmt->execute($bindings);
$results = $stmt->fetchAll();
clock()->addDatabaseQuery($query, $bindings, microtime(true) - $time);
return $results;
}
You can use a similar approach to logging cache queries, events, sent emails, etc. see the source of the main Clockwork class for a list of all available methods.