How to debug PHP errors in a snippet

When a PHP snippet fails, Code Snippets disables it and keeps the error for you. This article shows where to find it, what the common errors mean, and how to see the ones that don't disable the snippet.

Where the error shows up

• The snippets list. The failed snippet's status reads Auto-Disabled, and the Status filter has an entry for it.
• The edit screen. Open the snippet. The error message, the stack trace and the error date sit at the top.
• The Error Logs page. Click Error Logs in the toolbar of the snippets list. Each snippet gets its own log file under administrator/logs/tassos_code_snippets/, and the page lets you read and clear them.
• Your inbox. The site's administrator email address receives the error details.

The log file and the email are on by default. Turn them off in the component's Options, under Log Errors and Notify Admin.

What disables a snippet, and what doesn't

Any exception or error the snippet throws disables it. Since version 1.0.2 so does a fatal error PHP can't throw: a function or class declared twice, exhausted memory, or the execution time limit. The snippet goes to Auto-Disabled and the next request works.

Two cases leave the snippet published. A plain exit() or die() ends the request without an error. A loop that only waits (a sleep(), a slow HTTP call) never reaches PHP's time limit on Linux, so it hangs instead. For both, safe mode pauses every snippet so you can get in and fix it.

Common errors and their fixes

Call to undefined function, or class not found

A Joomla class is used without its namespace. Add a use line at the top of the snippet, for example use Joomla\CMS\Factory;, or write the full name: \Joomla\CMS\Factory::getApplication().

Cannot redeclare function

Two published snippets declare the same function, so the second one fails and gets disabled. Keep shared functions in one snippet, give the others a prefix, or guard the declaration:

if (!function_exists('my_helper'))
{
    function my_helper()
    {
        // ...
    }
}

Maximum execution time exceeded

A loop that never ends, or one that waits on a slow service on every request. Check the loop's exit condition, and keep slow HTTP calls behind a condition or a cache so they don't run on every page.

Seeing warnings and notices

Warnings, notices and deprecations don't disable the snippet and don't reach the log. To see them, set Error Reporting to Maximum under System → Global Configuration → Server, on a staging site. They then print on the page.

Debugging without a debugger

Queue a message to prove a line is reached, or to look at a value. It shows in Joomla's message area on the site and in the administrator:

use Joomla\CMS\Factory;

$app = Factory::getApplication();
$app->enqueueMessage('Reached line 12, user id ' . $app->getIdentity()->id, 'notice');

For values you want to keep, write them to a log file in administrator/logs:

use Joomla\CMS\Log\Log;

Log::addLogger(['text_file' => 'my-snippet.php'], Log::ALL, ['my-snippet']);
Log::add('Reached line 12', Log::INFO, 'my-snippet');

When several snippets interact, unpublish all but one and add them back one at a time.

Re-enable the snippet

Fix the code, set Status back to Published and save. Saving a published snippet clears the stored error and its date.

If the snippet runs but nothing happens, Why your PHP snippet isn't running has the checklist. The PHP snippet docs cover the events, the document type check and the blocked functions.