Documentation

cached_object($objpk, $class = null)

The cached_object method allows you to retrieve specific model object from the object cache, by primary key and model class name.

null

// tries to retrieve OtherModel object with primary key value "12" from the cache
$from_cache = MyModel::cached_object(12, 'OtherModel');

condition($type = null)

The condition method allows you to retrieve the models defined conditions.

null

// tries to retrieve MyModel where conditions
$where = MyModel::conditions('where');

connection($writeable = false)

The connection method allows you to retrieve the models defined database connection.

false

// retrieves the MyModel write connection
$where = MyModel::connection(true);

find($id = null, $options = null)

The find method allows you to retrieve record as a model object or an array of model objects.

null

null

See the CRUD documentation for detailed examples on how to use this method.

flush_cache($class = null)

The flush_cache method allows you to (selectively) delete model objects from the object cache.

null

primary_key()

The primary_key method returns an array with the column names that define the tables primary key.

// returns array('id') for default PK's
$pk = MyModel::primary_key();

implode_pk($data)

The implode_pk method allows you convert the value of a (compound) primary key into a string.

null

// with PK defined as both columns "A" and "B", this returns "[1][2]"
$pk = MyModel::implode_pk(array('A' => 1, 'B' => 2));

forge($data = array(), $new = true, $view = null, $cache = true)

The forge method allows you to forge a new model instance.

array()

true

false

$data

null

true

$new

// create a new MyModel model object
$mymodel = MyModel::forge();

get_filtered_properties()

The get_filtered_properties method returns the list of properties returned by a call to

to_array()

// with PK defined as both columns "A" and "B", this returns "[1][2]"
$pk = MyModel::implode_pk(array('A' => 1, 'B' => 2));

Excluding properties can come in handy for properties you don't want to expose, for example if you want to return model data to the caller in a JSON response. See the static model property $_to_array_exclude.

max($key = null)

The max method returns the maximum value of the given column name.

null

// get the last id issued
$last = MyModel::max('id');

This method does not support compound primary keys (as you can only query MAX() on a single column), and will return false if there is no result.

min($key = null)

The min method returns the minimum value of the given column name.

null

// get the first id issued
$last = MyModel::min('id');

This method does not support compound primary keys (as you can only query MAX() on a single column), and will return false if there is no result.

observers($specific = null, $default = null)

The observers method returns a list of all observers defined in the model.

null

null

// get the observers defined in the model
// might return array('Orm\Observer_Typing' => array())
MyModel::observers();

The array value associated with the observer in the result will contain the additional configuration the observer requires.

properties()

The properties method returns an array of all properties (i.e. column names) defined in the model class.

Note: If the model does not define its properties, the ORM will attempt to generate it dynamically, by running a "list all columns" query on the defined table. As this is performance impacting, you should not use this in a production environment, but you could dump the generated array, and use that to populate the model properties array.

Not all database drivers support a "list all columns" method, and will through an exception instead.

property($key, $default = null)

The property method returns the definition of a single model class property.

null

// get the definition of the primary key
MyModel::property('id');

If no properties are defined in the model class, a call to properties() will be made in an attempt to generate them.

query()

The query method returns an ORM query object for the current model class.

// get query object, and get the first record
$query = MyModel::query()->get_one();

See the CRUD documentation for detailed examples on how to use this method.

related_class($relation)

The related_class method returns the name of the ORM model class a relation maps to.

// might return "\Some\Namespace\Model_Child"
MyModel::related_class('children');

relations($specific)

The relations method returns the ORM definition of the given relation.

false

false

/**
 * might return:
 * object(Orm\HasMany)
 *   protected 'name' => string 'children' (length=12)
 *   protected 'model_from' => string 'Model\Parent' (length=19)
 *   protected 'model_to' => string 'Model\Child' (length=23)
 *   protected 'key_from' =>
 *     array (size=1)
 *       0 => string 'id' (length=2)
 *   protected 'key_to' =>
 *     array (size=1)
 *       0 => string 'parent_id' (length=6)
 *   protected 'conditions' =>
 *     array (size=1)
 *       'where' =>
 *         array (size=1)
 *           0 =>
 *             array (size=3)
 *               ...
 *   protected 'singular' => boolean false
 *   protected 'cascade_save' => boolean true
 *   protected 'cascade_delete' => boolean false
 */
MyModel::relations('children');

set_connection($connection)

The connection method allows you to set or override the defined database connection to be used by the model class.

// switch database connection to an Oracle db
MyModel::connection('oracle');

This sets both the read and write connection, unless a seperate write connection was defined.

set_write_connection($connection)

The set_write_connection method allows you to set or override the defined database connection for writes, to be used by the model class.

// switch database connection to the master db
MyModel::connection('master');

This sets the database write connection, which will override the generic connection for write queries.

table()

