Object Relational Mapping Component (PtcMapper)

Table of Contents

• Introduction
• Getting Started
• Specifying Table Name
• Retrieve All Records
• Retrieve Record Based On Id
• Using The Query Builder Directly
• Adding Records
• Updating Records
• Deleting Records
• Converting Values
  • Convert Values To Array
  • Convert Values To Json
• Retrieving Single Values
• Updating Single Values
• Mapping Field Names
• Using Observer Events
• Adding Options On Initialization
• Specify Connection To Use
• Specify Unique Key
• Specify Event Class
• Specify Connection Manager Class
• Adding Options On Initialization

Introduction

The Object Relational Mapping Component is a great tool for retrieving and manipulating database tables data with just a couple of lines of code. The class can be used with the PtcEvent component to add event listeners to queries. This class can also be used to call methods from the PtcQueryBuilder component directly. Retrieved rows can be converted to arrays or json arrays. The PtcMapper can also use shortcut methods to retrieve / update single column values.

Main Features:

• Simple syntax to manipulate and insert rows
• Uses shortcuts to retrieve / update single column value
• Can be used with PtcEvent component to add event listeners to queries
• Uses the PtcQueryBuilder class to handle all queries
• Converts retrieved records to json arrays
• Can use any connection configured with the PtcDb class

Note

This component depends on the PtcDb and the PtcQueryBuilder components, therfore it is not stand-alone.

---

Getting Started

To get started using this component, you just need to extend the class:

// Using the database table name as class name
class MY_Table extends PtcMapper
{

}

$row = MY_Table::find( 1 ); // getting record by id
print '<b>Getting 1 row:</b><br>';
print $row->field1 . '<br>';
print $row->field2 . '<br>';

And that's about it. The class name will be used as the database table name in lowercase letters.

Note

To retrieve and update records correctly, the class uses a primary key as unique row identifier which needs to be present in the table structure.

---

Specifying Table Name

If you need to specify the table name, use the static property PtcMapper::$_table in your extended class:

class MY_Table extends PtcMapper
{
    protected static $_table = 'table_name';
}

---

Retrieve All Records

To retrieve all records from the table, the method PtMapper:all( ) can be used:

// RETRIEVING ALL RECORDS FROM TABLE
$data = MY_Table::all( );
print "<b>Looping through all records:</b><br>";
foreach ( $data as $row )
{
    print $row->field1 . "<br>";
    print $row->field2 . "<br>";
}
print "<br>";

---

Retrieve Record Based On Id

To retrieve 1 record by it's id, the method PtcMapper:find( ) can be used:

// RETRIEVING 1 ROW BASED ON ID
$row = MY_Table::find( 1 );

print $row->field1 . "<br>";
print $row->field2 . "<br><br>";

---

Using The Query Builder Directly

The PtcMapper component can be used to call the query builder method directly.
Have a look at the following example to undestand how this can be done:

// USING THE QUERY BUILDER METHODS DIRECTLY
$data = MY_Table::where( 'id' , '!=' , 2 )->run( );

foreach ( $data as $row )
{
    print $row->field1 . "<br>";
    print $row->field2 . "<br>";
}

---

Adding Records

Adding new records is very simple, have a look at the following example:

// ADDING NEW RECORDS
$row = new MY_Table( );

$row->field1 = 'some value';
$row->field2 = 'some other value';

$row->save( ); // saving the values to the table

To create a new record from an associative array use the PtcMapper:create( ) method:

// CREATING NEW RECORD FROM ASSOCIATIVE ARRAY
$arr = array( 'field1' => 'created from array' , 'field2' => 'created from array' );
$row = MY_Table::create( $arr );

$row->save( ); // saving the values to the table

// or in 1 line
//Test_Table::create( $arr )->save( );

---

Updating Records

To update records the method PtcMapper::save( ) can be used:

// UPDATING RECORDS
$row = MY_Table::find( 1 ); // get record by id

$row->field1 = 'updated value';
$row->field2 = 'updated value';

$row->save( );

---

Deleting Records

To delete a record, the method PtcMapper::delete( ) can be used:

// DELETING RECORDS
$row = MY_Table::find( 1 ); // get record by id

$row->delete( ); // delete retrieved record

// same as above but in 1 line
MY_Table::find( 1 )->delete( );

The query builder can also be used with a where clause to delete records:

