dbScribe by ezra-obiwale

This library can create your databases, tables and columns. It can further keep an eye on your models to see if any column needs to be updated. This constant monitoring is based on annotations.

General uses

Below is a table showing the general uses of each file:

File	Uses
Annotation.php	Used to read annotations on models. Only used internally. Ignore.
ArrayCollection.php	An iteratable collection of models with additional methods for navigation.
Connection.php	Extends PDO and accepts PDO options to create a connection to the database.
Mapper.php	Extends Row. Required class to be extended by models for auto-generation and monitoring
Repository.php	Extends Table. Contains additional methods to for easier db access.
Row.php	A typical object representing a row in the database.
Table.php	Represents a table in the database and provides methods for operations.
Util.php	Contains utility methods used in operations and may be used by developers too if necessary.

Basic Usage

Connecting to a database

    $connection = new Connection('mysql:host=localhost;dbname=test_db', 'db_user', 'db_user_password', array(
        'tablePrefix' => 'ds_', // optional - Indicates the prefix to add to table names
        'create' => true, // optional - Indicates whether to create the database if it doesn't exist,
        'autoUpdate' => true, // optional - Indicates whether to auto update database tables from mapper class annotations
    ));

Connecting to a table

Example database table columns

Table ds_user

id	first_name	last_name	full_name	gender
1	Adam	Freeman	Adam Freeman	male
2	Eve	Gerald	Eve Gerald	female
3	Segun	Ajayi	Segun Ajayi	male
4	Shade	Adeyemi	Shade Adeyemi	female
5	Ezra	Obiwale	Ezra Obiwale	male

Method 1

    $tblUser = $connection->table('user'); // Note: Table name without prefix

Method 2

    $tblUser = new Table('user', $connection); // Note: Table name without prefix

CRUD

Creating entries

    // using array
    $row1 = array('first_name' => 'Shade', 'last_name' => 'Adeyemi');

    // using objects
    $row2 = new Row();
    $row2->firstName = 'Segun';
    $row2->lastName = 'Ajayi';

    $tblUser->insert(array($row1, $row2));

Reading entries

    $tblUser->select(); // Returns all rows

    // Select rows where firstname is Segun or Shade
    $criteria = array(
        array('firstName' => 'Segun'),
        array('firstName' => 'Shade'),
    );
    $rows = $tblUser->select($criteria); // Returns object ArrayCollection containing 2 Row objects
    // $tblUser->select($criteria, Table::RETURN_DEFAULT) returns an array of row arrays
    // $tblUser->select($criteria, Table::RETURN_JSON) returns (You got it right) JSON objects

Updating entries

    $row1 = array('first_name' => 'Segun', 'last_name' => 'Ayodeji');
    $row2 = new Row();
    $row2->firstName = 'Shade';
    $row2->lastName = 'Asegun';

    $tblUser->update(array($row1, $row2), 'firstName'); // updates the rows where the `first_name` is as given in the column to update by. Default is `id`

Deleting entries

    $tblUser->delete(array($row1, $row2)); // deletes based on the columns provided in the rows

Advanced Usage

Creating Model Classes

    class User extends DBScribe\Mapper {
        /** @DBS\Int (primary=true,autoIncrement=true,size=2) **/
        public $id;
        /** @DBS\String (size=20) **/
        public $firstName;
        /** @DBS\String (size=20) **/
        public $lastName;
        /** @DBS\String (size=41) **/
        public $fullName;

        public function preSave() {
            // do something before saving to database
            $this->fullName = $this->firstName . ' ' . $this->lastName;

            parent::preSave();
        }

        public function postFetch() {
            parent::postFetch();

            // do something after retrieving from database
        }
    }

    $user = new User();
    $user->firstName = 'Emmanuella';
    $user->lastName = 'Oyewumi';

    $repoUser = new Repository($user, $connection);

    $repoUser->insert(array($user));

    $repoUser->fetchAll(); // same as select() without criteria
    $repoUser->findOneBy('firstName', 'Emmanuella');
    $repoUser->findWhere([$row1, $row2]);
    $repoUser->findById(2);