@@ -113,5 +113,74 @@ services:
113
113
imported: true
114
114
` ` `
115
115
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 \R edbitcz\D ebugMode\D etector();
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 \R edbitcz\D ebugMode\P lugin\S ignedUrl('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
+
116
185
# # License
117
186
The MIT License (MIT). Please see [License File](LICENSE) for more information.
0 commit comments