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

Model classes
~~~~~~~~~~~~~

You can also create a model class for each entity in your application. For
example, if you are building an application that requires users, you
should create a ``User`` class. Your model classes should extend the
base ``Model`` class:

.. code-block:: php

    <?php
    class User extends Model {
    }

The base class takes care of creating instances of your model classes, and
populating them with *data* from the database. You can then add
*behaviour* to this class in the form of public methods which implement
your application logic. This combination of data and behaviour is the
essence of the `Active Record pattern`_.

IDE Auto-complete
^^^^^^^^^^^^^^^^^

As the model does not require you to specify a method/function per database column
it can be difficult to know what properties are available on a particular model.
Due to the magic nature of PHP's `__get() <https://www.php.net/manual/en/language.oop5.overloading.php#object.get>`_ method it is impossible for an IDE
to give you autocomplete hints as well.

To work around this you can use PHPDoc comment blocks to list the properties of
the model. These properties should mirror the names of your database tables
columns.

.. code-block:: php

    <?php
    /**
     * @property int $id
     * @property string $first_name
     * @property string $last_name
     * @property string $email
     */
    class User extends Model {
    }

For more information please see the `PHPDoc manual @property`_ documentation.

Database tables
~~~~~~~~~~~~~~~

Your ``User`` class should have a corresponding ``user`` table in your
database to store its data.

By default, models assume your class names are in *CapWords* style, and
your table names are in *lowercase\_with\_underscores* style. It will
convert between the two automatically. For example, if your class is
called ``CarTyre``, the model will look for a table named ``car_tyre``.

If you are using namespaces then they will be converted to a table name
in a similar way. For example ``\Models\CarTyre`` would be converted to
``models_car_tyre``. Note here that backslashes are replaced with underscores
in addition to the *CapWords* replacement discussed in the previous paragraph.

To disregard namespace information when calculating the table name, set
``Model::$short_table_names = true;``. Optionally this may be set or overridden at
class level with the **public static** property ``$_table_use_short_name``. The

``$_table_use_short_name`` takes precedence over ``Model::$short_table_names``
unless ``$_table_use_short_name`` is ``null`` (default).

Either setting results in ``\Models\CarTyre`` being converted to ``car_tyre``.

.. code-block:: php

    <?php
    class User extends Model {
        public static $_table_use_short_name = true;
    }

To override the default naming behaviour and directly specify a table name,
add a **public static** property to your class called ``$_table``:

.. code-block:: php

    <?php
    class User extends Model {
        public static $_table = 'my_user_table';
    }

Auto prefixing
^^^^^^^^^^^^^^

To save having type out model class name prefixes whenever code utilises ``Model::for_table()``
it is possible to specify a prefix that will be prepended onto the class name.

See the :doc:`configuration` documentation for more details.

ID column
~~~~~~~~~

Models require that your database tables have a unique primary key
column. By default, the model will use a column called ``id``. To override
this default behaviour, add a **public static** property to your class
called ``$_id_column``:

.. code-block:: php

    <?php
    class User extends Model {
        public static $_id_column = 'my_id_column';
    }

**Note** - The Model class has its *own* default ID column name mechanism, and
does not respect column names specified in ORM’s configuration.

.. _Active Record pattern: http://martinfowler.com/eaaCatalog/activeRecord.html
.. _PHPDoc manual @property: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/property.html