PHPackages neunerlei/dbg - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Debugging & Profiling](/categories/debugging) 4. / 5. neunerlei/dbg ActiveLibrary[Debugging & Profiling](/categories/debugging) neunerlei/dbg ============= PHP debugging suitcase for your daily work 3.3.0(2mo ago)06.1k↓31.3%1[1 PRs](https://github.com/Neunerlei/dbg/pulls)8Apache-2.0PHPPHP >=8.2CI passing Since May 16Pushed 2mo agoCompare [ Source](https://github.com/Neunerlei/dbg)[ Packagist](https://packagist.org/packages/neunerlei/dbg)[ RSS](/packages/neunerlei-dbg/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (8)Versions (35)Used By (8) DBG - Debug Helpers =================== [](#dbg---debug-helpers) This library is basically just a wrapper around [Kint](https://github.com/kint-php/kint)and [PHP-Console](https://github.com/barbushin/php-console) combining them both into a powerful debugging tool. Installation ------------ [](#installation) Install this package using composer: ``` composer require neunerlei/dbg ``` Environment detection --------------------- [](#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 1. You can completely disable the functionality of this library by setting the "enabled" config option (see the " Configuration" section for further information) to false. 2. You may define a environment variable to determine if the debugging is enabled or not. By default, the script will look for multiple different values to check if it has to enable the debugging. You may configure the name of the variable, as well as the expected value. (See below for the list of default variables) 3. By default, CLI commands are considered "save" and will allow execution of the debug methods. (See "cliIsDev" option) 4. 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](https://chrome.google.com/webstore/detail/referer-control/hnkcfpcejkafcihlgbojoidoihckciin?hl=en)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. ### Checked environment variables [](#checked-environment-variables) To determine the environment we check a set of environment variables. If you configured one yourself with `Dbg::config()->setEnvVarKey()` and `Dbg::config()->setEnvVarValue()`, the script will check for the variable you configured AND the following list of built-in variables: Variable nameDescription`APP_ENV`The most common variable to determine the current environment. If set to "dev", "local" or "development" the debugger will be enabled.`ENVIRONMENT`Can be set to "dev" or "development" to enable the debugger.`PHP_PROD_DEBUG`Can be set to "1" or "true" to enable the debugger, to work out of the box with my [Docker images](https://github.com/Neunerlei/docker-images/blob/main/docs/php-nginx.md)`PROJECT_ENV`**DEPRECATED** Legacy support for older applications. Can be set to "dev" or "development" to enable the debugger.> If ANY of those variables is set to the expected value, the debugger will be enabled. So you can choose the one that fits best for your environment. > **Pro tip** You can disable the built-in environment variable checks by setting Configuration ------------- [](#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! - logStream: (string) default: php://stdout | If set, the logStream() function will dump the given arguments to the given stream. ### Config files [](#config-files) The library supports the usage of dedicated config files. The files are plain PHP files with the name: `dbg.config.php`that are designed to execute either the `\Neunerlei\Dbg\Dbg::hooks()->addListener()` (for hooks) or the `\Neunerlei\Dbg\Dbg::config()` function (for configuration). Those files can easily be added to your .gitignore file, so you can configure your local development environment without affecting the production environment. The files are loaded from the directories of the following server variables: - `$_ENV['DOCUMENT_ROOT']` (Including all its parent directories) - `$_ENV['DDEV_COMPOSER_ROOT']` - `$_ENV['PWD']` - `$_ENV['DBG_CONFIG_DIR']` (Loaded from an environment variable) Pro tip: The `dbg.config.php` can also be stored in a subdirectory (called: `.dbg`) of the above directories, to allow easier `.gitignore` handling (If stored in the directory, the file can also be called `.dbg/config.php`). Functions --------- [](#functions) ### dbg() [](#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: [![Preview](ReadmeImages/dbg.png)](ReadmeImages/dbg.png) and something like this in a CLI app: [![Preview](ReadmeImages/dbg-cli.png)](ReadmeImages/dbg-cli.png) ### dbge() [](#dbge) Works exactly the same way as dbg() but kills the script exit(0) after dumping the arguments to the screen. ### trace() [](#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: [![Preview](ReadmeImages/trace.png)](ReadmeImages/trace.png) ### tracee() [](#tracee) Again, works exactly the same as trace, but kills the script after printing it. ### logConsole() [](#logconsole) This function is mend specifically for in-browser development only. It relies on [PHP-Console](https://github.com/barbushin/php-console) and the [chrome php console extension](https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef)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: [![Preview](ReadmeImages/php-console.png)](ReadmeImages/php-console.png) ### logFile() [](#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 - The following locations (in order) if the directory exist and is writable: - /var/www/html/var/log/dbg\_debug\_logfile.log - /var/www/html/storage/logs/dbg\_debug\_logfile.log - /var/www/logs/dbg\_debug\_logfile.log - If nothing else matches: `/$SYS_TEMP_DIR/labor_debug_logfile.log` ``` logFile("foo"); ``` ### logStream() [](#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() [](#dbgisenabled) 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() [](#dbgconfig) This function is used to configure the debugger with the options seen in the "Configuration" section. The function returns an instance of a configuration object, which can be used to set or get the current configuration. ``` // Disable environment detection Neunerlei\Dbg\Dbg::config()->setEnvironmentDetection(FALSE); ``` Postcardware ------------ [](#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](https://www.neunerlei.eu/). Thank you :D ### Health Score 56 — FairBetter than 98% of packages Maintenance87 Actively maintained with recent releases Popularity24 Limited adoption so far Community16 Small or concentrated contributor base Maturity83 Battle-tested with a long release history Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~78 days Recently: every ~91 days Total 33 Last Release 62d ago Major Versions 1.12.0 → 2.0.12022-12-14 2.2.0 → 3.0.02025-02-19 PHP version history (3 changes)2.0.1PHP >=7.4 2.2.0PHP >=7.4 <8.4 3.0.0PHP >=8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/0eb1c26fb5a535cd7a656faffbae7929009558b2bfa6156b2be7b636d689e13a?d=identicon)[labor-digital](/maintainers/labor-digital) ![](https://www.gravatar.com/avatar/c0356afb258572c8908df3132ea59545b7642a6b77fd90bc54215e506c42bfb7?d=identicon)[neunerlei](/maintainers/neunerlei) --- Top Contributors [![Neunerlei](https://avatars.githubusercontent.com/u/22350956?v=4)](https://github.com/Neunerlei "Neunerlei (35 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/neunerlei-dbg/health.svg) ``` [![Health](https://phpackages.com/badges/neunerlei-dbg/health.svg)](https://phpackages.com/packages/neunerlei-dbg) ``` ### Alternatives [symfony/stopwatch Provides a way to profile code 2.8k387.2M918](/packages/symfony-stopwatch)[fruitcake/laravel-debugbar PHP Debugbar integration for Laravel 19.1k662.9k29](/packages/fruitcake-laravel-debugbar)[soloterm/dumps A Laravel command to intercept dumps from your Laravel application. 125285.7k3](/packages/soloterm-dumps)[php-console/laravel-service-provider Laravel service provider to handle PHP errors, dump variables, execute PHP code remotely in Google Chrome 7361.2k1](/packages/php-console-laravel-service-provider)[steevanb/php-backtrace Nice debug\_backtrace() dump, with call and code preview 22142.6k5](/packages/steevanb-php-backtrace)[milo/vendor-versions Bar with versions list of vendor libraries for Tracy 19155.1k5](/packages/milo-vendor-versions) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)