Cowboy-Debugging TYPO3

Debugging is hard. Debugging PHP code is harder. And debugging TYPO3 code is probably the hardest.

Of course there is Xdebug, but in practice there are a lot of situations where you can’t use it, so most people, including myself, simply don’t use it at all. Of course we should, but we don’t. This is why a lot of PHP developers fall back to something I would call Cowboy Debugging (see Cowboy Coding).

Let’s face it: Most PHP developers use echo, print_r() or var_dump() to output variable contents during development or to understand crazy control flows. Unfortunately those methods often don’t work in bigger frameworks like TYPO3, where objects become so large that var_dump() exceeds the memory limit.

This is where TYPO3’s own debugging functions come into play:

DebugUtility::debug

\TYPO3\CMS\Core\Utility\DebugUtility::debug(
    $var = '',
    $header = '',
    $group = 'Debug'
)

A clear advantage of this function is that it is optimized both for frontend and backend output. This means that in the backend the debug output will be displayed in tabs at the bottom of the content frame. Those tabs don’t block your view on the actual backend page you are trying to debug. You can even change the size of the tab area and close tabs you don’t need anymore.

However I’m finding it quite hard to understand the structure of big arrays and objects because of the crazy syntax debug() uses:

$myVariable = array(
    'test' => array(
        'test2' => array(
            'key' => 'value'
        )
    )
);
\TYPO3\CMS\Core\Utility\DebugUtility::debug($myVariable, 'Header title', 'Group title');

Frontend output:

DebugUtility::debug() frontend output

Backend output:

DebugUtility::debug()

Let’s take a look at another one:

DebuggerUtility::var_dump

\TYPO3\CMS\Extbase\Utility\DebuggerUtility::var_dump(
    $variable,
    $title = NULL,
    $maxDepth = 8,
    $plainText = FALSE,
    $ansiColors = TRUE,
    $return = FALSE,
    $blacklistedClassNames = NULL,
    $blacklistedPropertyNames = NULL
)

This is ExtBase’s little debugging helper, which by the way is also used in Fluid templates:

<f:debug>{myVariable}</f:debug>  

It looks like this:

$myVariable = array(
    'test' => array(
        'test2' => array(
            'key' => 'value'
        )
    )
);
\TYPO3\CMS\Extbase\Utility\DebuggerUtility::var_dump($myVariable, 'My Title');

This function provides a much more readable output compared to the core function. For starters it collapses all objects and arrays by default so you get a nice overview of your output. Then you can start expanding the parts of the output that are interesting to you which helps you staying focussed. The function also allows you to specify a maximum of depth so you can even output very large objects without running into memory limits.

However there is one problem: The ExtBase debugger utility is clearly not optimized for backend use. In practice this means that you won’t always be able to see all outputs: If you put a couple of debugger calls in a CommandController you will only see those fitting the height of your browser window, the remaining outputs are lost below the fold. As there is no way to close boxes the only choices you have are to reduce the number of debug outputs or to mess around with the DOM inspector of your browser’s developer tools.

debug

I probably should mention that there is also a global debug() function which itself calls DebugUtility::debug(). It also checks the devIPmask setting to make sure that only developers see the debug output. It even allows you to replace the debug utility with your own.

I personally don’t use the function because of the configuration hassle. This is especially true if you work with a lot of TYPO3 instances, set up by different people on different servers with different TYPO3 versions. However for some people debug() might be the right choice.

To summarize …

I clearly prefer the ExtBase debug utility to the core utility in most cases. However it is probably a good idea to know them both, as well as their strengths and weaknesses.

I leave you with a few more debugging tips:

  • When in doubt, delete all caches.
  • Sometimes white pages can be fixed by wrapping your code in a try … catch block and outputting the exception messages (especially true for CommandController instances)
  • Yup, debugging database queries in ExtBase is that hard. Good luck.