| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| documentation:rack:reference:models [2019/05/10 17:57] – [Functions] Martijn Luinstra | documentation:rack:reference:models [2023/08/31 23:19] (current) – Martijn Luinstra |
|---|
| ====== Models ====== | ====== Models ====== |
| |
| All models in Rack applications extend from the abstract <php>Model</php> class, defined in ''include/models/Model.class.php''. This class provides a basic implementation for CRUD (create, read, update, and delete) functionality for a single database table. It utalizes the [[http://php.net/manual/en/book.pdo.php|PDO | All models in Rack applications extend from the abstract ''%%Model%%'' class, defined in ''include/models/Model.class.php''. This class provides a basic implementation for CRUD (create, read, update, and delete) functionality for a single database table. It utalizes the [[http://php.net/manual/en/book.pdo.php|PDO |
| ]] prepared statements to construct queries to help preventing SQL injections. | ]] prepared statements to construct queries to help preventing SQL injections. |
| |
| ===== Initialization ===== | ===== Initialization ===== |
| |
| A <php>Model</php> object should never be manually created, as Rack provide a function <php>get_model($name)</php> in ''include/init.php'' that creates an instance of a <php>Model</php> object for you when need it. The following snippet demonstrates its use: | A ''%%Model%%'' object should never be manually created, as Rack provide a function ''%%get_model($name)%%'' in ''include/init.php'' that creates an instance of a ''%%Model%%'' object for you when need it. The following snippet demonstrates its use: |
| |
| <PHP> | <PHP> |
| ===== Basic querying & filtering ===== | ===== Basic querying & filtering ===== |
| |
| Basic queries can be executed using the functions <php>get</php>, <php>create</php>, <php>update</php> and <php>delete</php> or their ''by_id'' counterparts. The <php>create</php> and <php>update</php> functions accept a list with <php>'fieldname'=>'value'</php> pairs that should be used to modify the database. | Basic queries can be executed using the functions ''%%get%%'', ''%%create%%'', ''%%update%%'' and ''%%delete%%'' or their ''by_id'' counterparts. The ''%%create%%'' and ''%%update%%'' functions accept a list with ''%%'fieldname'=>'value'%%'' pairs that should be used to modify the database. |
| |
| The <php>get</php>, <php>update</php> and <php>delete</php> functions also accept an array with filter conditions. These conditions will be appended to the query and multiple conditions will be joined with ''AND''. In this array, filter conditions should be specified as <php>'fieldname__function' => $value</php>. | The ''%%get%%'', ''%%update%%'' and ''%%delete%%'' functions also accept an array with filter conditions. These conditions will be appended to the query and multiple conditions will be joined with ''AND''. In this array, filter conditions should be specified as ''%%'fieldname__function' => $value%%''. |
| |
| Supported comparison functions are: | Supported comparison functions are: |
| * **in**: Tests if the field value is in a list. | * **in**: Tests if the field value is in a list. |
| * **contains**: Tests if the field contains a string value (''LIKE '%value%' ''). Note that ''%'' and ''_'' will not be automatically escaped. | * **contains**: Tests if the field contains a string value (''LIKE '%value%' ''). Note that ''%'' and ''_'' will not be automatically escaped. |
| * **isnull**: Tests if the field value is ''NULL'' (if <php>'field__isnull'=>true</php>) or not ''NULL'' (if <php>'field__isnull'=>false</php>). | * **isnull**: Tests if the field value is ''NULL'' (if ''%%'field__isnull'=>true%%'') or not ''NULL'' (if ''%%'field__isnull'=>false%%''). |
| |
| If the comparison function is omitted (<php>'field' => $value</php>), the default of **eq** is used. | If the comparison function is omitted (''%%'field' => $value%%''), the default of **eq** is used. |
| |
| The <php>get</php> function also supports custom ordering by passing a list of field names. Descending ordering can be achieved by adding a minus in front of the field name. The following example will order first by study and then by birthdate in descending ordering: <php>['study', '-birthdate']</php>. | The ''%%get%%'' function also supports custom ordering by passing a list of field names. Descending ordering can be achieved by adding a minus in front of the field name. The following example will order first by study and then by birthdate in descending ordering: ''%%['study', '-birthdate']%%''. |
| ===== Functions ===== | ===== Functions ===== |
| |
| * <php>__construct($db, $table=null)</php>: The variable <php>$db</php> is a [[http://php.net/manual/en/class.pdo.php|PDO object]]. This value will be set by <php>get_model</php>. <php>$table</php> is the name of the table as it's stored in the database. | * ''%%__construct($db, $table=null)%%'': The variable ''%%$db%%'' is a [[http://php.net/manual/en/class.pdo.php|PDO object]]. This value will be set by ''%%get_model%%''. ''%%$table%%'' is the name of the table as it's stored in the database. |
| * <php>protected query($query, array $input_parameters=[])</php> Expects a query and input parameters that that can be used for [[http://php.net/manual/en/pdo.prepare.php|PDO prepared statements]]. | * ''%%protected query($query, array $input_parameters=[])%%'' Expects a query and input parameters that that can be used for [[http://php.net/manual/en/pdo.prepare.php|PDO prepared statements]]. |
| * <php>protected query_first($query, array $input_parameters=[])</php> Same as <php>query</php>, but returns only the first result. | * ''%%protected query_first($query, array $input_parameters=[])%%'' Same as ''%%query%%'', but returns only the first result. |
| * <php>get(array $conditions=[], array $order=[], $get_first=false)</php> | * ''%%get(array $conditions=[], array $order=[], $get_first=false)%%'' |
| * <php>get_by_id($id, $field='id')</php> | * ''%%get_by_id($id, $field='id')%%'' |
| * <php>create(array $values)</php> Returns inserted ID. | * ''%%create(array $values)%%'' Returns inserted ID. |
| * <php>update(array $data, array $conditions=[])</php> Use with caution! | * ''%%update(array $data, array $conditions=[])%%'' Use with caution! |
| * <php>update_by_id($id, array $data, $field='id')</php> | * ''%%update_by_id($id, array $data, $field='id')%%'' |
| * <php>delete(array $conditions)</php> Use with caution! | * ''%%delete(array $conditions)%%'' Use with caution! |
| * <php>delete_by_id($id, $field='id')</php> | * ''%%delete_by_id($id, $field='id')%%'' |
| |
| |