Working with ORM

Now that your ORM models are defined and your relationships are in place, you are ready to begin accessing your data via ORM objects. Let's see how easy it is to work with your data using ORM.

Once your ORM models are defined, you can load ORM models using standard object instantiation or via the static factory method. Both work exactly the same, but the factory method is chainable, so it is preferred. You can optionally pass a primary key to the constructor or factory to create a ORM object associated with one specific record. Note: In order to access data in related tables, you need to define relationships in your model.

// create a new ORM object
$user = new User_Model();
 
// Create a new ORM object for the primary key of 1
$user = new User_Model(1);
 
// Using the factory method
$user = ORM::factory('user');
 
// Using the factory method with optional primary key
$user = ORM::factory('user', 1);

Once your ORM models are loaded, data is accessible using standard object property notation ($object→property). In a one-to-many relationship, where many rows from the child model are associated with the parent model, data within the child model is accessible via a foreach loop (the child model is actually an ORM_Iterator object, not an array).

Here is an example that shows how to access ORM data from the user model (part of the Kohana Auth module).

// accessing data for the user with the primary key of 1
$user = ORM::factory('user', 1);
echo $user->name;

If you have two tables in a one_to_many relationship: schools and students (a school has many students) and want to list information about each student in the school you need to use a foreach loop. Note: As you loop through the objects using foreach, only one object exists at any given point. Each time the loop continues, the old object is replaced by a new object. This is done to keep memory usage low when working with many objects at once.

// in your School_Model
protected $has_many = array('students');

// in your Student_Model
protected $belongs_to = array('school');

// in your controller
 
// create a new ORM object for school id = 1
$school = new School_Model(1);
 
// iterate through all of the students associated with the school and output their name
foreach ($school->students as $student)
{
    echo $student->name.'<br/>';
}

Most query builder methods can be used within ORM and are chainable, giving you a great deal of flexibility and control over the data returned by your ORM models. The only query builder methods that can not be used within ORM models are:

• query - Use ORM's find and find_all methods for select queries, and its save and delete methods for inserts, updates and deletes.
• get - Use ORM's find and find_all methods instead.
• insert - Use ORM's save method instead
• update - Use ORM's save method instead
• delete - Use ORM's delete and delete_all methods instead

Be sure to review the Database library and query builder before using ORM.

// query builder methods with chaining
$object = ORM::factory('model')->where('field', 'some_value')->orwhere('field', 'another_value')->find();
 
// retrieve a sorted list of books of the first 20 books associated with author (where id = 1)
$author = ORM::factory('author', 1);
$sorted_books = $author->orderby('date','desc')->limit(20)->books;

Once your ORM model is loaded it's easy to make updates. Just remember to call save() when you are done with all of your changes.

$user = ORM::factory('user', 1);
$user->name = 'New Name';
$user->email = '[email protected]';
$user->save();

When creating a database record that has related columns in a one-to-many relationship, you need to obtain the last insert id of the parent object to properly add an associated child row. The save() method sets the primary key of the object (usually id) to the last_insert_id.

The following example shows how to create a new Page record and then create a related Keyword record for that Page.

// models/page.php
class Page_Model extends ORM {
    protected $has_many = array('keywords');
}
 
// models/keyword.php
class Keyword_Model extends ORM {
    protected $belongs_to = array('page');
}
 
// in your controller
 
// create a new page record
$page = ORM::factory('page');
$page->title = "Test Page";
$page->content = "This is a test page";
$page->save();
 
// create a new keyword record for the page that was just created
$keyword = ORM::factory('keyword');
$keyword->name = "testing";
$keyword->page_id = $page->id;  // $page->id has the last insert id from the above save
$keyword->save();

Adding and removing data from many-to-many pivot tables is done using the add() and remove() methods. However, you can also use array(1,2,3) syntax to make multiple changes (adds, deletes) to related data in a pivot table for the current parent model. This allows you to pass the results of a multi-selection HTML form element (e.g. checkbox) as an array directly to your ORM model and ORM will automatically determine the appropriate values to add and remove from your pivot table upon saving. No additional code is required!

For example, if you have a form that allows users to update categories for a blog post via checkboxes, you can use the following syntax to have ORM manage both adds and updates:

$post = ORM::factory('blog_post', 1);
 
$post->categories = array(1,2); // array should contain id's
$post->save(); // save() must always be called last
 
echo '<h4>Categories of '.$post->title.'</h4>', '<ul>';
foreach ($post->categories as $category)
{
    echo '<li>', $category->id, ' ', $author->name, '</li>';
}
echo '</ul>';

Continue to the next section: Examples >>