tomkyle/repository-persistence

Scaffold for Repository-and-Persistence design pattern

dev-main 2024-02-12 08:29 UTC

Requires

• php: ^8.2
• nette/utils: ^4.0.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.11
• mnapoli/silly: ^1.9
• php-coveralls/php-coveralls: ^2.5.2
• phpspec/prophecy-phpunit: ^2.0.1
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.5
• rector/rector: ^1.0
• roave/security-advisories: dev-latest
• spatie/temporary-directory: ^2.2
• spatie/yaml-front-matter: ^2.0
• symfony/finder: ^7.0
• symfony/yaml: ^7.0

proprietary

README

Scaffold for Repository-and-Persistence design pattern.

Installation

$ composer require tomkyle/repository-persistence

Setup

The repository needs a persistence.

<?php

use tomkyle\RepositoryPersistence\Repositories\Repository;
use tomkyle\RepositoryPersistence\Persistence;

$repo = new Repository(
	new Persistence\JsonFilePersistence('path/to/json')
);

In this example, the Persistence works on a directory path/to/json in which the items are stored in JSON files named by their ID. — Example: john-doe.json

{
  "age": 30,
  "city": "New York",
  "name": "John Doe"
}

Usage

Get item. This method may throw \OutOfBoundsException

try {
  $person = $repo->get('john-doe');
  print_r($person);
} 
catch (\OutOfBoundsException) {
  // Not found
}

Output will be like:

Array  (
  [age] => 30
  [city] => New York
  [name] => John Doe
)

Find one item by criteria. This method my return null.

$repo->findOneBy([
  'name' => 'John'
]);  

Get all items:

$repo->findAll();

Find items by criteria

$repo->findBy([
  'color' => 'blue'
]);

Update item

$saved = $repo->save(['id' => 43, 'name' => 'John']));

Delete item

$repo->delete(43);

Create new item

$saved = $repo->save(['name' => 'Angie']));

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.

$new_id = $repo->getNextId();
$repo->save(['id' => $new_id, 'name' => 'Angie']));

Persistence

Inside a repository, the Persistence actually manages the data storage.

Instantiation

<?php
use tomkyle\RepositoryPersistence\Repositories;
use tomkyle\RepositoryPersistence\Persistence;

$persistence = new Persistence\JsonFilePersistence('path/to/json');
$persistence = new Persistence\YamlFilePersistence('path/to/yaml');

Methods API

Method	Parameters	Return	Description
create	array data	`string	int`
read	`string	int` id	array
readAll		array	All records
update	array data	int	Affected rows
delete	`string	int`	int

Special implementations

FrontmatterFilePersistence

If your JSON or YAML files have frontmatters:

$persistence = new Persistence\FrontmatterFilePersistence(
	new Persistence\JsonFilePersistence('path/to/json')
);

PersistenceChain

$persistence = new Persistence\PersistenceChain(
	new Persistence\JsonFilePersistence('path/to/json'),
	new Persistence\YamlFilePersistence('path/to/yaml')
);

InMemoryPersistence

An empty Persistence you can write and read to.

$persistence = new Persistence\InMemoryPersistence();

NoPersistence

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!

$persistence = new Persistence\NoPersistence();

Repository

The repository is the thing you work with in your app.

<?php
use tomkyle\RepositoryPersistence\Repositories\Repository;
use tomkyle\RepositoryPersistence\Persistence; 

// Feed a persistence to the repo:
$persistence = new Persistence\InMemoryPersistence();
$repository = new Repository($persistence)

Methods API

Method	Required Parameters	Optional	Return	Description
get	`string	id` id		`array
findOneBy	array criteria		`array	object
findAll			iterable	All records
findBy	array criteria	?array orderBy, ?int limit ?int offset	iterable	Some records
save	`array	object` entity		bool
delete	`array	object` entity		bool

Development

Install requirements

$ composer install
$ npm install

Watch source and run various tests

This will watch changes inside the src/ and tests/ directories and run a series of tests:

1. Find and run the according unit test with PHPUnit.
2. Find possible bugs and documentation isses using phpstan.
3. Analyse code style and give hints on newer syntax using Rector.

$ npm run watch

Run all tests

Choose to your taste:

$ npm run phpunit
$ composer test