README

This library is basically just a wrapper around Kint and PHP-Console combining them both into a powerful debugging tool.

Installation

Install this package using composer:

composer require neunerlei/dbg

Environment detection

It is not recommended to use this library in production. However, if you have considered the risks and know what to do, this library tries to help you to run it in production as securely as possible.

To do so there are different mechanics you may use to determine when you want to enable the debugger or not. First of all, to enable the environment detection set the "environmentDetection" to true

You can completely disable the functionality of this library by setting the "enabled" config option (see the " Configuration" section for further information) to false.
You may define a environment variable to determine if the debugging is enabled or not. By default, the script will look for a env variable called "APP_ENV" which requires a value of "dev" to enable the debugging. You may configure the name of the variable, as well as the expected value. (PROJECT_ENV also works for legacy compatibility)
By default, CLI commands are considered "save" and will allow execution of the debug methods. (See "cliIsDev" option)
It is possible to only enable the debugging when a specific referrer is transmitted by your browser. To enable this take a look at the "debugReferrer" option. (See the referrer control extension for chrome.)

IP's I explicitly left out ip's for determining if the debugger should run or not, as I figure that method as quite error prone (especially when you work with a dynamic IP address). If you want to use this, you have to code that feature for yourself.

Configuration

It is possible to define multiple options for the debugger. The configuration is performed using the Neunerlei\Dbg\Dbg::config() function. Possible config options are:

enabled: (bool) default: TRUE | Master switch to enable/disable the debugging functionality. If you set this to false, none of the functions will do or output anything.
environmentDetection: (bool) default: TRUE | Disables the environment detection mechanism if set to false.
- envVarKey: (string) default: APP_ENV | Determines the name of the environment variable to look for when enabling the debug feature.
- envVarValue: (string) default: dev | Used in combination with "envVarKey" and determines which value to expect from the configured environment variable to enable the debugger.
- cliIsDev: (bool) default: TRUE | Determines if the debugger should always output stuff in a CLI environment or not.
- debugReferrer: (string|NULL) default: NULL | If set this will be expected as the referrer to enable the debugger capabilities.
preHooks: (callable|array) | One or multiple callbacks to run in front of each debugger function ( dbg,dbge,trace,tracee,...). Useful for extending the functionality. Each callback will receive $hookType, $callingFunction and $givenArguments as arguments.
postHooks: (callable|array) | Same as "preHooks" but run after the debug output.
consolePassword: (string|NULL) default: NULL | If set the phpConsole will require this value as password before printing the console output to the browser.
logDir: (string|NULL) default: NULL | If set, the logFile() function will dump the logfile to the given director. Make sure it exists and is writable by the webserver!
editorFileFormat (string|NULL) default: null | Can be used to create clickable links to be opened in your IDE of choice. Can be either a formatting pattern like "phpstorm://open?file=%f&line=%l", or one of the predefined values: sublime, textmate, emacs, macvim, phpstorm, phpstorm-remotecall, idea, vscode, vscode-insiders, vscode-remote, vscode-insiders-remote, vscodium, atom, nova, netbeans or xdebug

Functions

dbg()

Takes any number of arguments and prints them to the screen, either formatted for html or for cli, depending on the current context.

dbg("foo");

Will render something like this in a browser:

and something like this in a CLI app:

dbge()

Works exactly the same way as dbg() but kills the script exit(0) after dumping the arguments to the screen.

trace()

Prints the current debug backtrace to the screen, either formatted for html or for cli, depending on the current context.

trace();

Will render something like this in a browser:

tracee()

Again, works exactly the same as trace, but kills the script after printing it.

logConsole()

This function is mend specifically for in-browser development only. It relies on PHP-Console and the chrome php console extension to render the given values to the javascript console without using html script tags or similar. It works also when performing redirects or throwing exceptions, as the data will be transferred over a http header.

logConsole("foo");

This will output something like:

logFile()

Receives any number of arguments and will dump them into a plain log file. The logfile will be located (in order of priority):

$_ENV["_DBG_LOG_DIR"]/dbg_debug_logfile.log if this environment variable contains a writable directory path
Dbg::config("logDir") /dbg_debug_logfile.log if the environment variable is empty and the directory is writable
/var/www/logs/dbg_debug_logfile.log if the logs directory is writable
/$SYS_TEMP_DIR/labor_debug_logfile.log

logFile("foo");

logStream()

Receives any number of arguments and dumps them into a configured stream. By default the 'php://stdout' is used as output stream, which is the best solution if you work with docker. The output will always be a single line with all line-breaks removed to keep cloud logging apis nice and happy

You can change the stream path to match your needs:

$_ENV['_DBG_LOG_STREAM'] to set the path via env variable
Dbg::config("logStream") to set the path via the configuration api

Dbg::isEnabled()

This function returns true if the debug functions are currently operational (including the checks for the environment detection) and will return TRUE if so, or FALSE if not.

Dbg::config(string $key = "", $value = NULL)

This function is used to configure the debugger with the options seen in the "Configuration" section. If this function is called without arguments it will return the current list of config option. If it is called with a key but without value it will return the current value for the given key.

If you supply both key and value you will set the given config option.

 // Disable environment detection
 Neunerlei\Dbg\Dbg::config("environmentDetection", FALSE);

Postcardware

You're free to use this package, but if it makes it to your production environment I highly appreciate you sending me a postcard from your hometown, mentioning which of our package(s) you are using.

You can find my address here.

Thank you :D

neunerlei / dbg

Maintainers

Details