Object-oriented CRUD for Doctrine DBAL
, (*1)
As a lightweight alternative to Doctrine ORM, this battle-tested library provides Business Model and Database Access Object (DAO) classes
that encapsulate Doctrine DBAL to provide high-performance, object-oriented CRUD (create, read, update, delete)
functionality for relational databases. It is a lot faster and less complex than Datamapper ORM implementations. See TRADEOFFS.md., (*2)
Documentation: https://docs.symlex.org/en/latest/doctrine-active-record/, (*3)
, (*4)
Basic Example
<?php
use Doctrine\ActiveRecord\Dao\Factory as DaoFactory;
use Doctrine\ActiveRecord\Model\Factory;
$daoFactory = new DaoFactory($db);
$modelFactory = new Factory($daoFactory);
$modelFactory->setFactoryNamespace('App\Model');
$modelFactory->setFactoryPostfix('Model');
// Returns instance of App\Model\UserModel
$user = $modelFactory->create('User');
// Throws exception, if not found
$user->find(123);
if ($user->email == '') {
// Update email
$user->update(array('email' => 'user@example.com'));
}
// Returns instance of App\Model\GroupModel
$group = $user->createModel('Group');
Usage in REST Controller Context
Doctrine ActiveRecord is perfectly suited for building high-performance REST services., (*5)
This example shows how to work with the EntityModel in a REST controller context. Note, how easy it is to avoid deeply
nested structures. User model and form factory (provided by the InputValidation
package) are injected as dependencies., (*6)
<?php
namespace App\Controller\Rest;
use Symfony\Component\HttpFoundation\Request;
use App\Exception\FormInvalidException;
use App\Form\FormFactory;
use App\Model\User;
class UsersController
{
protected $user;
protected $formFactory;
public function __construct(User $user, FormFactory $formFactory)
{
$this->user = $user;
$this->formFactory = $formFactory;
}
public function cgetAction(Request $request)
{
$options = array(
'count' => $request->query->get('count', 50),
'offset' => $request->query->get('offset', 0)
);
return $this->user->search(array(), $options);
}
public function getAction($id)
{
return $this->user->find($id)->getValues();
}
public function deleteAction($id)
{
return $this->user->find($id)->delete();
}
public function putAction($id, Request $request)
{
$this->user->find($id);
$form = $this->formFactory->create('User\Edit');
$form
->setDefinedWritableValues($request->request->all())
->validate();
if($form->hasErrors()) {
throw new FormInvalidException($form->getFirstError());
}
$this->user->update($form->getValues());
return $this->user->getValues();
}
public function postAction(Request $request)
{
$form = $this->formFactory->create('User\Create');
$form
->setDefinedWritableValues($request->request->all())
->validate();
if($form->hasErrors()) {
throw new FormInvalidException($form->getFirstError());
}
$this->user->save($form->getValues());
return $this->user->getValues();
}
}
See also: InputValidation for PHP – Easy & secure whitelist validation for input data of any origin, (*7)
Data Access Objects
DAOs directly deal with database tables and raw SQL, if needed. Doctrine\ActiveRecord\Dao\Dao is suited to implement custom methods using raw SQL. All DAOs expose the following public methods by default:
- createDao(string $name): Returns a new DAO instance
- beginTransaction(): Start a database transaction
- commit(): Commit a database transaction
- rollBack(): Roll back a database transaction, (*8)
In addition, Doctrine\ActiveRecord\Dao\EntityDao offers many powerful methods to easily deal with database table rows:
- setData(array $data): Set raw data (changes can not be detected, e.g. when calling update())
- setValues(array $data): Set multiple values
- setDefinedValues(array $data): Set values that exist in the table schema only (slower than setValues())
- getValues(): Returns all values as array
- find($id): Find a row by primary key
- reload(): Reload row values from database
- getValues(): Returns all values as associative array
- exists($id): Returns true, if a row with the given primary key exists
- save(): Insert a new row
- update(): Updates changed values in the database
- delete(): Delete entity from database
- getId(): Returns the ID of the currently loaded record (throws exception, if empty)
- hasId(): Returns true, if the DAO instance has an ID assigned (primary key)
- setId($id): Set primary key
- findAll(array $cond = array(), $wrapResult = true): Returns all instances that match $cond (use search() or searchAll(), if you want to limit or sort the result set)
- search(array $params): Returns a SearchResult object (see below for supported parameters)
- wrapAll(array $rows): Create and return a new DAO for each array element
- updateRelationTable(string $relationTable, string $primaryKeyName, string $foreignKeyName, array $existing, array $updated): Helper function to update n-to-m relationship tables
- hasTimestampEnabled(): Returns true, if this DAO automatically adds timestamps when creating and updating rows
- findList(string $colName, string $order = '', string $where = '', string $indexName = ''): Returns a key/value array (list) of all matching rows
- getTableName(): Returns the name of the underlying database table
- getPrimaryKeyName(): Returns the name of the primary key column (throws an exception, if primary key is an array), (*9)
Search Parameters
search() accepts the following optional parameters to limit, filter and sort search results:, (*10)
table: Table name, (*11)
table_alias: Alias name for "table" (table reference for join and join_left), (*12)
cond: Search conditions as array (key/value or just values for raw SQL), (*13)
count: Maximum number of results (integer), (*14)
offset: Result offset (integer), (*15)
join: List of joined tables incl join condition e.g. array(array('u', 'phonenumbers', 'p', 'u.id = p.user_id')), see Doctrine DBAL manual, (*16)
left_join: See join, (*17)
columns: List of columns (array), (*18)
order: Sort order (if not false), (*19)
group: Group by (if not false), (*20)
wrap: If false, raw arrays are returned instead of DAO instances, (*21)
ids_only: Return primary key values only, (*22)
sql_filter: Raw SQL filter (WHERE), (*23)
id_filter: If not empty, limit result to this list of primary key IDs, (*24)
Search Result
When calling search() on a EntityDao or EntityModel, you'll get a SearchResult instance as return value.
It implements ArrayAccess, Serializable, IteratorAggregate and Countable and can be used either as array
or object with the following methods:, (*25)
getAsArray(): Returns search result as array, (*26)
getSortOrder(): Returns sort order as string, (*27)
getSearchCount(): Returns search count (limit) as integer, (*28)
getSearchOffset(): Returns search offset as integer, (*29)
getResultCount(): Returns the number of actual query results (<= limit), (*30)
getTotalCount(): Returns total result count (in the database), (*31)
getAllResults(): Returns all results as array of EntityDao or EntityModel instances, (*32)
getAllResultsAsArray(): Returns all results as nested array (e.g. to serialize it as JSON), (*33)
getFirstResult(): Returns first result EntityDao or EntityModel instance or throws an exception, (*34)
Entity Configuration
DAO entities are configured using protected class properties:, (*35)
<?php
protected $_tableName = ''; // Database table name
protected $_primaryKey = 'id'; // Name or array of primary key(s)
protected $_fieldMap = array(); // 'db_column' => 'object_property'
protected $_hiddenFields = array(); // Fields that should be hidden for getValues(), e.g. 'password'
protected $_formatMap = array(); // 'db_column' => Format::TYPE
protected $_valueMap = array(); // 'object_property' => 'db_column'
protected $_timestampEnabled = false; // Automatically update timestamps?
protected $_timestampCreatedCol = 'created';
protected $_timestampUpdatedCol = 'updated';
Possible values for $_formatMap are defined as constants in Doctrine\ActiveRecord\Dao\Format:, (*36)
<?php
const NONE = '';
const INT = 'int';
const FLOAT = 'float';
const STRING = 'string';
const ALPHANUMERIC = 'alphanumeric';
const SERIALIZED = 'serialized';
const JSON = 'json';
const CSV = 'csv';
const BOOL = 'bool';
const TIME = 'H:i:s';
const TIMEU = 'H:i:s.u'; // Support for microseconds (up to six digits)
const TIMETZ = 'H:i:sO'; // Support for timezone (e.g. "+0230")
const TIMEUTZ = 'H:i:s.uO'; // Support for microseconds & timezone
const DATE = 'Y-m-d';
const DATETIME = 'Y-m-d H:i:s';
const DATETIMEU = 'Y-m-d H:i:s.u'; // Support for microseconds (up to six digits)
const DATETIMETZ = 'Y-m-d H:i:sO'; // Support for timezone (e.g. "+0230")
const DATETIMEUTZ = 'Y-m-d H:i:s.uO'; // Support for microseconds & timezone
const TIMESTAMP = 'U';
Example:, (*37)
<?php
namespace App\Dao;
use Doctrine\ActiveRecord\Dao\EntityDao;
class UserDao extends EntityDao
{
protected $_tableName = 'users';
protected $_primaryKey = 'user_id';
protected $_timestampEnabled = true;
}
Business Models
Business Models are logically located between Controllers - which render views and validate user input - and Data Access Objects (DAOs), that are low-level interfaces to a storage backend or Web service., (*38)
Public interfaces of models are high-level and should reflect all use cases within their domain. There are a number of standard use-cases that are pre-implemented in the base class Doctrine\ActiveRecord\Model\EntityModel:, (*39)
createModel(string $name = '', Dao $dao = null): Create a new model instance, (*40)
find($id): Find a record by primary key, (*41)
reload(): Reload values from database, (*42)
findAll(array $cond = array(), $wrapResult = true): Find multiple records; if $wrapResult is false, plain DAOs are returned instead of model instances, (*43)
search(array $cond, array $options = array()): Returns a SearchResult object ($options can contain count, offset, sort order etc, see search() in the DAO documentation above), (*44)
searchAll(array $cond = array(), $order = false): Simple version of search(), similar to findAll(), (*45)
searchOne(array $cond = array()): Search a single record; throws an exception if 0 or more than one record are found, (*46)
searchIds(array $cond, array $options = array()): Returns an array of matching primary keys for the given search condition, (*47)
getModelName(): Returns the model name without prefix and postfix, (*48)
getId(): Returns the ID of the currently loaded record (throws exception, if empty), (*49)
hasId(): Returns true, if the model instance has an ID assigned (primary key), (*50)
getValues(): Returns all model properties as associative array, (*51)
getEntityTitle(): Returns the common name of this entity, (*52)
isDeletable(): Returns true, if the model instance can be deleted with delete(), (*53)
isUpdatable(): Returns true, if the model instance can be updated with update($values), (*54)
isCreatable(): Returns true, if new entities can be created in the database with create($values), (*55)
batchEdit(array $ids, array $properties): Update data for multiple records, (*56)
getTableName(): Returns the name of the associated main database table, (*57)
hasTimestampEnabled(): Returns true, if timestamps are enabled for the associated DAO, (*58)
delete(): Permanently delete the entity record from the database, (*59)
save(array $values): Create a new record using the values provided, (*60)
update(array $values): Update model instance database record; before assigning multiple values to a model instance, data should be validated using a form class, (*61)
How much validation should be implemented within a model? Wherever invalid data can lead to security issues or major inconsistencies, some core validation rules must be implemented in the model layer. Model exception messages usually don’t require translation (in multilingual applications), since invalid values should be recognized beforehand by a form class. If you expect certain exceptions, you should catch and handle them in your controllers., (*62)
Models are associated with their respective Dao using a protected class property:, (*63)
protected $_daoName = ''; // DAO class name without namespace or postfix
Example:, (*64)
<?php
namespace App\Model;
use Doctrine\ActiveRecord\Model\EntityModel;
class User extends EntityModel
{
protected $_daoName = 'User';
public function delete()
{
$dao = $this->getEntityDao();
$dao->is_deleted = 1;
$dao->update();
}
public function undelete()
{
$dao = $this->getEntityDao();
$dao->is_deleted = 0;
$dao->update();
}
public function search(array $cond, array $options = array())
{
$cond['is_deleted'] = 0;
return parent::search($cond, $options);
}
public function getValues()
{
$result = parent::getValues();
unset($result['password']);
return $result;
}
}
Unit Tests
This library comes with a docker-compose.yml file for MySQL and database fixtures to run unit tests (MySQL will bind to 127.0.0.1:3308):, (*65)
localhost# docker-compose up -d
localhost# docker-compose exec mysql sh
docker# cd /share/src/Tests/_fixtures
docker# mysql -u root --password=doctrine doctrine-active-record < schema.sql
docker# exit
localhost# bin/phpunit
PHPUnit 7.3.2 by Sebastian Bergmann and contributors.
................................................................. 65 / 91 ( 71%)
.......................... 91 / 91 (100%)
Time: 251 ms, Memory: 8.00MB
OK (91 tests, 249 assertions)
localhost# docker-compose down
Composer
To use this library in your project, simply run composer require symlex/doctrine-active-record or
add "symlex/doctrine-active-record" to your composer.json file and run composer update:, (*66)
{
"require": {
"php": ">=7.1",
"symlex/doctrine-active-record": "^4.0"
}
}
About
Doctrine ActiveRecord is maintained by Michael Mayer.
Feel free to send an e-mail to hello@symlex.org if you have any questions,
need commercial support or just want to say hello.
We welcome contributions of any kind. If you have a bug or an idea, read our
guide before opening an issue., (*67)
Note: This library is part of Symlex (a framework stack for agile Web development
based on Symfony) and not an official Doctrine project., (*68)
Wallogit.com
