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 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
    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	condition
username	whereUsername
id_user	whereIdUser
aaa_bb_c_ddd	aaaBbCDdd

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