Clockwork 3.0 now available

2018-07-30

What started as a major version increment to make some small breaking changes ended up as the biggest Clockwork release yet. With many new features and improvements both on the server-side and in the Clockwork application, many based on your suggestions. Let's take a closer look.

Clockwork 3.0 supports the latest Laravel and Lumen versions, Slim and for the first time Symfony. This is the first version not supporting Laravel 4, though you can still enjoy all the improvements of the Clockwork app.

To upgrade to the latest version simply change the version constraint in your composer.json:

"itsgoingd/clockwork": "^3.0",

Request tab, UI polish

As with every release, the Clockwork app got some UI polish, especially for the dark theme, which now has a less blinding highlight color. The request tab now shows the request method, url, controller and status with an ability to copy the request url.

Clockwork UI polish

Performance tab, new timeline UI

The timeline tab was reworked into a new performance tab. Showing the performance metrics like database, query and application execution time and newly collected peak memory usage. The timeline component got a completely new UI focused on the visual representation of the events.

Clockwork performance tab and timeline component

Database tab, table filters and ordering

The database tab now shows the query count and time right on top. One of the most useful additions is the new filtering and ordering support. In fact, every table can now be filtered and ordered, from request data to database queries. You can search for order_items to show only queries for that particular table, but Clockwork also supports contextual filters, eg. typing duration:>100 will show only queries taking more than 100 ms.

Clockwork database tab and filtering example

Log tab, pretty printing improvements

The log tab got some new colors to easily distinguish errors and warnings. One of the most useful Clockwork features, rich logging, was greatly improved. Arrays will be properly identified, showing the class names is no longer depth limited, recursion and binary database bindings are properly handled, protected and private properties are now clearly marked with a * and ~ prefixes respectively and different types are now clearly distinguished with new colors.

Clockwork log tab with rich logging examples

User-data, custom tabs

While Clockwork collects a lot of useful data by default and you can always use the rich logging capabilities, adding support for custom user-specified tabs was on the wishlist from day one. With the new user-data api this is now possible. You can add your own custom tabs with data represented in counters (like performance tab metrics) or tables (with ordering and filtering support).

Clockwork custom cart tab example

Xdebug profiler

While Clockwork provides a lot of performance metrics and profiling features like timeline events, finding the problematic spot in your application can still be hard. Xdebug is a PHP extension, which provides an advanced profiler, collecting metrics about every single function call. Clockwork now comes with a full-featured Xdebug profiler UI. You can find it in the new performance tab.

Follow the instructions on how to setup Xdebug and enable collecting profiles in the Clockwork app. The profiler UI will show you a breakdown of all function calls with their self and inclusive cost. You can toggle between execution time or memory usage metrics, exact or pecentual representation and of course the data is orderable and filterable.

Clockwork performance tab with Xdebug profiler

Authentication support

Clockwork collects a lot of sensitive data. Typically you will run Clockwork only in your local development environment where this is not an issue. In some cases though, you might have a shared development or staging server. For these situations we now support a very simple authentication using a single shared password. The authentication support is extensible so you could for example write an authenticator against a database table.

It is still not recommended to run Clockwork in production or environments that might contain sensitive customer data. Please make sure you understand the details of the authentication implementation if you plan to use it in a sensitive environment.

Clockwork authentication prompt example

Symfony integration BETA

For the first time, Clockwork adds a Symfony support. The Symfony integration works quite differently from the existing Laravel or Slim integrations. While in the existing integrations we collect all the data, in Symfony we build on top of the existing Symfony profiler component. This means we can show all the data you can already see in the WebProfilerBundle, but we can't support all Clockwork features that require us to store additional data, like rich logging or the new Xdebug profiler.

We call this a beta since the testing was limited to a few demo Symfony applications so far. The integration will be improved and support for more Clockwork features added in the future. Please let us know if you decide to try it out.

Clockwork example with Symfony app

Stack traces, dark theme in web UI

There is a lot more smaller changes to talk about. We introduced collecting caller file name and line number a long time ago, now we support logging full stack traces. This might be a lot of additional data, so you can disable the feature in the config. Web UI now supports dark theme, you can change the default theme in the Clockwork config, but every user can enable or disable the dark theme by appending ?dark=1 or ?dark=0 to the url. This setting will be preserved in the browser.

Clockwork web UI dark mode with stack trace example

Performance improvements

Performance and reliability was also a focus area in the Clockwork app. The requests list behaviour was improved and metadata fetching is now more reliable. You should see way less of empty or duplicate requests and an error message will be shown instead of requests being stuck in a broken empty state. Whole application was rewritten to not use jQuery with a couple of other minor performance improvements.

Subrequests, advanced features

From a more advanced new features, subrequests allow you to see requests made by your application to other Clockwork-enabled applications. Laravel contracts are now type-hinted instead of concrete implementations. SQL storage now has indexes for faster querying.

Breaking changes

A new major release brings a few breaking changes. Laravel 4 is no longer supported, Clockwork now requires Laravel 5.0 or higher and works with all versions of Lumen. PHP 5.4 is no longer supported, PHP 5.5 and up is required. If you are affected by these breaking changes, a new 2.3 version was released with updated web UI. The browser extensions are also backwards compatible with all past server-side versions.

The Clockwork Chrome extension always required a bunch of privacy permissions. Yet we never documented why do we need them or how do we use them. Now you can read about existing and newly required privacy permissions on the Clockwork website.

The Clockwork website was also updated to include much more extensive documentation, including all the new features of 3.0 release and a full changelog.

I hope you will enjoy this release as much as I enjoyed working on it, please feel free to contact me with any feedback via the GitHub issues or email at info@underground.works.