bravo3/orm

NoSQL ORM for databases such as Redis

Document Object Relational Mapper

Purpose

The purpose of this library is to blend ORM and ODM fundamentals with NoSQL database platforms, allowing you to use NoSQL databases with pseudo-relationships through means of a traditional entity manager., _(*1)

Table of Contents

• Drivers
• Entity Mapping Definitions
• Events
• PubSub
• Important Notes
• Index Types
• Key Schemes
• Project Structure
• Queries
• Race Conditions
• Serialisers
• Mappers - Yaml

Further Examples

• Auto-updating Time Stamps
• Getters and Setters
• Lookup Indices
• Multi-Column IDs
• Sorted Relationships

Advanced/Internals

• Refs
• Entity Locator

Example

If you intend to use Redis, please include Predis in your composer.json:, _(*2)

"require": {
    "predis/predis": "~1.0"
}

Creating an entity manager for a Redis database with annotation mappings:, _(*3)

$em = new EntityManager(
    new RedisDriver(['host' => 'example.com']),
    new AnnotationMapper()
);

Persisting a simple relationship:, _(*4)

$address = new Address();
$address->setId(1)->setStreet("123 Example St");

$user = new User();
$user->setId(1)->setName("Harry")->setAddress($address);

$em->persist($user)->persist($address)->flush();

Retrieving a relationship with lazy-loading:, _(*5)

$user = $em->retrieve('User', 1);   // Only user entity retrieved
$address = $user->getAddress();     // DB call to get address made here

Example entity files:, _(*6)

User.php, _(*7)

<?php
use Bravo3\Orm\Annotations as Orm;

/**
 * @Orm\Entity(table="users")
 */
class User
{
    /**
     * @var int
     * @Orm\Id
     * @Orm\Column(type="int")
     */
    protected $id;

    /**
     * @var string
     * @Orm\Column(type="string")
     */
    protected $name;

    /**
     * @var Address
     * @Orm\ManyToOne(target="Address", inversed_by="users")
     */
    protected $address;

    // Other getters and setters here

    /**
     * Get Address
     *
     * @return Address
     */
    public function getAddress()
    {
        return $this->address;
    }

    /**
     * Set Address
     *
     * @param Address $address
     * @return $this
     */
    public function setAddress(Address $address)
    {
        $this->address = $address;
        return $this;
    }
}

Address.php, _(*8)

<?php
use Bravo3\Orm\Annotations as Orm;

/**
 * @Orm\Entity
 */
class Address
{
    /**
     * @var int
     * @Orm\Id
     * @Orm\Column(type="int")
     */
    protected $id;

    /**
     * @var string
     * @Orm\Column(type="string")
     */
    protected $street;

    /**
     * @var User[]
     * @Orm\OneToMany(target="User", inversed_by="address")
     */
    protected $users;

    // Other getters and setters here

    /**
     * Get users
     *
     * @return User[]
     */
    public function getUsers()
    {
        return $this->users;
    }

    /**
     * Set users
     *
     * @param User[] $users
     * @return $this
     */
    public function setUsers(array $users)
    {
        $this->users = $users;
        return $this;
    }

    /**
     * Add a user
     *
     * @param User $user
     * @return $this
     */
    public function addUser(User $user)
    {
        $this->users[] = $user;
        return $this;
    }
}

Bundled Strategies

Databases

• Redis
• Native filesystem
• Tar or zip archives

See drivers for more info on database implementations., _(*9)

Serialisation

• JSON

Entity Metadata Mappers

• Annotation
• YAML

Key Schemes

• Standard scheme: configurable delimiter, defaulting to Redis-style
• Filesystem path scheme

Major Planned Additions

• Validation service

Change Log

0.5.6

• Added a YAML mapper
• Added map portation to easily convert between mapping types

0.5.5

• Add a chained mapper, allowing you to examine multiple forms of entity mapping in a single project

0.5.0

• Removed 'entity hydration errors as events' due to its dangerous nature
• Added a filesystem driver - designed for backup purposes but could also serve has a mini internal database

0.4.3

• Added the ability to perform sorted, conditional queries on all items in a table
• Added the ability to name sorted queries, allowing different configurations of conditions on the same column

0.3.13

• Changed logic for retrieving entities. If nothing found (during writing) it will generate a new instance of the entity with the correct id
• Retrieving an entity with missing relatives will now return blank new instances of the relatives

0.3.0

• Added ref tables to maintain non-reciprocated relationships
• Added restrictions to table names and entity ID values
• Changed sort index key names to include the relationship name (WARNING: will break existing data)
  • Multiple relationships with the same sort-by columns would conflict
  • Use the Maintenance#rebuild() function to repair sort indices

0.2.0

• Added EntityManager::refresh()
• The entity manager will now remember previously retrieved entities and return them instead of querying the database
• Added $use_cache parameter to all retrieve*() and *Query() functions on the entity manager