120 lines
3.9 KiB
ReStructuredText
120 lines
3.9 KiB
ReStructuredText
Models
|
||
======
|
||
|
||
Model classes
|
||
~~~~~~~~~~~~~
|
||
|
||
You should 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 {
|
||
}
|
||
|
||
Paris 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 Paris 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()`_ 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, Paris assumes 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``, Paris 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
|
||
~~~~~~~~~
|
||
|
||
Paris requires that your database tables have a unique primary key
|
||
column. By default, Paris 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** - Paris has its *own* default ID column name mechanism, and
|
||
does not respect column names specified in Idiorm’s configuration.
|
||
|
||
.. _Active Record pattern: http://martinfowler.com/eaaCatalog/activeRecord.html
|
||
.. ___get: https://secure.php.net/manual/en/language.oop5.overloading.php#object.get
|
||
.. _PHPDoc manual @property: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/property.html |