Skip to content

Commit bb4ebb4

Browse files
alexmerlinalexmerlin
committed
- Code enhancements
- Documentation - Tests Signed-off-by: alexmerlin <alex.merlin.1985@gmail.com>
1 parent fef6ce9 commit bb4ebb4

40 files changed

+2335
-182
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ clover.xml
22
coveralls-upload.json
33
.phpunit.result.cache
44
.phpcs-cache
5+
config/log.global.php
6+
config/error-handling.global.php
57

68
# Created by .ignore support plugin (hsz.mobi)
79
### JetBrains template

‎composer.json‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,14 @@
66
"homepage": "https://github.com/dotkernel/dot-errorhandler",
77
"authors": [
88
{
9-
"name": "DotKernel Team",
9+
"name": "Dotkernel Team",
1010
"email": "team@dotkernel.com"
1111
}
1212
],
1313
"keywords": [
1414
"error",
1515
"errorhandler",
16-
"factories",
17-
"container",
18-
"laminas",
19-
"mezzio",
20-
"service-manager"
16+
"error_log"
2117
],
2218
"config": {
2319
"sort-packages": true,
@@ -27,7 +23,7 @@
2723
},
2824
"require": {
2925
"php": "~8.2.0 || ~8.3.0 || ~8.4.0",
30-
"dotkernel/dot-log": "^4.1.0",
26+
"dotkernel/dot-log": "^5.0",
3127
"laminas/laminas-diactoros": "^3.3",
3228
"laminas/laminas-stdlib": "^3.20",
3329
"laminas/laminas-stratigility": "^3.11",

‎config/error-handling.global.php.dist‎

Lines changed: 43 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,12 @@
33
declare(strict_types=1);
44

55
use Dot\ErrorHandler\ErrorHandlerInterface;
6+
use Dot\ErrorHandler\Extra\ExtraProvider;
67
use Dot\ErrorHandler\Extra\Processor\CookieProcessor;
78
use Dot\ErrorHandler\Extra\Processor\HeaderProcessor;
9+
use Dot\ErrorHandler\Extra\Processor\ProcessorInterface;
810
use Dot\ErrorHandler\Extra\Processor\RequestProcessor;
11+
use Dot\ErrorHandler\Extra\Processor\ServerProcessor;
912
use Dot\ErrorHandler\Extra\Processor\SessionProcessor;
1013
use Dot\ErrorHandler\Extra\Processor\TraceProcessor;
1114
use Dot\ErrorHandler\Extra\Provider\CookieProvider;
@@ -14,6 +17,7 @@ use Dot\ErrorHandler\Extra\Provider\RequestProvider;
1417
use Dot\ErrorHandler\Extra\Provider\ServerProvider;
1518
use Dot\ErrorHandler\Extra\Provider\SessionProvider;
1619
use Dot\ErrorHandler\Extra\Provider\TraceProvider;
20+
use Dot\ErrorHandler\Extra\ReplacementStrategy;
1721
use Dot\ErrorHandler\LogErrorHandler;
1822

1923
return [
@@ -23,32 +27,57 @@ return [
2327
],
2428
],
2529
'dot-errorhandler' => [
26-
'loggerEnabled' => true,
27-
'logger' => 'dot-log.default_logger',
28-
'loggerExtra' => [
30+
'loggerEnabled' => true,
31+
'logger' => 'dot-log.default_logger',
32+
ExtraProvider::CONFIG_KEY => [
2933
CookieProvider::class => [
30-
'enabled' => true,
31-
'processor' => CookieProcessor::class,
34+
'enabled' => false,
35+
'processor' => [
36+
'class' => CookieProcessor::class,
37+
'replacementStrategy' => ReplacementStrategy::Full,
38+
'sensitiveParameters' => [
39+
ProcessorInterface::ALL,
40+
],
41+
],
3242
],
3343
HeaderProvider::class => [
34-
'enabled' => true,
35-
'processor' => HeaderProcessor::class,
44+
'enabled' => false,
45+
'processor' => [
46+
'class' => HeaderProcessor::class,
47+
'replacementStrategy' => ReplacementStrategy::Full,
48+
],
3649
],
3750
RequestProvider::class => [
38-
'enabled' => true,
39-
'processor' => RequestProcessor::class,
51+
'enabled' => false,
52+
'processor' => [
53+
'class' => RequestProcessor::class,
54+
'replacementStrategy' => ReplacementStrategy::Full,
55+
'sensitiveParameters' => [
56+
'password',
57+
],
58+
],
4059
],
4160
ServerProvider::class => [
42-
'enabled' => true,
43-
'processor' => null,
61+
'enabled' => false,
62+
'processor' => [
63+
'class' => ServerProcessor::class,
64+
'replacementStrategy' => ReplacementStrategy::Full,
65+
'sensitiveParameters' => [
66+
ProcessorInterface::ALL,
67+
],
68+
],
4469
],
4570
SessionProvider::class => [
46-
'enabled' => true,
47-
'processor' => SessionProcessor::class,
71+
'enabled' => false,
72+
'processor' => [
73+
'class' => SessionProcessor::class,
74+
],
4875
],
4976
TraceProvider::class => [
5077
'enabled' => true,
51-
'processor' => TraceProcessor::class,
78+
'processor' => [
79+
'class' => TraceProcessor::class,
80+
],
5281
],
5382
],
5483
],

‎config/log.global.php.dist‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,32 @@
11
<?php
22

3+
declare(strict_types=1);
4+
5+
use Dot\Log\Formatter\Json;
6+
use Dot\Log\Logger;
7+
38
return [
49
'dot_log' => [
510
'loggers' => [
611
'default_logger' => [
712
'writers' => [
813
'FileWriter' => [
9-
'name' => 'stream',
10-
'priority' => \Dot\Log\Logger::ALERT,
14+
'name' => 'stream',
15+
'level' => Logger::ALERT,
1116
'options' => [
1217
'stream' => __DIR__ . '/../../log/error-log-{Y}-{m}-{d}.log',
1318
// explicitly log all messages
14-
'filters' => [
19+
'filters' => [
1520
'allMessages' => [
16-
'name' => 'priority',
21+
'name' => 'level',
1722
'options' => [
1823
'operator' => '>=',
19-
'priority' => \Dot\Log\Logger::EMERG,
24+
'level' => Logger::EMERG,
2025
],
2126
],
2227
],
2328
'formatter' => [
24-
'name' => \Dot\Log\Formatter\Json::class,
29+
'name' => Json::class,
2530
],
2631
],
2732
],

‎docs/book/v4/extra/cookie.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Log cookie data
2+
3+
Looking at `dot-errorhandler`'s config file, the array found at `CookieProvider::class` allows you to configure the behaviour of this provider:
4+
5+
- **enabled**: enabled/disable this provider
6+
- **processor**: an array configuring the data processor to be used by the **CookieProvider**:
7+
- **class**: data processor class implementing `Dot\ErrorHandler\Extra\Processor\ProcessorInterface`
8+
- **replacementStrategy**: whether to replace specific cookie values completely or partially
9+
- **sensitiveParameters**: an array of cookies names that may contain sensitive information so their value should be masked partially/completely
10+
11+
## Configure provider
12+
13+
By default, **CookieProvider** is disabled.
14+
It can be enabled only by setting **enabled** to **true**.
15+
16+
If **enabled** is set to **true**, your log file will contain an additional field under the `extra` key, called `cookie`.
17+
If **enabled** is set to **false**, no additional field is added under the `extra` key.
18+
19+
## Configure processor
20+
21+
From here, we assume that **enabled** is set to **true**.
22+
23+
If **processor** is missing/empty, the processor is ignored the provider will log the raw data available.
24+
If **processor** is specified, but **class** is missing/invalid, the processor is ignored and the provider will log the raw data available.
25+
26+
From here, we assume that **processor**.**class** is valid.
27+
28+
### Replacement strategy
29+
30+
This value should be an instance of `Dot\ErrorHandler\Extra\ReplacementStrategy`.
31+
32+
If **replacementStrategy** is missing/invalid, the default **replacementStrategy** is used, which is `ReplacementStrategy::Full`.
33+
Else, the value used should be one of:
34+
35+
- `ReplacementStrategy::Partial` for half-string replacements (e.g.: "abcdef" becomes "abc***")
36+
- `ReplacementStrategy::Full` for full-string replacements (e.g.: "abcdef" becomes "******")
37+
38+
### Sensitive parameters
39+
40+
If **sensitiveParameters** is missing/empty, the processor is ignored the provider will log the raw data available.
41+
This is because without a set of **sensitiveParameters**, the processor is unable to determine which key needs to be processed or left untouched.
42+
When specifying the array of **sensitiveParameters**, there are two possibilities:
43+
44+
- use the constant `ProcessorInterface::ALL`, meaning alter all cookie values using the strategy specified by the **replacementStrategy**
45+
46+
```php
47+
'sensitiveParameters' => [
48+
Dot\ErrorHandler\Extra\Processor\ProcessorInterface::ALL,
49+
],
50+
```
51+
52+
- use exact strings to list the cookies for which the values should be altered using the strategy specified by the **replacementStrategy**
53+
54+
```php
55+
'sensitiveParameters' => [
56+
'rememberMe',
57+
],
58+
```
59+
60+
> **CookieProcessor** uses EXACT cookie name lookups.
61+
> In order to alter the value of a cookie, you need to specify the exact cookie name.
62+
63+
> The config `sensitiveParameters` is case-insensitive.
64+
65+
## Why should I use a processor
66+
67+
Consider the following request cookies:
68+
69+
```text
70+
[
71+
"sessionId" => "feb21b39f9c54e3a49af1f862acc8300",
72+
"language" => "en",
73+
]
74+
```
75+
76+
Without a **CookieProcessor**, the plain text session cookie identifier would end up saved in the log file:
77+
78+
```text
79+
..."extra":{"file":"/path/to/some/class.php","line":314,"cookie":{"sessionId":"feb21b39f9c54e3a49af1f862acc8300","language":"en"},...
80+
```
81+
82+
But, with a properly configured **CookieProcessor**:
83+
84+
```php
85+
'processor' => [
86+
'class' => CookieProcessor::class,
87+
'replacementStrategy' => ReplacementStrategy::Full,
88+
'sensitiveParameters' => [
89+
'sessionId',
90+
],
91+
],
92+
```
93+
94+
the logged cookie data becomes:
95+
96+
```text
97+
..."extra":{"file":"/path/to/some/class.php","line":314,"cookie":{"sessionId":"********************************","language":"en"},...
98+
```
99+
100+
## Custom processor
101+
102+
If the existing processor does not offer enough features, you can create a custom processor.
103+
The custom processor must implement `Dot\ErrorHandler\Extra\Processor\ProcessorInterface` or extend `Dot\ErrorHandler\Extra\Processor\AbstractProcessor`, which already implements `Dot\ErrorHandler\Extra\Processor\ProcessorInterface`.
104+
Once the custom processor is ready, you need to configure **CookieProvider** to use it.
105+
For this, open `dot-errorhandler`'s config file and - under **CookieProvider::class** - set **processor**.**class** to the class string of your custom processor:
106+
107+
```php
108+
CookieProvider::class => [
109+
'enabled' => false,
110+
'processor' => [
111+
'class' => CustomCookieProcessor::class,
112+
'replacementStrategy' => ReplacementStrategy::Full,
113+
'sensitiveParameters' => [
114+
ProcessorInterface::ALL,
115+
],
116+
],
117+
],
118+
```
119+
120+
Using this, cookie data will be processed by `CustomCookieProcessor` and logged as provided by this new processor.

0 commit comments

Comments
 (0)