Fuel Documentation

Orm

Orm is short for Object Relational Mapper which does 2 things: it maps your database table rows to objects and it allows you to esteblish relations between those objects.
It follows closely the Active Record Pattern, but was also influenced by other systems.

CRUD: Create, Read, Update and Delete

Once you've configured your Model it's time to start creating, reading, updating and deleting entries in your database.

Create

// option 1
$new = new Model_Example();
$new->property = 'something';
$new->save();

// option 2, use factory instead of new
$new = Model_Example::factory();

After save() the model has been saved to the database and if you're using an auto_increment primary key it will automaticly be set on the instance after succesfull saving it.

You can also set properties on the model from an array:

$props = array('property' => 'something');

// using "new"
$new = new Model_Example($props);
$new->save();

// option 2, use factory instead of new
$new = Model_Example::factory($props)->save();

Read

Or actually find(). The find method can be used in 3 ways: find a specific id (primary key), find first/last or all entries with conditions, or use method chaining to fetch. All possible selection methods (where, or_where, order_by, etc) can be found at the bottom of the page.

Find by ID

// you know there's an article with ID=2
$entry = Model_Article::find(2);

// ...or when using multiple primary keys
$entry = Model_Article::find(array(2, 5));

In this example it will return either an instance of Model_Article or null when the ID wasn't found.

Find first/last

// find the first entry
$entry = Model_Article::find('first');

// find the last entry added when ordered by date
$entry = Model_Article::find('last', array('order_by' => 'date'));

In this example it will return either an instance of Model_Article or null when the ID wasn't found.

Find all

// find all articles
$entry = Model_Article::find('all');

// find all articles from category 1 order descending by date
$entry = Model_Article::find('last', array(
	'where' => array('category_id', 1),
	'order_by' => array('date' => 'desc')
));

In this example it will always return an array of instances of Model_Article.

Find using method chaining

When you use the find() method without properties it will return an Orm\Query object which you can use, and possibly reuse to find entries.

$query = Model_Article::find()->where('category_id', 1)->order_by('date', 'desc');

// We want to know the total number of articles for pagination
$number_of_articles = $query->count();

// fetch one Article
$newest_article = $query->get_one();

// we re-use but add a return limitation to the previous query to fetch multiple articles
$all_articles = $query->limit(15)->get();

All these methods are equally valid, the find other methods of find actually use the Query object as well but don't return it.

Update

$entry = Model_Article::find(4);
$entry->title = 'My first edit';
$entry->author = 'Total n00b';
$entry->save();

That's it, nothing more to it: Find, change properties and save.

Delete

$entry = Model_Article::find(4);
$entry->delete();

Again nothing more to it: Find and delete.

In the previous example the $entry variable and it's object still exist. The primary keys are however set to null and the object itself is considered a new instance. If you save it after deletion it will be re-entered into the database and be given a new primary key when auto_increment is switched on.

All selection methods when using find

Method Params Examples
where string $column, [string $operator,] mixed $value
// Single where
Model_Article::find()->where('id', 4);
Model_Article::find('all', array('where' => array('category_id', 5)));

// Multiple where usage examples
Model_Article::find()->where('id', 4)->where('category_id', '>', 1);
Model_Article::find()->where(array('id' => 4, 'category_id' => 6));
Model_Article::find('all', array('where' => array(array('category_id', 5), array('publish', '<', time()))));
where string $column, [string $operator,] mixed $value Same as where()

More to be written.