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

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
    require_once __ROOT__.'/autoloader.php';

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

[2] SELECT queries

(2.1) Single Table

<?php

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

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

(2.3) Select

<?php

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

(2.4) Order by

<?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

    // 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 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

    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

SELECT *
FROM user_table

<?php

$rows = Table::get('user_table')
	->select('*')
	->fetch();

2. Normal select

SELECT id_user, username, mail
FROM user_table

<?php

$rows = Table::get('user_table')
	->select('id_user')
	->select('username')
	->select('mail')
	->fetch();

3. Select distinct

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

<?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

SELECT	id_post,
	count(nb_view)
FROM posts

<?php

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

5. Select as (alias)

SELECT	id_post,
	count(nb_view) as NB_COUNT
FROM posts

<?php

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

6. Single PRIMARY KEY condition

SELECT *
FROM posts
WHERE id_post = 10

<?php

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

7. Composite PRIMARY KEY condition

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

<?php

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

8. Condition types

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

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