PHPackages                             redbitcz/debug-mode-enabler - 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. redbitcz/debug-mode-enabler

ActiveLibrary[Debugging & Profiling](/categories/debugging)

redbitcz/debug-mode-enabler
===========================

Debug mode enabler - safe and clean way to manage Debug Mode in your App

v5.0.2(7mo ago)33.9k2MITPHPPHP ~8.0

Since Oct 21Pushed 7mo ago2 watchersCompare

[ Source](https://github.com/redbitcz/php-debug-mode-enabler)[ Packagist](https://packagist.org/packages/redbitcz/debug-mode-enabler)[ Docs](https://github.com/redbitcz/php-debug-mode-enabler)[ RSS](/packages/redbitcz-debug-mode-enabler/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (14)Used By (0)

PHP Debug Mode Enabler
======================

[](#php-debug-mode-enabler)

Safe and clean way to manage Debug Mode in your app by specific environment and/or manually in App. Package automatically detects development environments and provide secure way to temporary switch Debug Mode of your App at any environment.

Features
--------

[](#features)

Package allows your app to switch to Debug Mode:

- automatically on localhost's environment by IP,
- semi-automatically on any environment where you set `APP_DEBUG` environment variable (useful for Docker dev-stack),
- semi-automatically **disable** Debug mode on any environment where you set `app-debug-mode` cookie variable (useful for tests and similar cases),
- manually enable/disable (force turn-on or turn-off) Debug Mode.

**NOTE:** Package does NOT provide any Debug tools directly – it only tells the app whether to switch to debug mode.

Package is optimized for invoking in very early lifecycle phase of your App

Requirements
------------

[](#requirements)

Package requires:

- PHP version 8.0, 8.1, 8.2, 8.3 or 8.4

Enabler requires:

- Temporary directory with writable access

SignUrl plugin requires:

- [Firebase JWT](https://github.com/firebase/php-jwt) v5 or v6

Installation
------------

[](#installation)

```
composer require redbitcz/debug-mode-enabler
```

Using
-----

[](#using)

Anywhere in your app you can determine if app is running in Debug mode by simple code:

```
$debugMode = \Redbitcz\DebugMode\Detector::detect(); //bool
```

It returns `$debugMode` = `true` when it detects Debug environment or manually switched.

### Using with Nette

[](#using-with-nette)

In Boostrap use package like in this example:

```
$debugModeDetector = new \Redbitcz\DebugMode\Detector();

$configurator = new Configurator();
$configurator->setDebugMode($debugModeDetector->isDebugMode());
```

> I know, you love DI Container to build services like this. But Container Loader need to know Debug Mode state before is DI Container ready, you cannot use DI for Debug Mode detecting.

Using with Docker
-----------------

[](#using-with-docker)

If you are building custom Docker image for your devstack, add the environment variable `APP_DEBUG=1`. For example in `Dockerfile` file:

```
ENV APP_DEBUG 1

```

> Avoid to publish these image to production!

Using with Docker compose
-------------------------

[](#using-with-docker-compose)

In your devstack set environment variable `APP_DEBUG=1`. For example in `docker-compose.yml` file:

```
environment:
    APP_DEBUG: 1
```

Manually switch
---------------

[](#manually-switch)

**WARNING – DANGER ZONE:** Following feature allows you to force Debug Mode on any environment, including *production*. Please use it with great caution only! Wrong use might cause critical security issue! Before using Enabler's feature, make sure your app is resistant to XSS, CSRF and similar attacks!

Enabler provide feature to force enable or disable Debug Mode anywhere for user's browser (drived by Cookie).

This example turn on Debug Mode for user's browser:

```
$enabler = new \Redbitcz\DebugMode\Enabler($tempDir);

$detector = new \Redbitcz\DebugMode\Detector(\Redbitcz\DebugMode\Detector::MODE_FULL, $enabler);

$enabler->activate(true);
```

### Options

[](#options)

- `$enabler->activate(true)` - force to Debug Mode turn on,
- `$enabler->activate(false)` - force to Debug Mode turn off,
- `$enabler->deactivate()` - reset back to automatically detection by environment.

### Using with Nette

[](#using-with-nette-1)

Debug Mode Enabler (unlike Debug Mode Detector) can be simply served through DI Container with configuration in `config.neon`:

```
services:
    - Redbitcz\DebugMode\Enabler(%tempDir%)
```

At most cases this example creates second instance of `Enabler` class because first one is already created internally with `Detector` instance in `Bootstrap`.

To re-use already existing instance you can inject it to DI Container:

```
$tempDir = __DIR__ . '/../temp';
$enabler = new \Redbitcz\DebugMode\Enabler($tempDir);
$debugModeDetector = new \Redbitcz\DebugMode\Detector(\Redbitcz\DebugMode\Detector::MODE_FULL, $enabler);

$configurator = new Configurator();
$configurator->setDebugMode($debugModeDetector->isDebugMode());
$configurator->addServices(['debugModeEnabler' => $debugModeDetector->getEnabler()]);
```

Don't forget letting know DI Container with service declaration in `config.neon`:

```
services:
    debugModeEnabler:
        type: Redbitcz\DebugMode\Enabler
        imported: true
```

Plugins
-------

[](#plugins)

Detector supports custom plugin. You can build custom plugin to provide your own roles to manage Debug Mode. Plugin must implements `Plugin` interface what means add `__invoke()` method. That method is called always is Detector aksed to detect mode.

Plugin retuns result of detection:

- `null` – no result – Detector will try to ask another plugin or detection method to decide
- `true` – force turn-on debug mode for current request
- `false` – force turn-off debug mode for current request

Note: You should return `null` value when Plugin doesn't explicitly matches rule. Boolean value is always stops processing detection rules.

Don't do this:

```
if (…) {
    return true;
} else {
    return false;
}
```

instead return `null` when your rule is not matched:

```
if (…) {
    return true;
} else {
    return null;
}
```

Your Plugin you can register to Detector with method `appendPlugin()` or `prepedndPlugin()`.

```
$detector = new \Redbitcz\DebugMode\Detector();

$plugin = new MyPlugin();

$detector->appendPlugin($plugin);

$detector->isDebugMode(); // appendPlugin($plugin);

$signedUrl = $plugin->signUrl('https://myapp.cz/failingPage', '+1 hour');

echo 'Private link with activated Debug mode: ' . htmlspecialchars($signedUrl, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE);
```

### Security notes

[](#security-notes)

Wrong usage of the `SignUrl` plugin can open critical vulnerability issue at your App. Follow this instructions:

- Always create `SignUrl` with strong and Secret key, use key generator like: `base64_encode(random_bytes(32))`
- Always create `SignUrl` with specified `$audience` parameter which distinguishes versions of app (stage vs production) to prevent unwanted re-using signatures between them ([read more about importance of audience](https://stackoverflow.com/a/41237822/1641372)).

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance64

Regular maintenance activity

Popularity27

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 97.1% 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 ~151 days

Recently: every ~243 days

Total

13

Last Release

218d ago

Major Versions

v2.0.2 → v3.0.02021-09-11

v3.2.2 → v4.0.02023-02-09

v4.0.1 → v5.0.02024-01-17

PHP version history (5 changes)2.0.0PHP >=7.3.4

v3.0.0PHP >=7.4

v4.0.0PHP ~7.4.0 || ~8.0.0 || ~8.1.0 || ~8.2.0

v5.0.0PHP ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0

v5.0.1PHP ~8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/343719dd69717f77bd727d9c3c110aabab0eb24f881dbf05941c1ba0d0deff6c?d=identicon)[jakubboucek](/maintainers/jakubboucek)

![](https://www.gravatar.com/avatar/a1e2f51c5351a4d01433e85cd819c0794708f03a595c7a09ddb5ba7f14c3d3c7?d=identicon)[redbitcz](/maintainers/redbitcz)

---

Top Contributors

[![jakubboucek](https://avatars.githubusercontent.com/u/1657322?v=4)](https://github.com/jakubboucek "jakubboucek (134 commits)")[![psenakv](https://avatars.githubusercontent.com/u/32768869?v=4)](https://github.com/psenakv "psenakv (2 commits)")[![vojtech-pejsa-redbit](https://avatars.githubusercontent.com/u/110399091?v=4)](https://github.com/vojtech-pejsa-redbit "vojtech-pejsa-redbit (2 commits)")

---

Tags

debug

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/redbitcz-debug-mode-enabler/health.svg)

```
[![Health](https://phpackages.com/badges/redbitcz-debug-mode-enabler/health.svg)](https://phpackages.com/packages/redbitcz-debug-mode-enabler)
```

###  Alternatives

[symfony/var-dumper

Provides mechanisms for walking through any arbitrary PHP variable

7.4k855.5M8.0k](/packages/symfony-var-dumper)[barryvdh/laravel-debugbar

PHP Debugbar integration for Laravel

19.2k124.3M624](/packages/barryvdh-laravel-debugbar)[php-debugbar/php-debugbar

Debug bar in the browser for php application

4.4k21.3M40](/packages/php-debugbar-php-debugbar)[fruitcake/laravel-debugbar

PHP Debugbar integration for Laravel

19.1k662.9k29](/packages/fruitcake-laravel-debugbar)[kint-php/kint

Kint - Advanced PHP dumper

2.8k19.3M283](/packages/kint-php-kint)[tracy/tracy

😎 Tracy: the addictive tool to ease debugging PHP code for cool developers. Friendly design, logging, profiler, advanced features like debugging AJAX calls or CLI support. You will love it.

1.8k24.4M1.3k](/packages/tracy-tracy)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)