Entities¶

Creating Entity Classes¶

You don’t need to create entity classes to get started with the ORM in CakePHP. However, if you want to have custom logic in your entities you will need to create classes. By convention entity classes live in src/Model/Entity/. If our application had an articles table we could create the following entity:

// src/Model/Entity/Article.php
namespace App\Model\Entity;

use Cake\ORM\Entity;

class Article extends Entity
{
}

Right now this entity doesn’t do very much. However, when we load data from our articles table, we’ll get instances of this class.

Creating Entities¶

Entities can be directly instantiated:

use App\Model\Entity\Article;

$article = new Article();

When instantiating an entity you can pass the fields with the data you want to store in them:

use App\Model\Entity\Article;

$article = new Article([
    'id' => 1,
    'title' => 'New Article',
    'created' => new DateTime('now')
]);

The preferred way of getting new entities is using the newEntity() method from the Table objects:

use Cake\ORM\TableRegistry;

// Prior to 3.6 use TableRegistry::get('Articles')
$article = TableRegistry::getTableLocator()->get('Articles')->newEntity();

$article = TableRegistry::getTableLocator()->get('Articles')->newEntity([
    'id' => 1,
    'title' => 'New Article',
    'created' => new DateTime('now')
]);

$article will be an instance of App\Model\Entity\Article or fallback to Cake\ORM\Entity instance if you haven’t created the Article class.

Accessing Entity Data¶

Entities provide a few ways to access the data they contain. Most commonly you will access the data in an entity using object notation:

use App\Model\Entity\Article;

$article = new Article;
$article->title = 'This is my first post';
echo $article->title;

You can also use the get() and set() methods:

$article->set('title', 'This is my first post');
echo $article->get('title');

When using set() you can update multiple fields at once using an array:

$article->set([
    'title' => 'My first post',
    'body' => 'It is the best ever!'
]);

You can check if fields are defined in your entities with has():

$article = new Article([
    'title' => 'First post',
    'user_id' => null
]);
$article->has('title'); // true
$article->has('user_id'); // false
$article->has('undefined'); // false.

The has() method will return true if a field is defined and has a non-null value. You can use isEmpty() and hasValue() to check if a field contains a ‘non-empty’ value:

$article = new Article([
    'title' => 'First post',
    'user_id' => null
]);
$article->isEmpty('title');  // false
$article->hasValue('title'); // true

$article->isEmpty('user_id');  // true
$article->hasValue('user_id'); // false

Accessors & Mutators¶

In addition to the simple get/set interface, entities allow you to provide accessors and mutator methods. These methods let you customize how fields are read or set.

Accessors use the convention of _get followed by the CamelCased version of the field name.

Cake\ORM\Entity::get($field)¶

They receive the basic value stored in the _properties array as their only argument. Accessors will be used when saving entities, so be careful when defining methods that format data, as the formatted data will be persisted. For example:

namespace App\Model\Entity;

use Cake\ORM\Entity;

class Article extends Entity
{
    protected function _getTitle($title)
    {
        return ucwords($title);
    }
}

The accessor would be run when getting the field through any of these two ways:

echo $article->title;
echo $article->get('title');

You can customize how fields get set by defining a mutator:

Cake\ORM\Entity::set($field = null, $value = null)¶

Mutator methods should always return the value that should be stored in the field. As you can see above, you can also use mutators to set other calculated fields. When doing this, be careful to not introduce any loops, as CakePHP will not prevent infinitely looping mutator methods.

Mutators allow you to convert fields as they are set, or create calculated data. Mutators and accessors are applied when fields are read using property access, or using get() and set(). For example:

namespace App\Model\Entity;

use Cake\ORM\Entity;
use Cake\Utility\Text;

class Article extends Entity
{
    protected function _setTitle($title)
    {
        return Text::slug($title);
    }
}

The mutator would be run when setting the field through any of these two ways:

$user->title = 'foo'; // slug is set as well
$user->set('title', 'foo'); // slug is set as well

namespace App\Model\Entity;

use Cake\ORM\Entity;

class User extends Entity
{
    protected function _getFullName()
    {
        return $this->first_name . '  ' . $this->last_name;
    }
}

echo $user->full_name;

Checking if an Entity Has Been Modified¶

Cake\ORM\Entity::dirty($field = null, $dirty = null)¶

You may want to make code conditional based on whether or not fields have changed in an entity. For example, you may only want to validate fields when they change:

// See if the title has been modified.
// Prior to 3.5 use dirty()
$article->isDirty('title');

You can also flag fields as being modified. This is handy when appending into array fields as this wouldn’t automatically mark the field as dirty, only exchanging completely would.:

// Add a comment and mark the field as changed.
// Prior to 3.5 use dirty()
$article->comments[] = $newComment;
$article->setDirty('comments', true);

In addition you can also base your conditional code on the original field values by using the getOriginal() method. This method will either return the original value of the field if it has been modified or its actual value.

You can also check for changes to any field in the entity:

// See if the entity has changed
// Prior to 3.5 use dirty()
$article->isDirty();

To remove the dirty mark from fields in an entity, you can use the clean() method:

$article->clean();

When creating a new entity, you can avoid the fields from being marked as dirty by passing an extra option:

$article = new Article(['title' => 'New Article'], ['markClean' => true]);

To get a list of all dirty fields of an Entity you may call:

$dirtyFields = $entity->getDirty();

Validation Errors¶

After you save an entity any validation errors will be stored on the entity itself. You can access any validation errors using the getErrors(), getError() or hasErrors() methods:

