Skip to content

Commit 378a2ac

Browse files
tomkyletomkyle
committed
Initial commit
0 parents  commit 378a2ac

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+13094
-0
lines changed

‎.github/workflows/dependency-review.yml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Dependency Review Action
2+
#
3+
# This Action will scan dependency manifest files that change as part of a Pull Reqest, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
4+
#
5+
# Source repository: https://github.com/actions/dependency-review-action
6+
# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
7+
#
8+
# Last revised: 2024/02/11
9+
#
10+
name: 'Dependency Review'
11+
on: [pull_request]
12+
13+
permissions:
14+
contents: read
15+
16+
jobs:
17+
dependency-review:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: 'Checkout Repository'
21+
uses: actions/checkout@v4
22+
- name: 'Dependency Review'
23+
uses: actions/dependency-review-action@v4

‎.github/workflows/php.yml

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# php.yml
2+
3+
# Stolen from osteel’s article:
4+
# A GitHub workflow to check the compatibility of your PHP package with a range of dependency versions
5+
# https://tech.osteel.me/posts/a-github-workflow-to-check-the-compatibility-of-your-php-package-with-a-range-of-dependency-versions
6+
7+
name: Tests
8+
9+
on:
10+
push:
11+
branches: [ main, develop ]
12+
pull_request:
13+
branches: [ main ]
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
phpunit:
20+
name: Tests
21+
runs-on: ubuntu-latest
22+
23+
strategy:
24+
fail-fast: false
25+
matrix:
26+
php-version:
27+
- "8.2"
28+
- "8.3"
29+
dependency-versions:
30+
- "lowest"
31+
- "highest"
32+
33+
steps:
34+
- name: Checkout Repository
35+
uses: actions/checkout@v4
36+
37+
- name: Setup PHP
38+
uses: shivammathur/setup-php@v2
39+
with:
40+
php-version: ${{ matrix.php-version }}
41+
coverage: none
42+
43+
- name: Install Composer dependencies
44+
uses: ramsey/composer-install@v2
45+
with:
46+
dependency-versions: ${{ matrix.dependency-versions }}
47+
48+
- name: Run PHPUnit
49+
run: vendor/bin/phpunit tests
50+
51+
- name: Run phpstan
52+
run: vendor/bin/phpstan analyse

