xdrm-framework/notice/orm/0.8-2.md

```yaml
module: orm
version: 0.8-2
requires:
  - database:  2.0
```

Overview
----

> ### 1. Introduction
The `orm` package allows you to simplify SQL requests through php objects. You will never have to use SQL code anymore.


> ### 2. Setup

In order for the orm to work, you will ne to configure the `database` driver according to your database credentials and information.

> ### 3. Features

Query types

- Manage `SELECT` queries
- Manage `UPDATE` queries
- Manage `INSERT INTO` queries
- Manage `DELETE` queries

Specification

- Fetches the whole schema specification (foreign keys, primary keys, etc)
- Manage `SELECT *`
- Manage composite `PRIMARY KEY`
- Manage `WHERE` conditions (_=_, _<>_, _<_, _>_, _>=_, _<=_, _LIKE_, _IN_)
- Manage aggregation functions (_AVG()_, _SUM()_, _MAX()_, _MIN()_, _COUNT()_, *GROUP_CONCAT()*)
- Manage `ORDER BY` ordering
- Manage `SELECT DISTINCT` specification (_ASC_, _DESC_)
- Inserting multiple rows at once
- Automatically select the **PRIMARY KEY(S)**
- Manage joined tables
- Manage `fetch` and `fetchAll`
- Manage `NULL` keyword
- Manage booleans
- Manage inserting the `DEFAULT` value
- Manage format beautifying (numbers as numbers, same for booleans, null)




Usage
----

> ### (1) Loader

```php
<?php
    require_once __ROOT__.'/autoloader.php';

    use \orm\core\Table;
    use \orm\core\Rows;
```

> ### (2) SELECT queries

> #### (2.1) Single Table

```php
<?php

    // All matching rows
    Table::get('table_name')
        ->select('*')
        ->fetch();

    // First row only
    Table::get('table_name')
        ->select('*')
        ->unique()
        ->fetch();

```

> #### (2.3) Select

```php
<?php

    Table::get('table_name')
        ->select('field_1')
        ->select('field_2')
        /// ...
        ->select('field_N')
        ->fetch();
```

> #### (2.4) Order by

```php
<?php

    // Ascending order of the field `field_name`
    Table::get('table_name')
        ->orderby('field_name', Rows::ORDER_ASC)
        ->fetch();

    // Descending order of the field `field_name`
    Table::get('table_name')
        ->orderby('field_name', Rows::ORDER_DESC)
        ->fetch();

```

> #### (2.5) WhereId

It will match the corresponding `PRIMARY KEY` of the table, if it is a composed key (multiple fields) instead of giving an argument, give an array for each in the order displayed in _phpmyadmin_ or you mysql viewer.

```php
<?php

    // PRIMARY KEY => `id_user`
    Table::get('user')
        ->select('*')                   // select all fields
        ->whereId(12)                   // if id_user is equal to 12
        ->fetch();                      // fetch matching rows

    // PRIMARY KEYS => `username` + `mail`
    Table::get('user')
        ->select('*')                   // select all fields
        ->whereId([12, 'sample@mail.com'])
                                        // if  `id_user` is equal to 12
                                        // AND `mail`    is equal to 'sample@mail.com'
        ->fetch();                      // fetch matching rows
```

The available condition operators are listed in the [constants](todo) section.
Note: `Rows::COND_EQUAL` is set by default if missing

> #### (2.6) Where clause

The where clause uses one of php's magic functions (\_\_call). So the name of the method you call will contain the field of the condition. But you must use the correct case, removing '\_' and setting the next character to upper case. The rest will be forced to lower case.

You can refer to the following examples:


|Field|condition|
|---|---|
|username|`whereUsername`|
|id_user|`whereIdUser`|
|aaa_bb_c_ddd|`aaaBbCDdd`|

```php
<?php

    Table::get('user')
        ->select('*')
        ->whereUsername('someusername') // if username is equal to 'someusername'
        ->whereMail(['somemail', Rows::COND_EQUAL]) // same as previous line (explicit here)
        ->fetch();
```