PHPackages                             cakephp/orm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. cakephp/orm

ActiveLibrary[Framework](/categories/framework)

cakephp/orm
===========

CakePHP ORM - Provides a flexible and powerful ORM implementing a data-mapper pattern.

5.3.3(2mo ago)151242.6k↓20.8%15[1 issues](https://github.com/cakephp/orm/issues)20MITPHPPHP >=8.2

Since Mar 22Pushed 2mo ago25 watchersCompare

[ Source](https://github.com/cakephp/orm)[ Packagist](https://packagist.org/packages/cakephp/orm)[ Docs](https://cakephp.org)[ RSS](/packages/cakephp-orm/feed)WikiDiscussions 5.x Synced 1mo ago

READMEChangelogDependencies (18)Versions (337)Used By (20)

[![Total Downloads](https://camo.githubusercontent.com/31e3497c8c01523c74a0ecbc77af2057a389ffb47effe357bb2a21b3cfeb995b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63616b657068702f6f726d2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cakephp/orm)[![License](https://camo.githubusercontent.com/942e017bf0672002dd32a857c95d66f28c5900ab541838c6c664442516309c8a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE.txt)

CakePHP ORM
===========

[](#cakephp-orm)

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
--------------------------

[](#database-engines-supported)

The CakePHP ORM is compatible with:

- MySQL 5.1+
- Postgres 8+
- SQLite3
- SQLServer 2008+
- Oracle (through a [community plugin](https://github.com/CakeDC/cakephp-oracle-driver))

Connecting to the Database
--------------------------

[](#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::class,
	'driver' => \Cake\Database\Driver\Mysql::class,
	'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
-------------------

[](#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();
$this->setTableLocator($locator);

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

Creating Associations
---------------------

[](#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](https://book.cakephp.org/5/en/orm/associations.html) for complete examples.

Reading Data
------------

[](#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](https://book.cakephp.org/5/en/orm/query-builder.html) to create complex queries, and a [variety of methods](https://book.cakephp.org/5/en/orm/retrieving-data-and-resultsets.html)to access your data.

Saving 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](https://book.cakephp.org/5/en/orm/saving-data.html)for more in-depth examples.

Deleting Data
-------------

[](#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);
$articles->delete($article);
```

Meta Data Cache
---------------

[](#meta-data-cache)

It is recommended to enable metadata 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);
```

Cache configs are optional, so you must require `cachephp/cache` to add one.

Creating Custom Table and Entity Classes
----------------------------------------

[](#creating-custom-table-and-entity-classes)

By default, the Cake ORM uses the `\Cake\ORM\Table` and `\Cake\ORM\Entity` classes to interact with the database. While using the default classes makes sense for quick scripts and small applications, you will often want to use your own classes for adding your custom logic.

When using the ORM as a standalone package, you are free to choose where to store these classes. For example, you could use the `Data` folder for this:

```