Clockwork 3.1 vanilla integration docs

vanilla.md

Installation

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.

PSR-7 applications

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.

Configuration

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.

The clock helper

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);

Registering database queries

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.