Repository · Persistence

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 may 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	New ID
read	string¦int id	array	The record
readAll		array	All records
update	array data	int	Affected rows
delete	string¦int	int	Affected rows

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¦int id		array¦object	The record
findOneBy	array criteria		array¦object¦null	One record
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