doublemcz/dibi-orm

ORM system based on dibi

Dibi ORM - EXPERIMENTAL

Dibi ORM is lightweight ORM solution based on Dibi. ORM logic comes from Doctrine 2 but is very simplified. Focus is also on performance., _(*1)

Installation

I recommend you to install via Composer., _(*2)

composer require doublemcz/dibi-orm

If you do not have Composer, download latest version from GitHub and require bootstrap file., _(*3)

require 'src/dibirom.php'

Initialization

$parameters = array(
    'database' => array(
        'host' => 'localhost',
        'username' => 'root',
        'password' => '',
        'database' => 'dibiorm',
        'driver' => 'mysqli',
    ),
    'entityNamespace' => 'App\Entities',
    'proxiesPath' => __DIR__ . '/temp',
    'storage' => new Nette\Caching\Storages\FileStorage('temp'),
);

$databaseManager = new \doublemcz\dibiorm\Manager($parameters);

Usage in Nette

Put this section into services.neon, _(*4)

extensions:
    dibi: Dibi\Bridges\Nette\DibiExtension22

services:
    databaseManager: doublemcz\dibiorm\Manager(%databaseManager%)

parameters:
    databaseManager:
        database: 
            host: localhost
            username: userName
            password: password
            database: database
        entityNamespace: App\Entities
        proxiesPath: '%tempDir%/proxies'
        storage: @cacheStorage

It is also possible to pass DibiConnection to parameter 'database', _(*5)

parameters:
    databaseManager:
        database: @dibiConnection

Data handling

Get an Entity by ID

Find a user with ID = 1, _(*6)

$databaseManager->find('User', 1);

If user has more columns in primary key, you can pass it in order you defined the key at the entity, _(*7)

$user = $databaseManager->find('AnEntityName', 'foo', 'bar');

Find an Entity by propety

We can find an Entity by property e-mail, _(*8)

$user = $databaseManager->findOneBy('User', array('email' => 'email@domain.com'));

Get entities in table

Find all users in table 'users', _(*9)

$users = $databaseManager->findBy('User');

You can filter and sort by array. We are trying to find Users in role 'admin' ordered by id desc., _(*10)

$users = $databaseManager
    ->findBy(
        'User', 
        array('role' => 'admin'),
        array('id' => 'DESC')
    );

Insert entity to database

$user = new User();
$user->name = 'Martin';
$databaseManager->persist($user);
$databaseManager->flush();

Update entity

When you load an entity from repository then the entity is automatically managed by Manager. It means that if you make a change and flush changes over Manager a SQL query is automatically executed., _(*11)

$user = $databaseManager->find('User', 1);
$user->note = 'An updated note on user 1';
$databaseManager->flush();

Delete entity

$user = $databaseManager->find('User', 1);
$database->delete($user);
$databaseManager->flush();

Database Manager knows what have changed

You can flush whenever you want. Manager knows what data have changed and does necessary stuff on flush., _(*12)

$user = $databaseManager->find('User', 1);
$user->note = 'An updated note on user 1';

$user2 = $databaseManager->find('User', 2);
$user2->note = 'An updated note on user 2';

$user3 = $databaseManager->find('User', 3);
$database->delete($user3);
// Flush makes automatically two sql updates and one delete
$databaseManager->flush();

Entity Settings

All settings are defined by PhpDoc. Every entity must have @table tag to specify the source table defined on class PhpDoc. Every class property that has relation to database column must have tag @column., _(*13)

Defining primary column

Every entity must have primary key. The definition is composed by @primaryKey and @column. If you want set id that was generated from database on create sql query then specify @autoIncrement tag., _(*14)

Relations

Basic relation are defined by @oneToOne and @oneToMany tag. Both need a join specification tag defined as follow: @join(column="id", referenceColumn="userId"). It says that it is joing column User.id to RelatedTable.userId column., _(*15)

Real example:

/**
 * @table (name="users")
 */
class User {
    /**
     * @oneToMany(entity="UserLog")
     * @join(column="id", referenceColumn="userId")
     * @var User
     */
    protected $userLog;

    /**
     * @return UserLog[]
     */
    public function getUserLog()
    {
        return  $this->userLog;
    }
}

Static join parameter

It is also possible to specify static join parameter to filter table by column. Here you can see static join that defines user.type = 'error'. Static join is possible only on @oneToOne and @oneToMany relations., _(*16)

/**
 * @table (name="users")
 */
class User {
    /**
     * @oneToMany(entity="UserLog")
     * @join(column="id", referenceColumn="userId")
     * @staticJoin(column="type", value="error")
     * @var User
     */
    protected $errorLog;

    /**
     * @return UserLog[]
     */
    public function getErrorLog()
    {
        return  $this->errorLog;
    }
}

Relation @manyToMany

Relation many-to-many is used when your data are connected over relation table., _(*17)

/**
 * @manyToMany(entity="AnEntityName", joiningTable="joining_table")
 * @joinPrimary(column="id", referenceColumn="userId")
 * @joinSecondary(column="userLogId", referenceColumn="id")
 * @var AnEntityName[]
 */
protected $foo;

Events

Manager has event handling based on methods included in the Class. We have Entity events at this moment: - beforeCreateEvent - beforeUpdateEvent, _(*18)

Examples of event usage.

There you can see how we can update an entity before create or update sql is executed., _(*19)

/**
 * @param Manager $manager
 */
public function beforeCreateEvent(Manager $manager)
{
    $this->createdAt = new \DateTime();
}

public function beforeUpdateEvent(Manager $manager)
{
    $this->updatedAt = new \DateTime();
}

Example of User entity definition

<?php

namespace doublemcz\dibiorm\Examples\Entities;
use doublemcz\dibiorm\Manager;

/**
 * @table (name="users")
 */
class User {
    /**
     * @primaryKey
     * @autoIncrement
     * @column
     * @var int
     */
    public $id;

    /**
     * @oneToMany(entity="UserLog")
     * @join(column="id", referenceColumn="userId")
     * @var User
     */
    protected $userLog;

    /**
     * @oneToMany(entity="UserLog")
     * @join(column="id", referenceColumn="userId")
     * @staticJoin(column="type", value="error")
     * @var User
     */
    protected $userErrorLog;

    /**
     * @oneToOne(entity="UserDetail")
     * @join(column="id", referenceColumn="userId")
     * @var UserDetail
     */
    protected $detail;

    /**
     * @column
     * @var string
     */
    public $fullname;

    /**
     * @column
     * @var \DateTime
     */
    public $birthDate;

    /**
     * @column
     * @var \DateTime
     */
    public $createdAt;

    /**
     * @column
     * @var \DateTime
     */
    public $updatedAt;

    /**
     * @return UserLog[]
     */
    public function getUserLog()
    {
        return $this->userLog;
    }

    /**
     * @return UserDetail
     */
    public function getDetail()
    {
        return $this->detail;
    }

    /**
     * @param Manager $manager
     */
    public function beforeCreateEvent(Manager $manager)
    {
        $this->createdAt = new \DateTime();
    }

    public function beforeUpdateEvent(Manager $manager)
    {
        $this->updatedAt = new \DateTime();
    }
}