DebugKit for CakePHP 3.0.0

A few weeks back during CakeFest 2014, I had the opportunity to hunker down and get DebugKit upgraded to CakePHP 3.0. While it was less of an upgrade and more of a re-design and re-write, I think the end results justify the drastic approach I took. First, a few of the problems I was trying to solve in the new version:

1. It is hard to make DebugKit look great as it lives on the same page as your app. Because the application CSS can easily apply to DebugKit it often ends up looking inconsistent or bad in many applications.
2. DebugKit adds gobs of HTML to the page which slows down application response times, often in very noticeable ways.
3. The history mode for DebugKit is very fragile.

With these problems in mind I felt that all 3 could be solved by re-designing how DebugKit interacts with an application, and how it stores its data. To make DebugKit more light weight, AJAX could be used to fetch panels on demand and put them into the DOM. However, using javascript can be tricky as I don’t know what is going to be on the page, and can’t rely on things like jQuery or other libraries. Often developers use incompatible versions of jQuery which breaks DebugKit. Next, because DebugKit is installed as a component it can be hard to install. I wanted to make the installation dead simple.

Iframes and SQLite to the rescue

By designing DebugKit to be hosted in an iframe I was able to solve the CSS pollution issues, force a light-weight AJAX based approach, and be able to rely on any javascript library I wanted. I quickly hacked up a prototype to ensure I would be able to use iframe messaging to resize the toolbar as needed. As the panels are being loaded lazily, I would need a semi-permanent place to store the data, and a SQLite database was a perfect fit. This made the general architecture of DebugKit as follows:

1. The host application loads the plugin, which adds a dispatcher filter.
2. The dispatcher filter attaches event listeners for each panel, and saves the results into a SQLite database when the request is complete.
3. If the request is an HTML one, the dispatcher filter injects a small javascript file into the page.
4. Once the page has rendered, the small script file uses only native browser features to inject the iframe that hosts the toolbar and panels.
5. Each panel’s data is loaded via AJAX on-demand and inserted into the iframe.
6. Because iframes cannot resize themselves, the iframe buttons pass messages to the host page telling the loader script what dimensions to make the iframe.
7. Because all panels and data are loaded via XHR, the history mode works exactly the same as the standard operation.

Another interesting trick I used was that the SQLite database is created automatically. If the plugin detects that the schema is missing it will automatically create the required schema using the test fixtures. This meant I could avoid any dependencies on migrations or complicated installation instructions.

Updated visuals

Not only has the functionality of DebugKit been updated for 3.0, the visual design has been refreshed as well:

New features

On top of a faster/lighter architecture, and updated visuals DebugKit has several new features as well:

• Cache panel – A new panel has been added to track cache operations and allow you to easily clear your application caches.
• ORM auto model warnings – Auto-models can be a confusing feature if you don’t know they are being used. DebugKit will now warn you if your application uses any auto models.
• Summary data – As you may have seen in the screenshots, for panels that it applies to, the toolbar will show summary data. This lets you get a quick overview without having to open panels.

I’ll be updating the various other plugins I maintain in the next few weeks. I’ve already completed updating the Geshi Helper and will be working on AssetCompress next.