Skip to content

Commit 15f3e20

Browse files
committed
Readme: Add docs for Plugin & SignUrl
1 parent 583f01a commit 15f3e20

File tree

1 file changed

+69
-0
lines changed

1 file changed

+69
-0
lines changed

README.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,5 +113,74 @@ services:
113113
imported: true
114114
```
115115

116+
## Plugins
117+
118+
Detector supports custom plugin. You can build custom plugin to provide your own roles to manage Debug Mode. Plugin must
119+
implements `Plugin` interface what means add `__invoke()` method. That method is called always is Detector aksed to
120+
detect mode.
121+
122+
Plugin retuns result of detection:
123+
124+
- `null` – no result – Detector will try to ask another plugin or detection method to decide
125+
- `true` – force turn-on debug mode for current request
126+
- `false` – force turn-off debug mode for current request
127+
128+
Note: You should return `null` value when Plugin doesn't explicitly matches rule. Boolean value is always stops
129+
processing detection rules.
130+
131+
Don't do this:
132+
133+
```php
134+
if (…) {
135+
return true;
136+
} else {
137+
return false;
138+
}
139+
```
140+
141+
instead return `null` when your rule is not matched:
142+
143+
```php
144+
if (…) {
145+
return true;
146+
} else {
147+
return null;
148+
}
149+
```
150+
151+
Your Plugin you can register to Detector with method `appendPlugin()` or `prepedndPlugin()`.
152+
153+
```php
154+
$detector = new \Redbitcz\DebugMode\Detector();
155+
156+
$plugin = new MyPlugin();
157+
158+
$detector->appendPlugin($plugin);
159+
160+
$detector->isDebugMode(); // <---- this invoke all Plugins
161+
```
162+
163+
## SignUrl plugin
164+
165+
`SignUrl` plugin provide secure way to share link with activated Debug Mode.
166+
167+
```php
168+
$plugin = new \Redbitcz\DebugMode\Plugin\SignedUrl('secretkey', 'HS256', 'https://myapp.cz');
169+
$detector->appendPlugin($plugin);
170+
171+
$signedUrl = $plugin->signUrl('https://myapp.cz/failingPage', '+1 hour');
172+
173+
echo 'Private link with activated Debug mode: ' . htmlspecialchars($signedUrl, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE);
174+
```
175+
176+
### Security notes
177+
178+
Wrong usage of the `SignUrl` plugin can open critical vulnerability issue at your App. Follow this instructions:
179+
180+
- Always create `SignUrl` with strong and Secret key, use key generator like: `base64_encode(random_bytes(32))`
181+
- Always create `SignUrl` with specified `$audience` parameter which distinguishes versions of app (stage vs production)
182+
to prevent unwanted re-using signatures between them
183+
([read more about importance of audience](https://stackoverflow.com/a/41237822/1641372)).
184+
116185
## License
117186
The MIT License (MIT). Please see [License File](LICENSE) for more information.

0 commit comments

Comments
 (0)