Models

Getting data from objects

Once you’ve got a set of records (objects) back from a query, you can access properties on those objects (the values stored in the columns in its corresponding table) in two ways: by using the get method, or simply by accessing the property on the object directly:

<?php
$person = ORM::for_table('person')->find_one(5);

// The following two forms are equivalent
$name = $person->get('name');
$name = $person->name;

You can also get the all the data wrapped by an ORM instance using the as_array method. This will return an associative array mapping column names (keys) to their values.

The as_array method takes column names as optional arguments. If one or more of these arguments is supplied, only matching column names will be returned.

<?php
$person = ORM::for_table('person')->create();

$person->first_name = 'Fred';
$person->surname = 'Bloggs';
$person->age = 50;

// Returns array('first_name' => 'Fred', 'surname' => 'Bloggs', 'age' => 50)
$data = $person->as_array();

// Returns array('first_name' => 'Fred', 'age' => 50)
$data = $person->as_array('first_name', 'age');

Updating records

To update the database, change one or more of the properties of the object, then call the save method to commit the changes to the database. Again, you can change the values of the object’s properties either by using the set method or by setting the value of the property directly. By using the set method it is also possible to update multiple properties at once, by passing in an associative array:

<?php
$person = ORM::for_table('person')->find_one(5);

// The following two forms are equivalent
$person->set('name', 'Bob Smith');
$person->age = 20;

// This is equivalent to the above two assignments
$person->set(array(
    'name' => 'Bob Smith',
    'age'  => 20
));

// Syncronise the object with the database
$person->save();

Properties containing expressions

It is possible to set properties on the model that contain database expressions using the set_expr method.

<?php
$person = ORM::for_table('person')->find_one(5);
$person->set('name', 'Bob Smith');
$person->age = 20;
$person->set_expr('updated', 'NOW()');
$person->save();

The updated column’s value will be inserted into query in its raw form therefore allowing the database to execute any functions referenced - such as NOW() in this case.

Creating new records

To add a new record, you need to first create an “empty” object instance. You then set values on the object as normal, and save it.

<?php
$person = ORM::for_table('person')->create();

$person->name = 'Joe Bloggs';
$person->age = 40;

$person->save();

After the object has been saved, you can call its id() method to find the autogenerated primary key value that the database assigned to it.

Properties containing expressions

It is possible to set properties on the model that contain database expressions using the set_expr method.

<?php
$person = ORM::for_table('person')->create();
$person->set('name', 'Bob Smith');
$person->age = 20;
$person->set_expr('added', 'NOW()');
$person->save();

The added column’s value will be inserted into query in its raw form therefore allowing the database to execute any functions referenced - such as NOW() in this case.

Checking whether a property has been modified

To check whether a property has been changed since the object was created (or last saved), call the is_dirty method:

<?php
$name_has_changed = $person->is_dirty('name'); // Returns true or false

Deleting records

To delete an object from the database, simply call its delete method.

<?php
$person = ORM::for_table('person')->find_one(5);
$person->delete();

To delete more than one object from the database, build a query:

<?php
$person = ORM::for_table('person')
    ->where_equal('zipcode', 55555)
    ->delete_many();

Model classes

You can also create a model class for each entity in your application. For example, if you are building an application that requires users, you should create a User class. Your model classes should extend the base Model class:

<?php
class User extends Model {
}

The base class takes care of creating instances of your model classes, and populating them with data from the database. You can then add behaviour to this class in the form of public methods which implement your application logic. This combination of data and behaviour is the essence of the Active Record pattern.

IDE Auto-complete

As the model does not require you to specify a method/function per database column it can be difficult to know what properties are available on a particular model. Due to the magic nature of PHP’s __get() method it is impossible for an IDE to give you autocomplete hints as well.

To work around this you can use PHPDoc comment blocks to list the properties of the model. These properties should mirror the names of your database tables columns.

<?php
/**
 * @property int $id
 * @property string $first_name
 * @property string $last_name
 * @property string $email
 */
class User extends Model {
}

For more information please see the PHPDoc manual @property documentation.

Database tables

Your User class should have a corresponding user table in your database to store its data.

By default, models assume your class names are in CapWords style, and your table names are in lowercase_with_underscores style. It will convert between the two automatically. For example, if your class is called CarTyre, the model will look for a table named car_tyre.

If you are using namespaces then they will be converted to a table name in a similar way. For example \Models\CarTyre would be converted to models_car_tyre. Note here that backslashes are replaced with underscores in addition to the CapWords replacement discussed in the previous paragraph.

To disregard namespace information when calculating the table name, set Model::$short_table_names = true;. Optionally this may be set or overridden at class level with the public static property $_table_use_short_name. The

$_table_use_short_name takes precedence over Model::$short_table_names unless $_table_use_short_name is null (default).

Either setting results in \Models\CarTyre being converted to car_tyre.

<?php
class User extends Model {
    public static $_table_use_short_name = true;
}

To override the default naming behaviour and directly specify a table name, add a public static property to your class called $_table:

<?php
class User extends Model {
    public static $_table = 'my_user_table';
}

Auto prefixing

To save having type out model class name prefixes whenever code utilises Model::for_table() it is possible to specify a prefix that will be prepended onto the class name.

See the Configuration documentation for more details.

ID column

Models require that your database tables have a unique primary key column. By default, the model will use a column called id. To override this default behaviour, add a public static property to your class called $_id_column:

<?php
class User extends Model {
    public static $_id_column = 'my_id_column';
}

Note - The Model class has its own default ID column name mechanism, and does not respect column names specified in ORM’s configuration.