Database Access & ORM

In CakePHP working with data through the database is done with two primary objecttypes. The first are repositories or table objects. These objectsprovide access to collections of data. They allow you to save new records,modify/delete existing ones, define relations, and perform bulk operations. Thesecond type of objects are entities. Entities represent individual recordsand allow you to define row/record level behavior & functionality.

These two classes are usually responsible for managing almost everythingthat happens regarding your data, its validity, interactions and evolutionof the information workflow in your domain of work.

CakePHP’s built-in ORM specializes in relational databases, but can be extendedto support alternative datasources.

The CakePHP ORM borrows ideas and concepts from both ActiveRecord and Datamapperpatterns. It aims to create a hybrid implementation that combines aspects ofboth patterns to create a fast, simple to use ORM.

Before we get started exploring the ORM, make sure you configure yourdatabase connections.

Note

If you are familiar with previous versions of CakePHP, you should read theNew ORM Upgrade Guide for important differences between CakePHP 3.0and older versions of CakePHP.

Quick Example

To get started you don’t have to write any code. If you’ve followed the CakePHPconventions for your database tablesyou can just start using the ORM. For example if we wanted to load some data from our articlestable we could do:

  1. use Cake\ORM\TableRegistry;
  2.  
  3. $articles = TableRegistry::getTableLocator()->get('Articles');
  4.  
  5. $query = $articles->find();
  6.  
  7. foreach ($query as $row) {
  8.     echo $row->title;
  9. }

Note that we didn’t have to create any code or wire any configuration up.The conventions in CakePHP allow us to skip some boilerplate code and allow theframework to insert base classes when your application has not createda concrete class. If we wanted to customize our ArticlesTable class adding someassociations or defining some additional methods we would add the following tosrc/Model/Table/ArticlesTable.php after the <?php opening tag:

  1. namespace App\Model\Table;
  2.  
  3. use Cake\ORM\Table;
  4.  
  5. class ArticlesTable extends Table
  6. {
  7.  
  8. }

Table classes use the CamelCased version of the table name with the Tablesuffix as the class name. Once your class has been created you get a referenceto it using the ORM\Locator\TableLocator through ORM\TableRegistry as before:

  1. use Cake\ORM\TableRegistry;
  2.  
  3. // Now $articles is an instance of our ArticlesTable class.
  4. $articles = TableRegistry::getTableLocator()->get('Articles');

Now that we have a concrete table class, we’ll probably want to use a concreteentity class. Entity classes let you define accessor and mutator methods, definecustom logic for individual records and much more. We’ll start off by adding thefollowing to src/Model/Entity/Article.php after the <?php opening tag:

  1. namespace App\Model\Entity;
  2.  
  3. use Cake\ORM\Entity;
  4.  
  5. class Article extends Entity
  6. {
  7.  
  8. }

Entities use the singular CamelCase version of the table name as their classname by default. Now that we have created our entity class, when weload entities from the database we’ll get instances of our new Article class:

  1. use Cake\ORM\TableRegistry;
  2.  
  3. // Now an instance of ArticlesTable.
  4. $articles = TableRegistry::getTableLocator()->get('Articles');
  5. $query = $articles->find();
  6.  
  7. foreach ($query as $row) {
  8.     // Each row is now an instance of our Article class.
  9.     echo $row->title;
  10. }

CakePHP uses naming conventions to link the Table and Entity class together. Ifyou need to customize which entity a table uses you can use theentityClass() method to set a specific classname.

See the chapters on Table Objects and Entities for moreinformation on how to use table objects and entities in your application.

More Information