The table method returns the name of the table associated with the model class. If none is defined in the model, one will be generated.

// might return "prefix_mymodel"
$table = MyModel::table();

The generated table name will be derived from the model name, after the namespaces and any "model_" prefix is stripped, lowercase, and made plural (for english names only). So "\Some\Model_Cat" will map to a table called "cats".

delete($cascade = null, $use_transaction = false)

The delete method deletes the record associated with the current model object from the database.

null

null

true

false

false

// delete the current record
$record->delete();

When the delete() operation fails logically, the method returns false. Otherwise it will return a new model instance, retaining all model data but with the primary keys reset, so a model in new state.

Note also that database exceptions that drivers might throw are not caught in this method !

disable_event($event)

The disable_event method allows you to disable a particular observer event defined in the model on a per-model instance basis.

// disable the after_save observers
$record->disable_event('after_save');

enable_event($event)

The disable_event method allows you to enable a particular observer event that was disabled previously. See disable_event().

// remove a defined block of all after_save observers
$record->enable_event('after_save');

from_array(array $values, $from_cache = false)

The from_array method allows you to populate a model object, and optionally related models objects, from a multi-dimensional array.

false

// create a model object and populate it
$mymodel = MyModel::forge();
$mymodel->from_array($data);

//NB: this is identical to:
$mymodel = MyModel::forge($data);

Be careful with enabling $from_cache. As objects are passed around by reference in PHP, modifying a cached object with the data passed will also modify any variable containing a reference to that object. This can lead to unexpected results and possible data corruption !

get($property, array $conditions = array())

The get method allows you to get a property from the model object. Properties include columns, related objects, EAV values or custom/runtime data stored in the object.

array()

// get all the related child records (from a defined related called 'children')
$mymodel->get('children');

get_diff()

The get_diff method returns an array with all properties that have been modified on the object since it was loaded.

// returns array('id' => 2)
$mymodel = MyModel::find(1);
$mymodel->id = 2;
print_r($mymodel->get_diff());

get_pk_assoc()

The get_pk_assoc method returns an array with a key-value pair for all primary key columns of the current model object.

// returns array('id' => 1)
$mymodel = MyModel::find(1);
print_r($mymodel->get_pk_assoc());

is_changed($property = null, $observe = false)

The is_changed method allows you to test if a model object has been altered since it was loaded.

null

null

false

// you can use get_diff() to check what has changed
if ($mymodel->is_changed()
{
	echo "something has changed in the object !";
}

is_fetched($relation)

The is_fetched method allows you check if related objects have been loaded.

if ( ! $mymodel->is_fetched('children'))
{
	echo "no child records have been loaded yet !";
}

Note that you can't use isset($mymodel->children), as that would access the property, which in turn would trigger a query to autoload the related records (which in turn would make is_fetched() return true) !

is_new()

The is_new method can be used to check if the object has a representation in the database, i.e. if a corresponding record exists.

if ( ! $mymodel->is_new())
{
	echo "no record exists of this object yet";
}

Note that that if your model uses database assigned primary keys (like AUTO_INCREMENT or SERIAL), the objects primary key properties will not have a value at this point. But the absence of such values doesn't say anything about the "new" state, as the model could have primary key values that are manually assigned or generated by observers, in which case it could already have a primary key set, even though it is still classified as "new".

is_parent($all = false)

The is_new method can be used to check if the object has a representation in the database, i.e. if a corresponding record exists.

false

false

true

if ($rels = $mymodel->is_parent(true))
{
	echo "don't delete it, it still has child records in " . impode(",", $rels) . " !";
}

You can use this as a manual foreign key check, either because you don't want to wait for a database driver exception in case of a foreign key violation, or because the database you work with doesn't have any foreign key constraints defined, and you want to make sure you don't want to corrupt the database by leaving child records without a parent.

reset()

The reset method deletes all changes made to the model object, and resets it to the state it was after loading.

If you call reset() on an object in "new" state, it will be completely wiped, like you had just called ClassName::forge().

save($cascade = null, $use_transaction = false)

The save method save the record associated with the current model object to the database, by using an INSERT if the object is in "new" state, or an UPDATE if not.

null

null

true

false

false

// saves the current record
$record->save();

When the save() operation fails logically, the method returns false. Otherwise it will return true.

Note also that database exceptions that drivers might throw are not caught in this method !

to_array($custom = false, $recurse = false, $eav = false)

The to_array method allows you to convert the model object, any relational data loaded, and optionally any custom/runtime data or EAV data, to be return as a multi-dimensional array.

false

false

false

false

// dump the contents of the current object into an array
$array = $record->to_array();

Did I mention not to set the recurse variable to anything other than false?

to_array($custom = false)

The to_array method allows you to convert the model object into a StdClass object with only the data properties.

false

// these are identical
$obj1 = $record->to_object();
$obj2 = (object) $record->to_array();