162 lines
4.4 KiB
ReStructuredText
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();
|
||
|
|
|