Development Debugging

From Cloudrexx Development Wiki
Jump to: navigation, search

Usage

Development tools under Global Configuration

There are several ways on how debugging can be enabled in Cloudrexx:

Backend

Debugging can be enabled under Administration > Global Configuration > Development tools in the Backend. This will enable the debugging on a per-session basis. Meaning that the debugging will only be enabled for the user who has enabled it. All other users won't be affected by the debugging output.

PHP

Debugging can be activated/deactivated using the following two commands:

// activate debugging
\DBG::activate();
// deactivate debugging
\DBG::deactivate();

Both methods \DBG::activate() and \DBG::deactivate() accept a bitwise combination of the available debug flags (see Debug Flags). Therefore you can individually activate/deactivate each debug flag throughout your code.

Example:

// activate PHP error-reporting + log to firephp console
\DBG::activate(DBG_PHP | DBG_LOG_FILE);

[...]

// later in the code, activate ADOdb error log to monitor some specific SQL queries
\DBG::activate(DBG_ADODB_ERROR);

[...]

// deactivate ADOdb error log for rest of page request (could be activated again later in the code if needed)
\DBG::deactivate(DBG_ADODB_ERROR);

// deactivate whole debugging output
\DBG::deactivate();

Logging

The methods \DBG::dump(), \DBG::log() and \DBG::msg() can be used to output custom debug information:

// dump variable information (similar to like PHP's var_dump())
\DBG::dump($array);

// output a message
// (optional) set $type to one of log (default), info or error
\DBG::log($message [, $type]);

Generate logs only if DBG_DEBUG has been enabled:

\DBG::debug($log);
\DBG::dump($data, DBG_DEBUG);
\DBG::stack(DBG_DEBUG);

Tracing

PHP code can be traced using \DBG::trace():

// output method/function name where \DBG::trace() is called
\DBG::trace();

Backtrace can be output using \DBG::stack():

// output backtrace (wrapper for PHP's debug_backtrace())
\DBG::stack();

SQL queries can be traced using the debug flag DBG_ADODB_TRACE:

// activate SQL query tracing
\DBG::activate(DBG_ADODB | DBG_ADODB_TRACE);

Env

In a Cloudrexx environment (cx env) debugging is enabled by default and can be adjusted through the environment variable CLX_DBG_FLAGS in the docker-compose.yml file.

Set CLX_DBG_FLAGS to a pipe delimited string of Debug Flags. I.e.:

CLX_DBG_FLAGS='DBG_PHP | DBG_LOG_FILE'
Important: The value of CLX_DBG_FLAGS must be enclosed by quotes.

To disable debugging just set CLX_DBG_FLAGS to "DBG_NONE".

Debug Flags

Flag Description
DBG_NONE Disable all output
DBG_PHP Output all PHP errors/warnings/notices
DBG_LOG Output debug messages/events (like \DBG::dump(), \DBG::msg(), etc)
DBG_PROFILE Logs time (by using \DBG::time()) of each log entry as well as the delta to the previous log entry.
DBG_DEBUG Logs stack trace (using \DBG::stack()) where DBG has been enabled and output of \DBG::debug() will be enabled.
DBG_DB Shortcut for: DBG_ADODB | DBG_DOCTRINE
DBG_DB_TRACE Shortcut for: DBG_ADODB_TRACE | DBG_DOCTRINE_TRACE
DBG_DB_CHANGE Shortcut for: DBG_ADODB_CHANGE | DBG_DOCTRINE_CHANGE
DBG_DB_ERROR Shortcut for: DBG_ADODB_ERROR | DBG_DOCTRINE_ERROR
DBG_DOCTRINE Output database (doctrine) queries
DBG_DOCTRINE_TRACE Output database (doctrine) queries with backtrace
DBG_DOCTRINE_CHANGE Output database (doctrine) changes (INSERT/UPDATE/DELETE)
DBG_DOCTRINE_ERROR Output only failed database (doctrine) queries
DBG_ADODB Output database (ADOdb) queries
DBG_ADODB_TRACE Output database (ADOdb) queries with backtrace
DBG_ADODB_CHANGE Output database (ADOdb) changes (INSERT/UPDATE/DELETE)
DBG_ADODB_ERROR Output only failed database (ADOdb) queries
DBG_LOG_FILE Output log to file (dbg.log). This will either log to /tmp/log/dbg.log or /update/dbg.log depending on which part of the system you're using
DBG_LOG_MEMORY Buffer output in memory which can then be fetched through \DBG::getMemoryLogs()
DBG_LOG_FIREPHP Deprecated Output log via FirePHP. FirePHP is an extension to Firebug
DBG_ERROR_FIREPHP Deprecated Shortcut for: DBG_PHP | DBG_ADODB_ERROR | DBG_LOG_FIREPHP
DBG_DB_FIREPHP Deprecated Shortcut for: DBG_PHP | DBG_ADODB | DBG_LOG_FIREPHP
DBG_ALL Deprecated Shortcut for: DBG_PHP | DBG_DB | DBG_DB_TRACE | DBG_DB_ERROR | DBG_DB_CHANGE | DBG_LOG_FILE | DBG_LOG_FIREPHP | DBG_LOG_MEMORY | DBG_LOG | DBG_PROFILE | DBG_DEBUG