CBL ActiveRecord

Introduction

CBL ActiveRecord is an O/R mapping library for PHP5.x. Active Record is an object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data. Using this library, it becomes very easy to access the database.

License

GNU Library or Lesser General Public License (LGPL2.1orlater)

Download

Current version of CBL ActiveRecord is available at 31tools.com site.

Prerequisites

PHP5.x	CBL ActiveRecord is currently developed and tested for PHP5.1
PDO	PDO (PHP Database Objects) - a native database abstraction layer for PHP5, distributed in the form of PECL

How to Use

Naming Rules

The name of the class derived from CBL_ActiveRecord class corresponds to the table name in the database. For example, if the table name is 'user', then the class name must be 'User'.

Examples

Connect to database

$pdo = new PDO( 'mysql:dbname=todo;host=localhost', 'root', '' );
CBL_ActiveRecord::setDefaultPDO( $pdo );

Class definition

require_once 'cbl_activerecord.php';

class User extends CBL_ActiveRecord
{
}

class ToDo extends CBL_ActiveRecord
{
}

Insert record

case: don't specify id

$todo = new ToDo();
$todo->name = 'Planning';   // set property
$todo->save();

case: specify id

$todo = new ToDo();
$todo->id = 1;              // set id
$todo->name = 'Planning';   // set property
$todo->insert();

case: specify id, which is string data type

$todo = new ToDo();
$todo->id = '57f3d093';     // set id
$todo->name = 'Planning';   // set property
$todo->insert();

case: create unique id, which is string data type

$todo = new ToDo();
$todo->uniqid();            // create and set id (default id length is 8 characters)
$todo->name = 'Planning';   // set property
$todo->insert();

case: create unique id with 16 characters

$todo = new ToDo();
$todo->uniqid(16);          // create and set id (max id length is 32 characters)
$todo->name = 'Planning';   // set property
$todo->insert();

case: create unique id, but don't set it to 'id' column

$todo = new ToDo();
$id = $todo->uniqid(8, FALSE);

Get one record

case: using find() method

$todo = new ToDo();
$todo = $todo->find( $id );  // get record by id

case: using constructor

try {
    $todo = new ToDo( $id );    // get record by id
} catch ( Exception $e ) {
    echo $e->getMessage();      // throw exception, if not found.
}

case: specify columns

$todo = new ToDo();
$todo = $todo->find( $id, array( 'columns'=>'id, name' ) );

Update record

case: executing SELECT before UPDATE in SQL

$todo = new ToDo( $id );    // get record by id
$todo->name = 'Scheduling'; // modify property
$todo->save();              // or $todo->update();

case: without executing SELECT in SQL

$todo = new ToDo();
$todo->id = $id;            // set record id directly
$todo->name = 'Scheduling'; // modify property
$todo->save();              // or $todo->update();

case: update several records at once

$todo = new ToDo();
$id_list = array(1, 2, 5);  // prepare id list
$todo->finish = 1;          // modify property
$todo->update($id_list);    // update() with $id_list parameter

Delete record

case: executing SELECT before DELETE in SQL

$todo = new Todo( $id );    // get record by id
$todo->delete();

case: without executing SELECT in SQL

$todo = new ToDo();
$todo->delete( $id );

Get record list

case: all records

$todo = new ToDo();
$todo_list = $todo->find_all();
foreach( $todo_list as $id=>$todo_item )
{
    echo $todo_item->name;
}

case: search

$user_id = intval( $user_id);
$todo = new ToDo();
$todo_list = $todo->find_all( array( 'conditions'=>"user_id={$user_id}" ) );

case: order

$todo = new ToDo();
$todo_list = $todo->find_all( array( 'order'=>'name' ) );

case: limit

$todo = new ToDo();
$todo_list = $todo->find_all( array( 'limit'=>20 ) );

case: offset

$todo = new ToDo();
$todo_list = $todo->find_all( array( 'offset'=>5, 'limit'=>20 ) );

case: specify columns

$todo = new ToDo();
$todo_list = $todo->find_all( array( 'columns'=>'id, name' ) );

Get record count

case: count all records

$todo = new ToDo();
echo $todo->count();

case: count records under a condition

$todo = new ToDo();
echo $todo->count(array('conditions'=>'finish=1'));

Relation

case: get one record

$user = new User( $user_id );       // get user record
$todo = $user->todo->find( $id );   // get todo of todo.user_id={$user_id}

case: get record list

$user = new User( $user_id );           // get user record
$todo_list = $user->todo->find_all();   // get todo list of todo.user_id={$user_id}

case: inner join (SELECT todo.*, user.name FROM todo INNER JOIN user ON todo.user_id=user.id)

$todo = new ToDo();
$todo_list = $todo->find_all(
    array('columns'=>'todo.*, user.name'),
    array('table'=>'user', 'lhs'=>'user_id', 'rhs'=>'id'));

Use root object (CBL_ActiveRoot)

$root = new CBL_ActiveRoot();
$todo = $root->todo->find( $id );
$todo_list = $root->todo->find_all( $id );