Using the Object Relational Model (ORM)

In Emergence ORM is provided in the form of a feature that is part of the ActiveRecord class. Any model derived from an Emergence ActiveRecord class may use the built in ORM features. This page will provide a guide and a reference for the configuration of ORM.

Types of Relationships

Emergence supports these relationship types.

Type Description Returns
one-one A single foreign object that corresponds to an attribute value of the local object. A single instance of an object or false if none found.
one-many Many foreign objects that correspond to an attribute value of the local object. An array of objects even if only one object is found. False if none found.
context-children Many objects that are attached to the current object with field ContextParent equal to the name of the current class and the value of ContextID being the name of the current object's primary key. An array of objects even if only one object is found. False if none found.
context-child An object that is attached to the current object with field ContextParent equal to the name of the current class and the value of ContextID being the name of the current object's primary key. A single instance of an object or false if none found.
context-parent An object that is being attached to by the current object with field ContextParent equal to the name of the parent class and the value of ContextID being the name of the parent object's primary key. A single instance of an object or false if none found.

One-one

Configuration Options

Option Required Description
class Yes The fully qualified PHP class name of the foreign object.
local No This is the name of the local attribute that contains the key for the foreign object. ActiveRecord will automatically use the name of the relationship with the letters ID appended to the end as the default value. For example if the relationship name was "Payment", ActiveRecord would check for "PaymentID". Otherwise you may specify anything.
foreign No This is the name of the foreign attribute that contains the primary key of the foreign object. "ID" is used as a default.

Examples

One-many

Configuration Options

Option Required Description
class Yes The fully qualified PHP class name of the foreign object.
local No This is the name of the local attribute that contains the key for the foreign objects. ActiveRecord will automatically use ID as the default value.
foreign No This is the name of the foreign attribute that contains the key for the foreign object. The full qualified PHP class name of the local root class is used as the default.
indexField No Default is false.
conditions No Additional conditions that must be met for any matches from this relationship. Can be a string of raw SQL that comes after the "WHERE" clause in SQL or an array of conditions that will automatically glue together and assume an AND operator.
order No A string of RAW SQL that proceeds immediatly after the SQL "ORDER BY" clause or an array of key value pairs where the key is the name of the field and the value is the order direction ASC or DESC. The default order when none is specified is `ID` DESC.

Examples

Context-children

Context children is a special relationship that allows an object to access all objects of a specific class. The child object will declare a ContextClass which is the PHP class of it's parent and a ContextID to specify which specific object to use as the parent.

This relationship type allows the parent object to access it's children of a specific class.

Configuration Options

Option Required Description
class Yes The fully qualified PHP class name of the foreign object.
local No This is the name of the local attribute that contains the key for the foreign objects. ActiveRecord will automatically use ID as the default value.
contextClass No This is the name of the fully qualified PHP class name of the local object. This is normally set for you by default however in some cases you may want to specify a specific class name. Especially if the local class has children classes that extend it.
indexField No Default is false.
conditions No Additional conditions that must be met for any matches from this relationship. Can be a string of raw SQL that comes after the "WHERE" clause in SQL or an array of conditions that will automatically glue together and assume an AND operator.
order No A string of RAW SQL that proceeds immediatly after the SQL "ORDER BY" clause or an array of key value pairs where the key is the name of the field and the value is the order direction ASC or DESC. The default order when none is specified is `ID` DESC.

Examples

Context-child

This is the same as the context-children relationship type but this will only return a single object or false if none is found.

The returned object will always return the first in the set if multiple objects fit the configured criteria.

Configuration Options

Option Required Description
class Yes The fully qualified PHP class name of the foreign object.
local No This is the name of the local attribute that contains the key for the foreign objects. ActiveRecord will automatically use ID as the default value.
contextClass No This is the name of the fully qualified PHP class name of the local object. This is normally set for you by default however in some cases you may want to specify a specific class name. Especially if the local class has children classes that extend it.
indexField No Default is false.
conditions No Additional conditions that must be met for any matches from this relationship. Can be a string of raw SQL that comes after the "WHERE" clause in SQL or an array of conditions that will automatically glue together and assume an AND operator.
order No A string of RAW SQL that proceeds immediatly after the SQL "ORDER BY" clause or an array of key value pairs where the key is the name of the field and the value is the order direction ASC or DESC. The default order when none is specified is `ID` DESC.

Examples

Context-parent

A special relationship that allows you to attach local objects to another class as its' "parent".

This relationship type allows you to quickly access a local object's parent.

Configuration Options

Option Required Description
local No This is the name of the local attribute that contains the key for the foreign objects. For this relationship type ActiveRecord will automatically use ContextID as the default value.
foreign No This is the name of the foreign attribute that contains the key for the foreign object. ID will be used as a default.
classField No This is the local object's field that contains as its' value the foreign object's fully qualified PHP class name.

Examples