Skip to content

Commit 6ec8b9a

Browse files
sweikenbsweikenb
committed
Initial commit
0 parents  commit 6ec8b9a

31 files changed

+1556
-0
lines changed

‎.github/workflows/phpunit.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: PHP Composer
2+
3+
on:
4+
push:
5+
branches: [ "**" ]
6+
pull_request:
7+
branches: [ "main" ]
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
22+
strategy:
23+
fail-fast: false
24+
matrix:
25+
php-version:
26+
- "8.2"
27+
- "8.3"
28+
dependency-versions:
29+
- "lowest"
30+
- "highest"
31+
32+
steps:
33+
- name: Checkout source
34+
uses: actions/checkout@v4
35+
36+
- name: Setup PHP
37+
uses: shivammathur/setup-php@v2
38+
with:
39+
php-version: ${{ matrix.php-version }}
40+
coverage: xdebug
41+
42+
- name: Install composer dependencies
43+
uses: ramsey/composer-install@v2
44+
with:
45+
dependency-versions: ${{ matrix.dependency-versions }}
46+
47+
- name: Run test-suite
48+
run: composer run-script phpunit
49+
50+
- name: Setup Pages
51+
if: github.ref == 'refs/heads/main'
52+
id: pages
53+
uses: actions/configure-pages@v3
54+
55+
- name: Upload artifact
56+
if: github.ref == 'refs/heads/main'
57+
uses: actions/upload-pages-artifact@v2
58+
with:
59+
path: ./coverage/html
60+
61+
deploy:
62+
runs-on: ubuntu-latest
63+
64+
if: github.ref == 'refs/heads/main'
65+
66+
environment:
67+
name: github-pages
68+
url: ${{ steps.deployment.outputs.page_url }}
69+
70+
needs: build
71+
72+
steps:
73+
- name: Deploy to GitHub Pages
74+
id: deployment
75+
uses: actions/deploy-pages@v2

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/*.cache
2+
/coverage
3+
/composer.lock

‎.php-cs-fixer.dist.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?php
2+
3+
$finder = (new PhpCsFixer\Finder())
4+
->in(__DIR__);
5+
6+
return (new PhpCsFixer\Config())
7+
->setRules([
8+
'@Symfony' => true,
9+
])
10+
->setFinder($finder);

‎LICENSE‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright 2024 Simon Schröer
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# sweikenb/dirty
2+
3+
Library for checking if an object or array has changes (is dirty) since the last check.
4+
5+
License: MIT
6+
7+
## Installation
8+
9+
```bash
10+
composer require sweikenb/dirty
11+
```
12+
13+
If you plan to use this library in a **Symfony** project, consider checking out the corresponding
14+
[DirtyBundle](https://github.com/sweikenb/dirty-bundle) instead.
15+
16+
## Usage
17+
18+
**How does it work?**
19+
20+
In order to check if the test-subject has untracked changes, the given object or array will be normalized, flattened and
21+
stored using a configurable storage adapter.
22+
23+
The next time the check is executed the current data will be compared to the data of the previous check.
24+
Which of the subjects fields will be tracked or ignored can be [configured](#configuration) (see below).
25+
26+
**Usage:**
27+
28+
As the result of the check, you will receive a detailed list of fields that changed and the corresponding previous and
29+
current value:
30+
31+
```php
32+
$categoryId = 'category:123';
33+
$categoryData = [
34+
'title' => 'My Category',
35+
'tags' => ['Foo', 'Bar', 'Baz'],
36+
'createdAt' => '2024-07-10 15:31:00'
37+
];
38+
39+
$service = new \Sweikenb\Library\Dirty\Service\DirtyCheckService();
40+
41+
$result = $service->execute($categoryId, $categoryData);
42+
43+
if ($result->isDirty) {
44+
foreach ($result->diffs as $fieldPath => $diff) {
45+
echo sprintf("Field '%s' is dirty! '%s' -> '%s'\n", $fieldPath, $diff->previously, $diff->currently);
46+
}
47+
}
48+
```
49+
50+
### Configuration
51+
52+
In some cases you might have data-structures that contain volatile values (e.g. dynamic timestamps) that will always
53+
trigger a false-positiv for the dirty-check:
54+
55+
#### Ignore fields
56+
57+
If you want to **ignore** certain fields, you can specify which fields should be ignored during the check. If the
58+
configured fields contain complex data _(object or array)_ the affected field and all of it subsequent data will be
59+
**ignored** _(the field acts like a **wildcard**)_:
60+
61+
```php
62+
$userId = 'user:123';
63+
$userData = [
64+
'username' => 'some-user'
65+
'security' => [
66+
'password' => '...',
67+
'passwordSalt' => '...',
68+
'pgp-key' => '...'
69+
]
70+
'meta' => [
71+
'source' => 'sso'
72+
'createdAt' => '2024-07-10 15:41:10'
73+
]
74+
];
75+
76+
$config = new \Sweikenb\Library\Dirty\Model\ConfigModel(ignoreFieldPath: [
77+
'security', // will ignore the whole "security" subset
78+
'meta.createdAt' // will only ignore the "createdAt" field under "meta"
79+
]);
80+
81+
$service = new \Sweikenb\Library\Dirty\Service\DirtyCheckService();
82+
83+
$result = $service->execute($userId, $userData, $config);
84+
85+
if ($result->isDirty) {
86+
foreach ($result->diffs as $fieldPath => $diff) {
87+
echo sprintf("Field '%s' is dirty! '%s' -> '%s'\n", $fieldPath, $diff->previously, $diff->currently);
88+
}
89+
}
90+
```
91+
92+
#### Check only certain fields
93+
94+
You can also explicitly allow fields that should be checked, any other fields will be ignored. If the
95+
configured fields contain complex data _(object or array)_ the affected field and all of it subsequent data will be
96+
**checked** _(the field acts like a **wildcard**)_:
97+
98+
```php
99+
$userId = 'user:123';
100+
$userData = [
101+
'username' => 'some-user'
102+
'security' => [
103+
'password' => '...',
104+
'passwordSalt' => '...',
105+
'pgp-key' => '...',
106+
]
107+
'meta' => [
108+
'source' => 'sso'
109+
'createdAt' => '2024-07-10 15:41:10'
110+
]
111+
];
112+
113+
$config = new \Sweikenb\Library\Dirty\Model\ConfigModel([
114+
'username', // check the "username" field
115+
'meta', // check the "meta" field with all containing sub-fields
116+
]);
117+
118+
$service = new \Sweikenb\Library\Dirty\Service\DirtyCheckService();
119+
120+
$result = $service->execute($userId, $userData, $config);
121+
122+
if ($result->isDirty) {
123+
foreach ($result->diffs as $fieldPath => $diff) {
124+
echo sprintf("Field '%s' is dirty! '%s' -> '%s'\n", $fieldPath, $diff->previously, $diff->currently);
125+
}
126+
}
127+
```
128+
129+
#### Combine check and ignore fields
130+
131+
Please note that the "ignore"-configuration will be applied after the "allow"-configuration, that means you can combine
132+
them to enable certain structures and then explicitly remove a single field or subset from it:
133+
134+
```php
135+
$userId = 'user:123';
136+
$userData = [
137+
'username' => 'some-user'
138+
'security' => [
139+
'password' => '...',
140+
'passwordSalt' => '...',
141+
'pgp-key' => '...',
142+
]
143+
'meta' => [
144+
'source' => 'sso'
145+
'createdAt' => '2024-07-10 15:41:10'
146+
]
147+
];
148+
149+
$config = new \Sweikenb\Library\Dirty\Model\ConfigModel(
150+
[
151+
'username', // check the "username" field
152+
'meta', // check the "meta" field with all containing sub-fields
153+
],
154+
[
155+
'meta.createdAt', // ignore the "createdAt" sub-field even tough "meta" was explicitly configured to be checked
156+
]
157+
);
158+
159+
$service = new \Sweikenb\Library\Dirty\Service\DirtyCheckService();
160+
161+
$result = $service->execute($userId, $userData, $config);
162+
163+
if ($result->isDirty) {
164+
foreach ($result->diffs as $fieldPath => $diff) {
165+
echo sprintf("Field '%s' is dirty! '%s' -> '%s'\n", $fieldPath, $diff->previously, $diff->currently);
166+
}
167+
}
168+
```
169+
170+
## Storage Adapters
171+
172+
Storage adapters and their primary use-cases:
173+
174+
* **Filesystem Adapter** _(default)_
175+
* local **development** or stage environments
176+
* single-server setups
177+
* low amounts of data to check
178+
* this adapter is **NOT RECOMMENDED** to be used with a network storage mount and highly benefits from a fast
179+
underlying storage _(e.g. SSD)_
180+
* files will not be cleaned up automatically, you need to write your own script for that!
181+
* **REDIS Adapter** _(or compatible such as "ValKey")_
182+
* **Symfony** applications via [DirtyBundle](https://github.com/sweikenb/dirty-bundle)
183+
* **production** or stage environments
184+
* multi-server setups
185+
* any data-set size
186+
187+
You can add custom storage adapters if needed by implementing the `Sweikenb\Library\Dirty\Api\StorageAdapterInterface`.
188+
189+
## Configuration and customization
190+
191+
* _TODO_

‎composer.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"name": "sweikenb/dirty",
3+
"description": "Library for checking if an object or array has changes (is dirty) since the last check.",
4+
"type": "library",
5+
"license": "MIT",
6+
"authors": [
7+
{
8+
"name": "Simon Schröer",
9+
"email": "[email protected]"
10+
}
11+
],
12+
"require": {
13+
"php": "^8.2",
14+
"ext-json": "*",
15+
"symfony/serializer": "^6.4 | ^7.0",
16+
"symfony/property-access": "^6.4 | ^7.0"
17+
},
18+
"require-dev": {
19+
"ext-xdebug": "*",
20+
"phpunit/phpunit": "^11.2",
21+
"symplify/easy-coding-standard": "^12.3",
22+
"friendsofphp/php-cs-fixer": "^3.59"
23+
},
24+
"suggest": {
25+
"ext-redis": "*",
26+
"snc/redis-bundle": "*"
27+
},
28+
"autoload": {
29+
"psr-4": {
30+
"Sweikenb\\Library\\Dirty\\": "src/"
31+
},
32+
"exclude-from-classmap": [
33+
"examples/",
34+
"tests/"
35+
]
36+
},
37+
"autoload-dev": {
38+
"psr-4": {
39+
"Sweikenb\\Library\\Dirty\\Tests\\": "tests/"
40+
}
41+
},
42+
"scripts": {
43+
"phpcs-fixer": "./vendor/bin/php-cs-fixer fix src --rules=@Symfony",
44+
"phpunit": "XDEBUG_MODE=coverage php ./vendor/bin/phpunit -c phpunit.dist.xml"
45+
}
46+
}

‎examples/000_value_diffs.php‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?php
2+
3+
use Sweikenb\Library\Dirty\Service\DirtyCheckService;
4+
5+
require __DIR__.'/../vendor/autoload.php';
6+
7+
$dirtyCheck = new DirtyCheckService();
8+
9+
/*
10+
* Execute this example multiple times to see the library in action
11+
*/
12+
13+
$id = 'my_identifier';
14+
15+
$foo = [
16+
'some' => 'foo',
17+
'Bar' => 'baz',
18+
'foo' => microtime(true),
19+
];
20+
21+
$result = $dirtyCheck->execute($id, $foo);
22+
if ($result->isDirty) {
23+
foreach ($result->diffs as $fieldPath => $valueDiff) {
24+
echo sprintf("Field '%s' is dirty! '%s' -> '%s'\n", $fieldPath, $valueDiff->previously, $valueDiff->currently);
25+
}
26+
}

0 commit comments

Comments
 (0)