// using the query builder directly
MY_Table::where('field1', '!=', 'some value' )->delete( )->run( );

Refer to the Query Builder Component (PtcQueryBuilder) user manual for detailed usage over the PtcQueryBuilder.

---

Converting Values

The returned values from the queries, can be converted to array or json. The following paragraphs will demostrate how:

Convert Values To Array

If you need to convert a record values to an array, the method PtcMapper::toArray( ) can be used:

    $row = MY_Table::find( 1 ); // retrieving by id

$data = $row->toArray( ); // converting the values to an array

Convert Values To Json

To convert records to json array, use the PtcMapper::toJson( ) method:

$row = MY_Table::find( 1 ); // retrieving by id

$data = $row->toJson( ); // converting the values to a json array

---

Retrieving Single Values

There are shortcuts to retrieve single column values with the component, by using the prefix "get_" followed by the column name:

// retrieving single column value based on id
print Test_Table::get_some_column_name( 1 ); // retrieving by id

// select `some_column_name` where `some_column` = 'some value'
print Test_Table::get_some_column_name( 'some_column' , 'some value' );

---

Updating Single Values

Updating 1 single value based on the record id, can be done quickly by using the prefix "set_" followed by the column name that you want to update:

// updating 1 single column value based on id
Test_Table::set_some_column( 'new value saved' , 1 ); // set come_column = 'new value saved' where id = 1

---

Mapping Field Names

To map field names, use the property PtcMapper::$_map like shown in the following example:

    class MY_Table extends PtcMapper
{
    // MAP FIELD NAMES IF "AS" IS USED IN A SELECT QUERY
    protected static $_map = array( 'column_name' => 'i' ); 
}

// using "as" with the select( ) method from the query builder
MY_Table::select( 'column_name as i' )
    ->where( 'some_column' , '!=' ,'some value' )
    ->run( );

---

Using Observer Events

The PtcMapper component can be used with the PtcEvent class, to add event observers to the queries.

Here follows a list with all event observers and possible arguments, when they are fired:

• inserting ( &$values ), called before row insert
• inserted ( &$values , $result ), called after row insert
• updating ( &$values ), called before row update
• updated ( &$values , $result ), called after row update
• saving ( &$values ), called before row insert and update
• saved ( &$values , $result ), called after row insert and update
• deleting ( &$values ), called before row delete
• deleted ( &$values , $result ), called after row delete

Note

Observer events are fired even if the query result was not sucessfull, the check needs to be done manually with the "$result" parameter.

To use these observer events, add them as static methods to your class:

class myObserver
{
    // observer example
    public static function saved( $data , $result )
    {
        // do some stuff here after save( ) is called
        if ( $result )
        {
            // log the query values 
            var_dump( $data );
        }
    }
}

Observers can be registered with the PtcMapper::observe( ) method:

// register our class as observer
MY_Table::observe( 'myObserver' );

---

Adding Options On Initialization

To add options on on initliazation, use the boot( ) method, like shown in the next example:

class MY_Table extends PtcMapper
{
    public static function boot( )
    {
        static::observe( 'myObserver' ); // registering observer events on initalization
    }
}

---

Specify Connection To Use

By default the PtcMapper component uses the "default" connection from the PtcDb component.
To specify a different connection, use the PtcMapper::$_connectionName property to specify the connection to use:

class MY_Table extends PtcMapper
{
    protected static $_connectionName ='your connection name';
}

---

Specify Unique Key

By default the PtcMapper uses the string "id" to identify the primary key for the table.
To specify a different column name, use the PtcMapper::$_uniqueKey property:

    class MY_Table extends PtcMapper
{
    protected static $_uniqueKey ='yourKey';
}

---

Specify Event Class

To specify a different name for the event class, use the static property PtcMapper::$_eventClass, inside your extend class:

    class MY_Table extends PtcMapper
{
    protected static $_eventClass ='yourEventClassName';
}

---

Specify Connection Manager Class

To specify a different name for the event class, use the static property PtcMapper::$_connectionManager, inside your extend class:

    class MY_Table extends PtcMapper
{
    protected static $_connectionManager ='connectionManagerName';
}

---

Adding Options On Initialization

To add options on initialization, add the method boot( ) statically to your extended class:

    class MY_Table extends PtcMapper
{
    public static boot( )
    {
        // do something on initialization
    }
}