// Get all the errors
$errors = $user->getErrors();
// Prior to 3.4.0
$errors = $user->errors();

// Get the errors for a single field.
$errors = $user->getError('password');
// Prior to 3.4.0
$errors = $user->errors('password');

// Does the entity or any nested entity have an error.
$user->hasErrors();

// Does only the root entity have an error
$user->hasErrors(false);

The setErrors() or setError() method can also be used to set the errors on an entity, making it easier to test code that works with error messages:

$user->setError('password', ['Password is required']);
$user->setErrors([
    'password' => ['Password is required'],
    'username' => ['Username is required']
]);

// Prior to 3.4.0
$user->errors('password', ['Password is required.']);

Mass Assignment¶

While setting fields to entities in bulk is simple and convenient, it can create significant security issues. Bulk assigning user data from the request into an entity allows the user to modify any and all columns. When using anonymous entity classes or creating the entity class with the Bake Console CakePHP does not protect against mass-assignment.

The _accessible property allows you to provide a map of fields and whether or not they can be mass-assigned. The values true and false indicate whether a field can or cannot be mass-assigned:

namespace App\Model\Entity;

use Cake\ORM\Entity;

class Article extends Entity
{
    protected $_accessible = [
        'title' => true,
        'body' => true
    ];
}

In addition to concrete fields there is a special * field which defines the fallback behavior if a field is not specifically named:

namespace App\Model\Entity;

use Cake\ORM\Entity;

class Article extends Entity
{
    protected $_accessible = [
        'title' => true,
        'body' => true,
        '*' => false,
    ];
}

use App\Model\Entity\Article;

$article = new Article(['id' => 1, 'title' => 'Foo'], ['guard' => false]);

// Make user_id accessible.
$article->setAccess('user_id', true);
// Prior to 3.5
$article->accessible('user_id', true);

// Make title guarded.
$article->setAccess('title', false);
// Prior to 3.5
$article->accessible('title', false);

$article->set($fields, ['guard' => false]);

if (!$article->isNew()) {
    echo 'This article was saved already!';
}

$article->isNew(false);

$article->isNew(true);

Lazy Loading Associations¶

While eager loading associations is generally the most efficient way to access your associations, there may be times when you need to lazily load associated data. Before we get into how to lazy load associations, we should discuss the differences between eager loading and lazy loading associations:

Eager loading

Eager loading uses joins (where possible) to fetch data from the database in as few queries as possible. When a separate query is required, like in the case of a HasMany association, a single query is emitted to fetch all the associated data for the current set of objects.

Lazy loading

Lazy loading defers loading association data until it is absolutely required. While this can save CPU time because possibly unused data is not hydrated into objects, it can result in many more queries being emitted to the database. For example looping over a set of articles & their comments will frequently emit N queries where N is the number of articles being iterated.

While lazy loading is not included by CakePHP’s ORM, you can just use one of the community plugins to do so. We recommend the LazyLoad Plugin

After adding the plugin to your entity, you will be able to do the following:

$article = $this->Articles->findById($id);

// The comments property was lazy loaded
foreach ($article->comments as $comment) {
    echo $comment->body;
}

Creating Re-usable Code with Traits¶

You may find yourself needing the same logic in multiple entity classes. PHP’s traits are a great fit for this. You can put your application’s traits in src/Model/Entity. By convention traits in CakePHP are suffixed with Trait so they can be discernible from classes or interfaces. Traits are often a good complement to behaviors, allowing you to provide functionality for the table and entity objects.

For example if we had SoftDeletable plugin, it could provide a trait. This trait could give methods for marking entities as ‘deleted’, the method softDelete could be provided by a trait:

// SoftDelete/Model/Entity/SoftDeleteTrait.php

namespace SoftDelete\Model\Entity;

trait SoftDeleteTrait
{
    public function softDelete()
    {
        $this->set('deleted', true);
    }
}

You could then use this trait in your entity class by importing it and including it:

namespace App\Model\Entity;

use Cake\ORM\Entity;
use SoftDelete\Model\Entity\SoftDeleteTrait;

class Article extends Entity
{
    use SoftDeleteTrait;
}

Converting to Arrays/JSON¶

When building APIs, you may often need to convert entities into arrays or JSON data. CakePHP makes this simple:

// Get an array.
// Associations will be converted with toArray() as well.
$array = $user->toArray();

// Convert to JSON
// Associations will be converted with jsonSerialize hook as well.
$json = json_encode($user);

When converting an entity to an JSON, the virtual & hidden field lists are applied. Entities are recursively converted to JSON as well. This means that if you eager loaded entities and their associations CakePHP will correctly handle converting the associated data into the correct format.

namespace App\Model\Entity;

use Cake\ORM\Entity;

class User extends Entity
{
    protected $_virtual = ['full_name'];
}

$user->setVirtual(['full_name', 'is_admin']);
// Prior to 3.5
$user->virtualProperties(['full_name', 'is_admin']);

namespace App\Model\Entity;

use Cake\ORM\Entity;

class User extends Entity
{
    protected $_hidden = ['password'];
}

$user->setHidden(['password', 'recovery_question']);
// Prior to 3.5
$user->hiddenProperties(['password', 'recovery_question']);

Storing Complex Types¶

Accessor & Mutator methods on entities are not intended to contain the logic for serializing and unserializing complex data coming from the database. Refer to the Saving Complex Types section to understand how your application can store more complex data types like arrays and objects.