‎.gitignore

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Compiled source #
2+
###################
3+
*.com
4+
*.class
5+
*.dll
6+
*.exe
7+
*.o
8+
*.so
9+
10+
# Packages #
11+
############
12+
# it's better to unpack these files and commit the raw source
13+
# git has its own built in compression methods
14+
*.7z
15+
*.dmg
16+
*.gz
17+
*.iso
18+
*.jar
19+
*.rar
20+
*.tar
21+
*.zip
22+
23+
# Logs and databases #
24+
######################
25+
*.log
26+
*.sql
27+
*.sqlite
28+
29+
# OS generated files #
30+
######################
31+
.DS_Store
32+
.DS_Store?
33+
._*
34+
.Spotlight-V100
35+
.Trashes
36+
ehthumbs.db
37+
Thumbs.db
38+
.LSOverride
39+
Icon
40+
.AppleDouble
41+
42+
43+
# Project files #
44+
######################
45+
vendor
46+
node_modules
47+
var/*
48+
tests/build/*
49+
phpunit.xml
50+
.phpunit.result.cache
51+
phpstan.neon
52+
.php-cs-fixer.php
53+
.php-cs-fixer.cache
54+

‎.php-cs-fixer.dist.php

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
$header = <<<EOF
3+
tomkyle/repository-persistence
4+
5+
Scaffold for Repository-and-Persistence design pattern
6+
EOF;
7+
8+
$finder = PhpCsFixer\Finder::create()
9+
->in([
10+
__DIR__ . '/src',
11+
__DIR__ . '/tests'
12+
]);
13+
14+
return (new PhpCsFixer\Config())->setRules([
15+
'@PSR12' => true,
16+
'header_comment' => [
17+
'comment_type' => 'PHPDoc',
18+
'header' => $header,
19+
'location' => 'after_open',
20+
'separate' => 'both',
21+
]
22+
])->setFinder($finder);

‎LICENSE

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

‎README.md

+212
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
<h1 align="center">Repository · Persistence</h1>
2+
3+
[![PHP Composer](https://github.com/tomkyle/repository-persistence/actions/workflows/php.yml/badge.svg)](https://github.com/tomkyle/repository-persistence/actions/workflows/php.yml)
4+
5+
**Scaffold for Repository-and-Persistence design pattern.**
6+
7+
---
8+
9+
## Installation
10+
11+
```bash
12+
$ composer require tomkyle/repository-persistence
13+
```
14+
15+
## Setup
16+
17+
**The repository needs a persistence.**
18+
19+
```php
20+
<?php
21+
22+
use tomkyle\RepositoryPersistence\Repositories\Repository;
23+
use tomkyle\RepositoryPersistence\Persistence;
24+
25+
$repo = new Repository(
26+
new Persistence\JsonFilePersistence('path/to/json')
27+
);
28+
```
29+
30+
## Usage
31+
32+
**Get item.** This method may throw `\OutOfBoundsException`
33+
34+
```php
35+
$repo->get(42);
36+
$repo->get('foo');
37+
```
38+
39+
**Find one item by criteria.** This method my return `null`.
40+
41+
```php
42+
$repo->findOneBy([
43+
'name' => 'John'
44+
]);
45+
```
46+
47+
**Get all items:**
48+
49+
```php
50+
$repo->findAll();
51+
```
52+
53+
**Find items by criteria**
54+
55+
```php
56+
$repo->findBy([
57+
'color' => 'blue'
58+
]);
59+
```
60+
61+
**Update item**
62+
63+
```php
64+
$saved = $repo->save(['id' => 43, 'name' => 'John']));
65+
```
66+
67+
**Delete item**
68+
69+
```php
70+
$repo->delete(43);
71+
```
72+
73+
**Create new item**
74+
75+
```php
76+
$saved = $repo->save(['name' => 'Angie']));
77+
```
78+
79+
If you need the new ID onbeforehand in your App controller, e.g. for redirecting the client to the new resource, you can obtain a new ID from the repo. It then looks exactly like updating, but the *Repository* implementation will figure out if the item has to be created or updated.
80+
81+
```php
82+
$new_id = $repo->getNextId();
83+
$repo->save(['id' => $new_id, 'name' => 'Angie']));
84+
```
85+
86+
87+
88+
---
89+
90+
## Persistence
91+
92+
Inside a repository, the *Persistence* actually manages the data storage.
93+
94+
### Instantiation
95+
96+
```php
97+
<?php
98+
use tomkyle\RepositoryPersistence\Repositories;
99+
use tomkyle\RepositoryPersistence\Persistence;
100+
101+
$persistence = new Persistence\JsonFilePersistence('path/to/json');
102+
$persistence = new Persistence\YamlFilePersistence('path/to/yaml');
103+
```
104+
105+
### Methods API
106+
107+
| Method | Parameters | Return | Description |
108+
| ------- | --------------- | ------------ | ------------- |
109+
| create | `array` data | `string|int` | New ID |
110+
| read | `string|int` id | `array` | The record |
111+
| readAll | | array | All records |
112+
| update | `array` data | `int` | Affected rows |
113+
| delete | `string|int` | `int` | Affected rows |
114+
115+
### Special implementations
116+
117+
#### FrontmatterFilePersistence
118+
119+
If your JSON or YAML files have frontmatters:
120+
121+
```php
122+
$persistence = new Persistence\FrontmatterFilePersistence(
123+
new Persistence\JsonFilePersistence('path/to/json')
124+
);
125+
```
126+
127+
#### PersistenceChain
128+
129+
```php
130+
$persistence = new Persistence\PersistenceChain(
131+
new Persistence\JsonFilePersistence('path/to/json'),
132+
new Persistence\YamlFilePersistence('path/to/yaml')
133+
);
134+
```
135+
136+
#### InMemoryPersistence
137+
138+
An empty *Persistence* you can write and read to.
139+
140+
```php
141+
$persistence = new Persistence\InMemoryPersistence();
142+
```
143+
144+
#### NoPersistence
145+
146+
Mock implementation of *Persistence* that simulates data persistence operations without actually storing data. Note that *read* method will always throw `\OutOfBoundsException` as it does not contain any data!
147+
148+
```php
149+
$persistence = new Persistence\NoPersistence();
150+
```
151+
152+
153+
154+
---
155+
156+
## Repository
157+
158+
The repository is the thing you work with in your app.
159+
160+
```php
161+
<?php
162+
use tomkyle\RepositoryPersistence\Repositories\Repository;
163+
use tomkyle\RepositoryPersistence\Persistence;
164+
165+
// Feed a persistence to the repo:
166+
$persistence = new Persistence\InMemoryPersistence();
167+
$repository = new Repository($persistence)
168+
```
169+
170+
### Methods API
171+
172+
| Method | Required Parameters | Optional | Return | Description |
173+
| --------- | --------------------- | -------------------------------------------------------- | ------------------- | ------------ |
174+
| get | id | | `array|object` | The record |
175+
| findOneBy | `array` criteria | | `array|object|null` | One record |
176+
| findAll | | | `iterable` | All records |
177+
| findBy | `array` criteria | `?array` orderBy,<br /> `?int` limit<br /> `?int` offset | `iterable` | Some records |
178+
| save | `array|object` entity | | `bool` | |
179+
| delete | `array|object` entity | | `bool` | |
180+
181+
---
182+
183+
## Development
184+
185+
### Install requirements
186+
187+
```bash
188+
$ composer install
189+
$ npm install
190+
```
191+
192+
### Watch source and run various tests
193+
194+
This will watch changes inside the **src/** and **tests/** directories and run a series of tests:
195+
196+
1. Find and run the according unit test with *PHPUnit*.
197+
2. Find possible bugs and documentation isses using *phpstan*.
198+
3. Analyse code style and give hints on newer syntax using *Rector*.
199+
200+
```bash
201+
$ npm run watch
202+
```
203+
204+
#### Run all tests
205+
206+
Choose to your taste:
207+
208+
```bash
209+
$ npm run phpunit
210+
$ composer test
211+
```
212+

0 commit comments

Comments
 (0)