windwalker/record

Windwalker Record package

Windwalker Record

Windwalker Record is a simple ActiveRecord to operate database row., _(*1)

Installation via Composer

Add this to the require block in your composer.json., _(*2)

``` json { "require": { "windwalker/record": "~3.0" } }, <sub>(*3)</sub>

## Use Record

New a instance.

``` php
use Windwalker\Record\Record;

// Record object for users table
$user = new Record('users');

Or create a class:, <sub>(*4)</sub>

``` php use Windwalker\Record\Record;, <sub>(*5)</sub>

class UserRecord extends Record { protected $table = 'users';, <sub>(*6)</sub>

protected $keys = 'id';

}, <sub>(*7)</sub>

$user = new UserRecord;, <sub>(*8)</sub>

### Load A Record

``` php
$user->load(25); // Load by primary key

$user->load(array('alias' => $alias)); // Load by field name.

Check row exists, <sub>(*9)</sub>

``` php try { $record->load(25); } catch (NoResultException $e) { // Handle error }, <sub>(*10)</sub>

### Bind Data

``` php
$data = array(
    'name'     => 'Sakura',
    'username' => 'sakura',
    'alias'    => 'sakura',
    'password' => '1234',
    'desc'     => 'foo bar.'
);

$user->bind($data);

$user->name; // Sakura

If we have a table with only 3 columns:, <sub>(*11)</sub>

The fields which not in this table will be remove after binding data., <sub>(*12)</sub>

``` php $user->alias; // null, <sub>(*13)</sub>

That makes our fields in Record will always same as DB table.

### Store

#### Create A New Row

If primary not exists, Record will create a new row in table.

``` php
$data = array(
    'name'     => 'Sakura',
    'username' => 'sakura',
    'password' => '1234'
);

$user->bind($data);

$user->store();

echo $user->id; // Auto generated id

Update A Existing Row

If primary key exists, Record will update it., <sub>(*14)</sub>

``` php $data = array( 'id' => 30, 'name' => 'Sakura', 'username' => 'sakura', 'password' => '1234' );, <sub>(*15)</sub>

$user->bind($data);, <sub>(*16)</sub>

$user->store();, <sub>(*17)</sub>

### Validate

Check method help you validate data.

``` php
class UserRecord extends Record
{
    // ...

    public function validate()
    {
        if (!$this['name'])
        {
            throw new InvalidArgumentException('Name empty.');
        }

        return true;
    }
}

Then we call validate() before store()., <sub>(*18)</sub>

``` php $user->bind($data) ->validate() ->store();, <sub>(*19)</sub>

### Delete

``` php
$user->load(30);
$result = $user->delete(); // boolean

// OR delete by conditions

$result = $user->delete(30); // boolean
$result = $user->delete(array('username' => $username)); // boolean

Mutator and Accessor

Mutator and accessor is a setter and getter to do some extra modification when you access value via magic methods., <sub>(*20)</sub>

This is an example of mutator:, <sub>(*21)</sub>

``` php class ArticleRecord extends Record { protected function setCreatedDateValue($value) { if ($value instanceof \DateTime) { $value = $value->format('Y-m-d H:i:s'); }, <sub>(*22)</sub>

    $this->data['created_date'] = $value;
}

}, <sub>(*23)</sub>

Use camel-case style to define a method, then when you access the `created_date` field, this method will
 be auto executed.

``` php
$articleRecord->created_date = new \DateTime('now');

echo $articleRecord->created_date; // 2016-03-02 12:30:29

And an example of accessor:, <sub>(*24)</sub>

``` php class ArticleRecord extends Record { protected function getCreatedDateValue($value) { return new \DateTime($value); } }, <sub>(*25)</sub>

And now you can get `DateTime` object back:

``` php
echo $articleRecord->created_date->format('Y-m-d H:i:s'); // 2016-03-02 12:30:29

Casts

Add casts to auto convert value type after read from DB:, <sub>(*26)</sub>

<?
class SakuraRecord extends Record
{
    protected $casts = [
        'id' => 'int',
        'price' => 'string',
        'created' => 'datetime',
        'modified' => 'timestamp',
        'images' => 'object', // or array will be json decoded
        'params' => \Windwalker\Structure\Structure::class,
        'other' => ['SomeClass', 'handle'] // Use callback
    ];
}

$sakuraRecord->load(3);

$sakuraRecord->id; // 3
$sakuraRecord->price; // '1200.00'
$sakuraRecord->created->format('Y/d/m'); // Auto convert to DateTime object
$sakuraRecord->modified; // 1497067876
$sakuraRecord->images[0]->url; // Store json in DB, can will auto decode to object.
$sakuraRecord->params->get('foo.bar'); // Use class name to store value to object

Supports casts:, <sub>(*27)</sub>

• int | integer
• real | float | double
• string
• bool | boolean
• object
• array | json
• date | datetime
• timestamp
• (Class name)
• (Callback array)

NestedRecord

NestedRecord is a tool help us handle Nested Set Model., <sub>(*28)</sub>

Create Table

Name: categories, <sub>(*29)</sub>

Initialise

Every nested set should have a root node., <sub>(*30)</sub>

``` php $cat = new NestedRecord('categories');, <sub>(*31)</sub>

$cat->createRoot();, <sub>(*32)</sub>

NOTE: The root node id is `1`.

### Create Node

Set as first child of ROOT

``` php
$cat->bind($data)
    ->setLocation(1, NestedRecord::LOCATION_FIRST_CHILD)
    ->store();

Now we will have a new node and it id is 2. Create a new node as last child of 2., <sub>(*33)</sub>

``` php $cat->bind($data) ->setLocation(2, NestedRecord::LOCATION_LAST_CHILD) ->store();, <sub>(*34)</sub>

Available positions:

- LOCATION_FIRST_CHILD
- LOCATION_LAST_CHILD
- LOCATION_BEFORE
- LOCATION_AFTER

### Move Node

#### Re Ordering

``` php
$cat->move(1); // move up
$cat->move(-1); // Move down

Move To Other Node

Move to node 3 as last child., <sub>(*35)</sub>

``` php $cat->moveByReference(3, NestedRecord::LOCATION_LAST_CHILD);, <sub>(*36)</sub>

### Rebuild

If a tree was not correct, using rebuild to reset all `lft`, `rgt` of this branch.

``` php
$cat->load(5);
$cat->rebuild(); // Rebuild node: 5 and it's children.

getPath

Method to get an array of nodes from a given node to its root., <sub>(*37)</sub>

``` php $path = $cat->getPath();, <sub>(*38)</sub>

### getTree

Method to get a node and all its child nodes.

``` php
$records = $cat->getTree();

Event

Record has an event system that we can process logic before & after every DB operation., <sub>(*39)</sub>

Add event methods in your Record class., <sub>(*40)</sub>

``` php class UserRecord extends Record { public function onAfterLoad(Event $event) { $this->foo = array('a', 'b', 'c'); } }, <sub>(*41)</sub>

Or add listeners to Dispatcher (You must install `windwalker/event` first).

``` php
// Use listener object
$record->getDispatcher()->addListener(new MyRecordListener);

// Use callback
$record->getDispatcher()->listen('onAfterStore', function (Event $event)
{
    // Process your logic
});

Available events:, <sub>(*42)</sub>

• onBeforeLoad
• onAfterLoad
• onBeforeStore
• onAfterStore
• onBeforeDelete
• onAfterDelete
• onBeforeBind
• onAfterBind
• onBeforeCreate
• onAfterCreate
• onBeforeUpdate
• onAfterUpdate