ActiveRecord
Pair allows the creation of objects related to each respective database table using the ActiveRecord class, based on the homonymous ActiveRecord pattern.
The configuration of the objects described above does not require the creation of XML files, as usual, in the ORM. Objects created by the DB records are converted in both directions to the desired PHP type. See further on this page.
In addition, each class inherited from ActiveRecord supports many convenient methods including those for managing the internal cache for saving data that saves queries.
The Pair base tables are InnoDB utf-8mb4.
The purpose of this class is to provide inheritance for the methods of the ActiveRecord paradigm, which involves coupling a class to a database table.
Creating an object that inherits from ActiveRecord using the PHP __construct() method can be done in two ways:
- using the key field in the table
- manually populating all the expected properties
To construct an object using the table key, you can indicate three types of keys:
- integer for simple tables or autoincrement
- string for simple tables
- Array for tables with composite keys
A query to the database will retrieve the object identified by the key value and all the properties of the object bound to the table fields will be populated and converted accordingly (see automatic cast).
Example:
<?php
use Pair\ActiveRecord;
class Person extends ActiveRecord {
/**
* Property that binds db field id.
* @var int
*/
protected $id;
/**
* Property that binds db field name.
* @var string
*/
protected $name;
/**
* Name of related db table.
* @var string
*/
const TABLE_NAME = 'persons';
/**
* Name of primary key db field.
* @var array
*/
const TABLE_KEY = ['id'];
/**
* Method called by constructor just after having populated the object.
*/
protected function init() {
$this->bindAsInteger('id');
}
}
$id = 1;
$person = new Person($id);
print $person->name;The $person object has the id and name properties populated as in the record of db where id = 1.
Note:
idobject property is casted to integer when its value is collected by database record.
The second way to create an object is the manual population of its properties. This is useful when you have already loaded a list of complete rows of the table and want to create the related objects without further queries.
To construct an object in this way, it is sufficient to pass as a parameter an object of type PHP stdClass containing the same properties of the object to be created and its values.
Example:
<?php
// load an array of stdClass object with all rows in persons
$db = Database::getInstance();
$db->setQuery('SELECT * FROM persons');
$list = $db->loadObjects();
// initialize persons list
$persons = array();
// populate persons with Person objects
foreach ($list as $row) {
$persons[] = new Person($row);
}If some properties are not of the same expected type, an automatic cast will be performed by the parent ActiveRecord class.
Each property of a Pair\ActiveRecord object can be automatically converted to a specific type of PHP. This happens when an object is requested by loading it from the DB. When an object is to be stored in the DB, a smart reverse conversion occurs. It is recommended to call these methods within the init() method available for each Pair\ActiveRecord child object.
The following self-explanatory methods perform the proper conversions when loaded a record from DB and when the object is saved to DB.
Converts the value of the field, usually an integer of any size, to TRUE or FALSE. The PHP NULL value is not foreseen under any circumstances.
This special type is very useful for storing properties of the array object in a string, ENUM or SET field of the database by executing the conversion of the array into a comma-separated values string before storing the record.
This is the most sophisticated method of the series. The date can be set in different ways and could have only the date or both date and time. In any case, the available property will be a PHP DateTime object or, if the DB column is Nullable, the NULL value.
First assign the TimeZone of the connected user, if there is one, otherwise assign the default TimeZone in the case of a guest or stand-alone process.
Then it distinguishes the different cases in which the date can be indicated. If the constant UTC_DATE in configuration file is TRUE and the date is of type integer or consisting of a string of numbers only, then it interprets it as a timestamp.
Then check if the date is in date or time format of the dbms and in the case or directly a PHP DateTime object and assign it to the object property.
In case of unrecognized date, it is assigned NULL to the property.
Converts field value to PHP Float type. It is recommended for use with the DB fields of the type DEC, DECIMAL, DOUBLE, DOUBLE PRECISION, FIXED, FLOAT, NUMERIC, REAL. If the DB field is Nullable, the value can be of PHP NULL type, which will otherwise be converted to 0.0.
Converts the value of the DB field to the PHP integer type. If the DB field is Nullable, this property can have NULL value, otherwise the assignment from code of the NULL value will be automatically converted to 0.
Tip: Do not use this method to handle BIGINT fields because of PHP int value limits will produce side effects when out-of-range.
To store an object you can use the store() method. This distinguishes the action to be performed based on the primary-key related to the object class. If the key is single and has the auto-increment attribute, the object creates a new record when the field linked to the primary-key has a value of NULL by invoking the method create(). In other cases, compound-key or primary-key with a string or integer value, the update() method is invoked.
Before storing an object in the DB, it is possible to indicate the actions to be performed. For this you can insert some code in the following methods:
-
beforeCreate(), invoked before the creation of a record -
beforeUpdate(), invoked before a record is updated -
beforeStore(), invoked in both the above cases
With the same logic, you can run some code immediately after editing an ActiveRecord object by inserting it in one of the following methods, as needed:
-
afterCreate(), invoked after creating a record -
afterUpdate(), invoked after updating a record -
afterStore(), invoked in both the above cases
Before storing the record, whether it is created or updated, each property value that has a corresponding one in the columns of the DB is converted appropriately according to the indications provided by the bindAs* methods. If the field was primary-key with auto-increment, the property of the key field is populated with the real value of the key field in the corresponding record.
