5   Repository

5.1   About the repository

The repository is the link between your entity object and your database, through the Query object.

It also bear the responsibility to intialize Metadata related to your entity, to learn how to map your database object.

5.2   Creating Metadata

As an example speaks louder than words:

use CCMBenchmark\Ting\Repository\Repository;
use CCMBenchmark\Ting\Serializer\SerializerFactoryInterface;
use CCMBenchmark\Ting\Repository\MetadataInitializer;

class SampleRepository extends Repository implements MetadataInitializer
{
    public static function initMetadata(SerializerFactoryInterface $serializerFactory, array $options = [])
    {
        $metadata = new Metadata($serializerFactory);

        $metadata->setEntity(Sample\Model\City::class);
        $metadata->setConnectionName('main');
        $metadata->setDatabase('world');
        $metadata->setTable('t_city_cit');

        $metadata
            ->addField([
                'primary'       => true,
                'autoincrement' => true,
                'fieldName'     => 'id',
                'columnName'    => 'cit_id',
                'type'          => 'int'
            ])
            ->addField([
                'fieldName'  => 'name',
                'columnName' => 'cit_name',
                'type'       => 'string'
            ]);

        return $metadata
    }
Some details:
  • fieldName is the name of the property of your entity
  • columnName is the name of the column in your database
  • type is the type of your variable; among one of the following :
    • int
    • double
    • string
    • bool
    • datetime
    • json

The types bool, datetime and json are a bit special because they are dependent of database so they can be serialized / deserialized with some options:

5.3   Serializer

5.3.1   About the serializer

Serialization is the operation which transform PHP data into understandable data for RDBMS. The reverse operation is called unserialization

Serializer allow complex type management like bool, datetime and json.

The boolean type is considered a complex type, because the way they are stored in the database differs depending on each RDBMS
  • CCMBenchmark\Ting\Driver\Pgsql\Serializer\Boolean
  • CCMBenchmark\Ting\Driver\Mysqli\Serializer\Boolean

The datetime type is considered as complex because it transform DateTime object into understandable format by RDBMS

The json type is complex because it translate data array into string understandable by RDBMS

5.3.2   Serializer configuration

Serializer is configured by serializer_options key

addField([
    'fieldName'          => 'tags',
    'columnName'         => 'tags_name',
    'type'               => 'json',
    'serializer_options' => [
        'unserialize' => ['assoc' => true]
    ]
]);

Please take a look at the source code of each Serializer to see available options.

5.3.3   Writing a serializer

You can write your own serializers and inject it into the repository definition by using serializer key

The serializer must implements interface CCMBenchmark\Ting\Serializer\SerializeInterface and/or CCMBenchmark\Ting\Serializer\UnserializeInterface. If you want implents both interfaces, you must use CCMBenchmark\Ting\Serializer\SerializerInterface

The interface CCMBenchmark\Ting\Serializer\SerializeInterface transform a value into a data understandable by DMBS. The interface CCMBenchmark\Ting\Serializer\UnserializeInterface authorize the reverse operation

addField([
    'fieldName'  => 'tags',
    'columnName' => 'tags_name',
    'type'       => 'json',
    'serializer' => Bouh\Awesome\Serializer::class
]);

5.4   QueryBuilder

We can need chaining queries, a QueryBuilder can be used. Ting provide it through aura/sqlquery.

$repository->getQueryBuilder(Repository::QUERY_SELECT);

or

$repository->getQueryBuilder(Repository::QUERY_INSERT);

or

$repository->getQueryBuilder(Repository::QUERY_UPDATE);

or

$repository->getQueryBuilder(Repository::QUERY_DELETE);

Documentation available on https://github.com/auraphp/Aura.SqlQuery

5.5   Queries

The Repository provides several methods to perform common queries easily.

5.5.1   Find an object by it’s primary key

$repository->get(['id' => 3])

5.5.2   All items

$repository->getAll()

5.5.3   An object according to one or more properties of the model

$repository->getOneBy(['propertyName' => 'Sylvain']);

5.5.4   An object collection, according to one or more properties of the model

$repository->getBy(['propertyName' => 'Sylvain']);