README

weblibs-dbabstraction

weblibs-dbabstraction is an simple and lightweight Abstraction library for the database and ORM modules.

Why use weblibs-dbabstraction ?

The purpose of this project is to propose a simple and lightweight alternative solution instead of more big and complex projects such as Doctrine.

Installation

The recommended way to install weblibs-dbabstraction is through Composer.

composer require clagiordano/weblibs-dbabstraction

Description of the main components

Adapter description

Is a persistence layer which interact with database or other backends. An adapter class must be implements the DatabaseAdapterInterface for compatibility with other components.
The default adapter is the already defined PDOAdapter wich simplify the access to PDO object and related methods.
Other specific adapters can be implemented to easily access to other backends.

Adapter usage

new PDOAdapter(
    $dbHost,
    $dbUser,
    $dbPassword,
    $dbName,
    $dbDriver,
    $dbCharset,
    $isPersistent
);

See PDOAdapterTest class (phpunit test class) for full sample usage into tests folder.

Entity description

An entity is an object which expose properties dynamically generated from an array of fields. It is a simple class which have defined the magic methods (__set, __get ... ).
The entity is automatically used by the mapper class for the operations and can be used to gets and sets its properties.
For more details please see the SampleEntity class into testdata folder.

Entity usage

An entity class must be extends AbstractEntity as:

/**
 * Class SampleEntity
 */
class SampleEntity extends AbstractEntity
{
}

Then can be used:

$entityClass->property = "value";
echo $entityClass->property;

Mapper description

A mapper is a glue between Entity and Adapter objects which expose high level method to use and persists data.
A mapper class must be extends the AbstractMapper:

/**
 * Class SampleMapper
 */
class SampleMapper extends AbstractMapper
{

then must be declare two protected properties to connect database table for persistence and the related entity class:

protected $entityTable = 'sample_table';
protected $entityClass = 'SampleEntity';

therefore must be implements the abstract method createEntity for the correct mapping between table fields and the desidered entity properties:

protected function createEntity(array $fields)
{
    return new SampleEntity(
        [
            'id' => $fields['id'],
            'code' => $fields['code'],
            'brand' => $fields['brand'],
            'model' => $fields['model'],
            'description' => $fields['description']
        ]
    );
}

You can also define additional methods if necessary or override existing ones such as insert, update, delete etc to modify its behavior.

Mapper usage

To improve control and security AbstractMapper's methods can be overrided:

/**
 * Sample overrided insert method
 *
 * @param SampleEntity $entity
 * @return mixed
 */
public function insert($entity)
{
    if (!$entity instanceof SampleEntity) {
        throw new \InvalidArgumentException(
            __METHOD__ . ": Invalid entity type."
        );
    }

    return $this->adapter->insert($this->entityTable, $entity->toArray());
}

As you can see, this overrided method require explicitly an instance of SampleEntity to works, the same way you can run a validation or additional arguments formatting/sanitizing or whatever you want.

Legal

Copyright (C) Claudio Giordano claudio.giordano@autistici.org

clagiordano / weblibs-dbabstraction

Maintainers

Details