j4mie/idiorm

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:

.. code-block:: php

    <?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.

.. code-block:: php

    <?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:

.. code-block:: php

    <?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.

.. code-block:: php

    <?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.

.. code-block:: php

    <?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.

.. code-block:: php

    <?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:

.. code-block:: php

    <?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.

.. code-block:: php

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

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

.. code-block:: php

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