Agile Data for Doctrine users

Agile Data offers a similar feature set to that of Doctrine-ORM, this document will explain how to transition.

Overview

Model in Agile Data is somewhat similar to Entity, but with a more flexible / loose implementation of Inheritance mapping (see joins below). Model is a simple class that functions like an associative array:

$m['name'] = "John";

// or 

$m->set('name', 'John');

Each model defines method init() that is called when Model is associated with a specific Persistence (SQL, Array or REST). The job of init() method is to define the following:

• Field - defines Fields and their parameters (such as mapping, type, default values)
• Join - defines how to join tables for CRUD operations
• Conditions - similar to Filter Constraint
• Hooks - similar to Behaviours

using Model methods (addField, join, addCondition, addHook). Those methods may use different 'Classes' for creating dependent objects based on persistence:

• Persistence_Array - addField() creates new object of 'Field' class.
• Persistence_SQL - addFiled() creates new object of 'Field_SQL' class, which knows a bit more about SQL.

Conditions and Hooks don't create a new object but are stored as an array internally inside Model. I must note that once model is associated with persistence, it cannot be detached. There is a mechanism, however, allowing you to persist associated model elsewhere.

Models are mutable and while some operations can be reversed, others cannot (by design).

Conditions and Data Sets

The Model supports permanent conditions for your entities. This operation limits which records Model can load from Persistence. The set of all those "loadable records" is called DataSet and is a core feature of Agile Data.

Once the condition is added to the model object, it cannot be used to save, update, delete or execute other operations outside of records outside the new DataSet for safety reasons.

• ref: http://stackoverflow.com/questions/25098027/can-i-specify-default-conditions-in-doctrine-queries

Relations

Although they may appear similar to Associations, Relations in Agile Data are quite different.

• Relation is always defined between entities (never between tables)
• Relations are designed around "business logic" rather than "foreign keys in the database"
• Two Models can have many various relations
• Relations can add Conditions for destination Model
• Conditions can use data of an active record
• Traversing Relation always generates a new Model

Workflow

Defining Database Structure

You normally don't reverse-engineer the schema in Agile Data but are asked right from the start to think in terms of Business Entities. If the record in table user cannot exist without user_details record, then your 'Model_User' will be defining join between both tables and the rest of your business logic will honour the association. Once defined like that it will be impossible to create stray records in user records.

Multiple business models can use the same table, without a common ancestor. When extending model you can even specify a different table.

CRUD operations

Once your model object is associated with Persistence, you can re-use it to load various records:

$m = new Model_User($db);
$m->load(3);
$m->set('name', 'John');
$m->save();

$m->load(5)->delete();

$m->addCondition('is_vip', true);
$m->loadAny();
var_dump($m->get());

Inline definitions

Agile Data is unique in allowing you to create on-the-fly definitions for your Models. This can be used by developer for data integrity:

$m = new Model_User($db);
$m->addCondition('is_confirmed', true);
$m->loadBy('email', $email);
$m->verifyPassword($password);

and is extensively used by Relations.