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 establish relations between those objects.
It follows the Active Record Pattern closely, but was also influenced by other systems.

Introduction

Unlike many other ActiveRecord implementations, ours is small, fast and dead simple to use. It attempts to make creating, updating and deleting items from your database as easy as possible. It does this by doing all the hard work for you.

Installation

The Orm package is included in the Fuel download. All you need to do is enable it in your config.

'always_load' => array(
	'packages' => array(
		'orm',
	),
),

Troubleshooting

Some common problems and frequent questions.

My relations/foreign keys aren't being saved (1)

This happens most often when you're using the wrong type of relationship. Especially Has-one and Belongs-to tend to get mixed up. Reread the examples in the docs to make sure you're using the correct relation types and check if everything is configured correctly.

I can't relate objects (2)

Make sure your model is extending Orm\Model and not Model_Crud.

I get an exception that my related model in a package/module can't be found

Make sure the package or module is loaded by Fuel, otherwise the Autoloader won't be able to find the class.
And when configuring the related model "model_to" make sure you configure the full classname, this includes the namespace even if you're in that namespace. Classnames in strings are always taken from global context, no matter the current namespace context.

I get an Orm\FrozenObject exception

Objects can't be edited while being saved to the database, that prevents circular saving and resaving already saved objects. This shouldn't happen during normal usage and is most often caused by faulty configuration of relations.
Sometimes this can be caused by a bug, especially when you're not using a stable release.

I have defined a limit and offset, but the results are not correct

The ORM always makes sure that query results are consistent. If you run a query that contains related models, a subquery will be generated to make sure the entire related resultset is fetched. Even if this means more records then the limit you have set will be fetched. This is because once you start manipulating incomplete resultsets, very bad things might happen to your related models.

If you are absolutely sure you are not going to manipulate the results, for example because you need them for pagination only, you can use rows_limit() and rows_offset() instead, which will force them on the entire query.