From ce9bee052c165c83f6022719ccc64cade6c441ee Mon Sep 17 00:00:00 2001
From: xdrm-brackets <doowap31@gmail.com>
Date: Sat, 9 Sep 2017 18:46:41 +0200
Subject: [PATCH] update orm:0.8-2 notice

---
 README.md           |   3 +
 notice/orm/0.8-2.md | 156 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 notice/orm/0.8-2.md

diff --git a/README.md b/README.md
index f25e9ec..952c446 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,9 @@ xdrm-framework is based on `all in config` so you will have this structure :
 #### [3.2] error - error system
 #### [3.3] database - database wrapper and repository manager
 #### [3.4] orm - sql orm
+
+> version 0.8-2 - [documentation](/notice/orm/0.8-2.md)
+
 #### [3.5] router - apache2 router
 #### [3.6] lightdb - fast key-value storage
 #### [3.7] db-schema - Json to Mysql
diff --git a/notice/orm/0.8-2.md b/notice/orm/0.8-2.md
new file mode 100644
index 0000000..6b93496
--- /dev/null
+++ b/notice/orm/0.8-2.md
@@ -0,0 +1,156 @@
+```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();
+```
\ No newline at end of file