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 chain-methods. You will never have to use SQL code anymore.


> ### 2. Setup

In order for the orm to work, you will have 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|Method name|
|---|---|
|username|`whereUsername`|
|id_user|`whereIdUser`|
|aaa_bb_c_ddd|`whereAaaBbCDdd`|

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

Request examples
----

> ##### `1. Select all`

```sql
SELECT *
FROM user_table
```

```php
<?php

$rows = Table::get('user_table')
	->select('*')
	->fetch();
```
> ##### `2. Normal select`

```sql
SELECT id_user, username, mail
FROM user_table
```

```php
<?php

$rows = Table::get('user_table')
	->select('id_user')
	->select('username')
	->select('mail')
	->fetch();
```
> ##### `3. Select distinct`

```sql
SELECT	DISTINCT id_user,  -- distinct
				 username,
				 mail
FROM user_table
```

```php
<?php

$rows = Table::get('user_table')
	->select('id_user', null, true) // 2nd arg is for aggregation functions
	->select('username')
	->select('mail')
	->fetch();
```


> ##### `4. Aggregation functions`

```sql
SELECT	id_post,
	count(nb_view)
FROM posts
```

```php
<?php

$rows = Table::get('posts')
	->select('id_post')
	->select('nb_view', Rows::SEL_COUNT)
	->fetch();
```


> ##### `5. Select as (alias)`

```sql
SELECT	id_post,
	count(nb_view) as NB_COUNT
FROM posts
```

```php
<?php

$rows = Table::get('posts')
	->select('id_post')
	->select('nb_view', Rows::SEL_COUNT, null, 'NB_COUNT')
	->fetch();
```


> ##### `6. Single PRIMARY KEY condition`

```sql
SELECT *
FROM posts
WHERE id_post = 10
```

```php
<?php

$rows = Table::get('posts')
	->select('*')
	->whereId(10)
	->fetch();
```

> ##### `7. Composite PRIMARY KEY condition`

```sql
SELECT *
FROM posts
WHERE id_post = 10 -- primary key (field 1)
AND   id_user = 11 -- primary key (field 2)
```

```php
<?php

$rows = Table::get('posts')
	->select('*')
	->whereId([10, 11])
	->fetch();
```


> ##### `8. Condition types`

```sql
SELECT *
FROM complex_table
WHERE a = 10
AND   b <> 11
AND   c < 12
AND   d > 13
AND   e <= 14
AND   f >= 15
AND   g LIKE '%16%'
AND   h IN (2, 4, 6, 8)
```

```php
<?php

$rows = Table::get('complex_table')
	->select('*')
	->whereA( 10                               )
	->whereB( [11,           Rows::COND_NOTEQ] )
	->whereC( [12,           Rows::COND_INF]   )
	->whereD( [13,           Rows::COND_SUP]   )
	->whereE( [14,           Rows::COND_INFEQ] )
	->whereF( [15,           Rows::COND_SUPEQ] )
	->whereG( ['%16%',       Rows::COND_LIKE]  )
	->whereH( [[2, 4, 6, 8], Rows::COND_IN]    )
	->fetch();
```