Errors and debugging

On a live site visitors see a short error page and the details go to PHP's error log. Debug mode shows a developer everything at once.

Debug mode

The only switch is site.debug in the site's configuration: 1 on, 0 off. The installer writes 0. Turn it on only on a development copy: with debug mode on, error pages show server paths and the call chain, and anyone can open the XML of any page. php index.php setup check fails while it is on.

With debug mode on:

  • PHP displays errors;
  • ?debug after a page's address returns the page's XML document: its properties, the XML of every component, the interface strings, the scripts and the database queries with their count;
  • ?struct returns the tree of the page's layout and content with the classes of its components;
  • error pages show the message, the file and the line, and the call chain;
  • a picture the resizer can't find shows as a grey placeholder.

Without debug mode ?debug and ?struct are ignored, and the page is the usual HTML.

What visitors get

Answer When
404 an unknown address; a page switched off in this language; a language in preparation, for anyone but an editor; a page the visitor has no right to see
403 an admin window or action that needs rights the user does not have
422 a form without its token or from another site; a change — delete, move, switch on — asked for without POST
500 an error the code did not expect

The 404 and 403 pages keep the site's layout: the site's own site/modules/main/templates/layout/error.layout.xml if there is one, else the core's, with the interface strings TXT_ERROR_404, TXT_ERROR_403 and TXT_ERROR_HINT. The 500 page stands outside the layout: the error's text, a link to the home page and noindex. Outside debug mode its text is «Ошибка на сервере. Попробуйте ещё раз позже.» (Server error. Try again later.), and the details go to the log. Requests of the admin get the error as JSON: {"result": false, "errors": [{"message": …}]}.

A refused form answers 422 rather than 403 because hosting panels often put their own page in place of a 403. If your hosting panel serves its own error pages, switch that off for the site, or visitors get the panel's pages instead of the site's.

PHP warnings stop the page

All PHP errors are reported. A warning or a notice is not ignored: it stops the page as an error, the visitor sees the error page and the log gets the message with its file and line. Only deprecation notices are logged and let the page go on, so a newer PHP does not break the site.

The log

Simple keeps no log files of its own: it writes to the site's PHP error log, without levels or rotation. Its lines begin with:

Line What
Energine: <class>: <message> @ <file>:<line> an error the visitor did not see in detail
PHP error <N> thrown as SystemException: … a PHP warning or notice that stopped a page
PHP Deprecated: … a deprecation notice
Mail: <reason> a letter that was not sent
Register: …, UserProfile: … a failed registration or profile save

The database keeps journals, not errors:

  • «Журнал действий» (Action log) at /admin/action-log/: saves and deletes in the admin and saved texts — who, what and when;
  • the history of each text: its last 20 versions in each language;
  • failed sign-ins of the last 15 minutes, for the sign-in limits.

Checks

  • php index.php setup check — before a site is handed over; see Your first site.
  • php index.php setup checklinks — broken links in texts; exits with code 1 if it finds any.

The repository's own tests are in tests/ and are described in tests/README.md. They read the site's configuration and tests/local.php — the administrator's e-mail and password, a local mailbox and the path of the PHP error log; make it from tests/local.php.example, readable by its owner only. They call php8.5, the mysql client and curl; run them from the repository as the site's user.

  • bash tests/smoke-final.sh reads every page as a guest and as the administrator and reports new lines in the PHP log. It changes nothing and is safe on a live site.
  • bash tests/regression.sh runs every suite against the site's database: it creates and removes test records, and its sign-in test locks this machine's address for a while. Run it on a test copy — tests/tools/stand.sh starts one with its own MariaDB and PHP's built-in server.