Running like clockwork: Better developer tools with the Clockwork module

A common request on the SilverStripe mailing list, forums, and user voice site over the years has been the desire for an improved developers toolbar, similar to what other frameworks such as Symfony have. These toolbars often make available extensive information about an http request - from the contents of $_SERVER, $_REQUEST, $_COOKIES, etc to logging and database queries. Many of these features are available with SilverStripe through url parameters such as ?showqueries=1 but are neither pretty nor easy to use.

Enter Clockwork

Our team at Adair Creative Group uses SilverStripe for 95% of the work we do. A few months ago I was working on a project using the popular Laravel framework when I came across a wonderful Chrome extension called Clockwork. It extends Chrome's built-in developer tools by adding a tab with information specific to php and the application framework including routing, execution timeline, database queries, logging - everything in fact that I'd seen in Symfony, Kohana, etc. It comes bundled with support for Laravel and Slim, and is easy enough to integrate with any framework.

With just a few hours hacking and a some help from a few others in the SilverStripe community I was able to put together a SilverStripe module utilizing most of the features of Clockwork.

How to get started

The best way to install the module is with Composer, which insures that clockworks server side components and its dependencies. 

composer require markguinn/silverstripe-clockwork dev-master

You'll also need to install the Chrome extension And put your site in dev mode via _ss_environment.php or ?isDev=1. If your site is in live or test mode the extension will automatically disable itself. 

Open your site in Chrome with the developer tools enabled and the Clockwork tab visible. Every request will now log:

• basic timing of framework initialization and controller routing
• any calls to SS_log::log
• all database queries, including query times
• php request, cookie, and server information 

Advanced usage

Logging

Any use of SilverStripe's built in logging (with the exception of Debug::log) will go to Clockwork as well as whatever files or email writers you have configured. For example:

SS_Log::log("well, that happened...", SS_Log::INFO);

If you use Monolog instead there is a ClockworkWriter class that comes bundled but you'll need to set it up yourself manually or via the injector.

Adding custom timeline entries

Basic framework, routing and controller events are added to the execution timeline automatically and it's often useful to add your own events to keep an eye on how long certain sections of code are taking and find bottlenecks. This is easy to do:

Injector::inst()->get('ClockworkTimeline')->startEvent('myevent1', 'Description of the event');

// ... do the things ... //

// this will happen automatically when the request ends
Injector::inst()->get('ClockworkTimeline')->endEvent('myevent1');

Limitations

• Only works with Chrome. There is an embeddable web app version and a Firebug plugin however.
• Doesn't register failed requests
• Isn't aware of site structure. I'd suggest using this module in concert with something like Better Navigator.

How to help

• Bug reports 
• Help integrate the embeddable web version. Pull requests are always welcome at https://github.com/markguinn/silverstripe-clockwork
• Brainstorm more and better ways to utilize and integrate - especially things like the timeline events.