[READ-ONLY] A flexible, lightweight and powerful Object-Relational Mapper for PHP, implemented using the DataMapper pattern. This repo is a split of the main code that can be found in https://github.com/cakephp/cakephp
Failed to load latest commit information.
Association Update phpstan to v0.10. Jul 26, 2018
Behavior Update phpstan to v0.10. Jul 26, 2018
Exception Fixing style errors. Jan 23, 2018
Locator Fixing style errors. May 8, 2018
Rule Merge branch 'master' into 3.next Apr 14, 2018
Association.php Fix errors reported by phpstan. Mar 18, 2018
AssociationCollection.php Fix all phpDocs @throws FQN Apr 16, 2018
AssociationsNormalizerTrait.php Use HTTPS for the opensource.org URL Jun 11, 2017
Behavior.php Fix all phpDocs @throws FQN Apr 16, 2018
BehaviorRegistry.php Make BehaviorRegistry::className() return null on failure. Dec 5, 2017
EagerLoadable.php Merge branch 'master' into 3.next Dec 13, 2017
EagerLoader.php Add QueryTrait::getRepository(). Apr 4, 2018
Entity.php Use HTTPS for the opensource.org URL Jun 11, 2017
LICENSE.txt Use HTTPS for the cakefoundation.org URL Jun 10, 2017
LazyEagerLoader.php Fix a typo May 23, 2018
Marshaller.php Update phpstan to v0.10. Jul 26, 2018
PropertyMarshalInterface.php Use HTTPS for the opensource.org URL Jun 11, 2017
Query.php Update phpstan to v0.10. Jul 26, 2018
README.md Update docs on table locators usage. Feb 15, 2018
ResultSet.php Update usage of deprecated method. Jul 26, 2018
RulesChecker.php Use HTTPS for the opensource.org URL Jun 11, 2017
SaveOptionsBuilder.php Updated instance of Table::association() Nov 7, 2017
Table.php Update phpstan to v0.10. Jul 26, 2018
TableRegistry.php Remove deprecation warnings for commonly used TableRegistry methods. Feb 15, 2018
composer.json Update requirements in subsplits. Apr 19, 2018


Total Downloads License


The CakePHP ORM provides a powerful and flexible way to work with relational databases. Using a datamapper pattern the ORM allows you to manipulate data as entities allowing you to create expressive domain layers in your applications.

Database engines supported

The CakePHP ORM is compatible with:

  • MySQL 5.1+
  • Postgres 8+
  • SQLite3
  • SQLServer 2008+
  • Oracle (through a community plugin)

Connecting to the Database

The first thing you need to do when using this library is register a connection object. Before performing any operations with the connection, you need to specify a driver to use:

use Cake\Datasource\ConnectionManager;

ConnectionManager::setConfig('default', [
	'className' => 'Cake\Database\Connection',
	'driver' => 'Cake\Database\Driver\Mysql',
	'database' => 'test',
	'username' => 'root',
	'password' => 'secret',
	'cacheMetadata' => true,
	'quoteIdentifiers' => false,

Once a 'default' connection is registered, it will be used by all the Table mappers if no explicit connection is defined.

Using Table Locator

In order to access table instances you need to use a Table Locator.

use Cake\ORM\Locator\TableLocator;

$locator = new TableLocator();
$articles = $locator->get('Articles');

You can also use a trait for easy access to the locator instance:

use Cake\ORM\Locator\LocatorAwareTrait;

$articles = $this->getTableLocator()->get('Articles');

By default classes using LocatorAwareTrait will share a global locator instance. You can inject your own locator instance into the object:

use Cake\ORM\Locator\TableLocator;
use Cake\ORM\Locator\LocatorAwareTrait;

$locator = new TableLocator();

$articles = $this->getTableLocator()->get('Articles');

Creating Associations

In your table classes you can define the relations between your tables. CakePHP's ORM supports 4 association types out of the box:

  • belongsTo - E.g. Many articles belong to a user.
  • hasOne - E.g. A user has one profile
  • hasMany - E.g. A user has many articles
  • belongsToMany - E.g. An article belongsToMany tags.

You define associations in your table's initialize() method. See the documentation for complete examples.

Reading Data

Once you've defined some table classes you can read existing data in your tables:

use Cake\ORM\Locator\LocatorAwareTrait;

$articles = $this->getTableLocator()->get('Articles');
foreach ($articles->find() as $article) {
	echo $article->title;

You can use the query builder to create complex queries, and a variety of methods to access your data.

Saving Data

Table objects provide ways to convert request data into entities, and then persist those entities to the database:

use Cake\ORM\Locator\LocatorAwareTrait;

$data = [
	'title' => 'My first article',
	'body' => 'It is a great article',
	'user_id' => 1,
	'tags' => [
		'_ids' => [1, 2, 3]
	'comments' => [
		['comment' => 'Good job'],
		['comment' => 'Awesome work'],

$articles = $this->getTableLocator()->get('Articles');
$article = $articles->newEntity($data, [
	'associated' => ['Tags', 'Comments']
$articles->save($article, [
	'associated' => ['Tags', 'Comments']

The above shows how you can easily marshal and save an entity and its associations in a simple & powerful way. Consult the ORM documentation for more in-depth examples.

Deleting Data

Once you have a reference to an entity, you can use it to delete data:

$articles = $this->getTableLocator()->get('Articles');
$article = $articles->get(2);

Meta Data Cache

It is recommended to enable meta data cache for production systems to avoid performance issues. For e.g. file system strategy your bootstrap file could look like this:

use Cake\Cache\Engine\FileEngine;

$cacheConfig = [
   'className' => FileEngine::class,
   'duration' => '+1 year',
   'serialize' => true,
   'prefix'    => 'orm_',
Cache::setConfig('_cake_model_', $cacheConfig);

Additional Documentation

Consult the CakePHP ORM documentation for more in-depth documentation.