ttrss/vendor/j4mie/idiorm/docs/models.rst

162 lines
4.4 KiB
ReStructuredText

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();