README

通过特定环境和/或在应用中手动方式，以安全、干净的方式管理应用中的调试模式。该包会自动检测开发环境，并在任何环境中提供临时切换应用调试模式的安全方式。

功能

该包允许您的应用自动切换到调试模式

• 在本地主机环境中，通过IP地址
• 在您设置了 APP_DEBUG 环境变量的任何环境中半自动切换（适用于Docker开发栈）
• 在您设置了 app-debug-mode 甜点变量的任何环境中半自动禁用调试模式（适用于测试等情况）
• 手动启用/禁用（强制打开或关闭）调试模式。

注意：该包不直接提供任何调试工具 - 它只告诉应用是否切换到调试模式。

该包针对在应用的生命周期早期阶段调用进行了优化

要求

该包需要

• PHP版本 8.0, 8.1, 8.2 或 8.3

启用器需要

• 具有可写访问权限的临时目录

SignUrl插件需要

• Firebase JWT v5 或 v6

安装

composer require redbitcz/debug-mode-enabler

使用

在应用中的任何位置，您都可以通过简单的代码确定应用是否正在运行在调试模式下

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

当它检测到调试环境或手动切换时，返回 $debugMode = true

与Nette一起使用

在Bootstrap中使用包，如下所示

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

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

我知道，您喜欢使用DI容器来构建这样的服务。但是，Container Loader需要在DI容器准备好之前知道调试模式的状态，您不能使用DI来检测调试模式。

与Docker一起使用

如果您正在为开发栈构建自定义Docker镜像，请添加环境变量 APP_DEBUG=1。例如，在 Dockerfile 文件中

ENV APP_DEBUG 1

请避免将此镜像发布到生产环境！

与Docker Compose一起使用

在您的开发栈中设置环境变量 APP_DEBUG=1。例如，在 docker-compose.yml 文件中

environment:
    APP_DEBUG: 1

手动切换

警告 - 危险区域：以下功能允许您在包括 生产环境 在内的任何环境中强制启用调试模式。请谨慎使用！错误使用可能导致关键安全漏洞！在使用启用器的功能之前，请确保您的应用对XSS、CSRF和类似攻击具有抵抗力！

启用器提供了一种在用户的浏览器中任何地方强制启用或禁用调试模式的功能（由Cookie驱动）。

此示例为用户的浏览器打开调试模式

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

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

$enabler->activate(true);

选项

• $enabler->activate(true) - 强制将调试模式打开
• $enabler->activate(false) - 强制将调试模式关闭
• $enabler->deactivate() - 重置回环境自动检测

与Nette一起使用

调试模式启用器（与调试模式检测器不同）可以通过DI容器通过在 config.neon 中的配置来简单提供

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

在大多数情况下，此示例创建了第二个 Enabler 类的实例，因为第一个实例已经在 Bootstrap 中通过 Detector 实例内部创建了。

要重用已存在的实例，您可以将其注入到DI容器中

$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()]);

不要忘记在 config.neon 中的服务声明中让DI容器知道

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

插件

检测器支持自定义插件。您可以通过构建自定义插件来提供自己的角色来管理调试模式。插件必须实现Plugin接口，这意味着需要添加__invoke()方法。该方法在检测器请求检测模式时总是被调用。

插件返回检测结果

• null – 无结果 – 检测器将尝试请求另一个插件或检测方法来决定
• true – 强制打开当前请求的调试模式
• false – 强制关闭当前请求的调试模式

注意：当插件不符合规则时，应返回null值。布尔值总是停止处理检测规则。

不要这样做

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

而是当您的规则不匹配时返回null

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

您可以通过appendPlugin()或prepedndPlugin()方法将插件注册到检测器中。

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

$plugin = new MyPlugin();

$detector->appendPlugin($plugin);

$detector->isDebugMode(); // <---- this invoke all Plugins

SignUrl插件

SignUrl插件提供了一种安全的方式，在激活调试模式后共享链接。

$plugin = \Redbitcz\DebugMode\Plugin\SignedUrl::create('secretkey', 'HS256', 'https://myapp.cz');
$detector->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);

安全提示

不正确使用SignUrl插件可能会在您的应用程序中引发关键漏洞问题。请遵循以下说明

• 始终使用强大且秘密的密钥创建SignUrl，使用类似以下方法的密钥生成器：base64_encode(random_bytes(32))
• 始终使用指定的$audience参数创建SignUrl，以区分应用程序的不同版本（测试阶段 vs 生产）以防止在它们之间意外重用签名（了解更多关于观众的重要性）。

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。