Сущности

Сущность (entity) — класс, объект которого представляет одну строку таблицы. Модель по-прежнему ищет и сохраняет записи, но возвращает их не массивами, а объектами. В таком классе удобно держать всё, что относится к одной записи: приведение типов, форматирование, небольшие вычисления. Сущности лежат в папке app/Entities.

Создание сущности

php spark make:entity Post

Команда создаёт файл app/Entities/Post.php. Заготовки уже достаточно для работы:

// app/Entities/Post.php
namespace App\Entities;
 
use CodeIgniter\Entity\Entity;
 
class Post extends Entity
{
}

Перечислять столбцы таблицы в классе не нужно: они становятся свойствами объекта автоматически.

Подключение к модели

Чтобы модель возвращала объекты, в свойстве $returnType указывают класс сущности:

// app/Models/PostModel.php
protected $returnType = \App\Entities\Post::class;

Теперь find() и findAll() возвращают объекты Post, и в шаблоне вместо $post['title'] пишут $post->title:

<!-- app/Views/posts/show.php -->
<h1><?= esc($post->title) ?></h1>
<p><?= esc($post->body) ?></p>

Страница /posts/1 выглядит как прежде, изменился только способ обращения к полям.

Приведение типов

Из базы все значения приходят строками. Свойство $casts превращает их в нужный тип, а $dates — в объекты даты:

// app/Entities/Post.php
class Post extends Entity
{
    protected $casts = [
        'id' => 'integer',
        'status' => 'integer',
    ];
 
    protected $dates = ['created_at', 'updated_at'];
}

После этого $post->status === 1 даёт true, а дату можно форматировать прямо в шаблоне: <?= $post->created_at->format('d.m.Y') ?>.

Свои методы

Метод с именем get и названием свойства вызывается при чтении этого свойства:

public function getExcerpt(): string
{
    return mb_substr($this->attributes['body'], 0, 100) . '…';
}
 
public function isPublished(): bool
{
    return $this->status === 1;
}

В шаблоне <?= esc($post->excerpt) ?> выведет первые сто знаков текста, хотя столбца excerpt в таблице нет. Массив $this->attributes хранит исходные значения строки.

Создание и сохранение

Сущность заполняют данными и передают модели:

$post = new \App\Entities\Post();
$post->fill([
    'title' => 'Новая статья',
    'body' => 'Текст статьи',
]);
 
model(PostModel::class)->save($post);

Метод save() добавит строку в таблицу. Если объект получен из базы и изменён, тот же вызов сохранит только изменённые поля.

Массив или сущность

Сущности необязательны. В следующих уроках курса записи остаются массивами, чтобы примеры были короче.

Частая ошибка

После смены $returnType старые шаблоны с записью $post['title'] перестают работать: объект сущности не является массивом, и PHP сообщит об ошибке. Меняйте способ обращения сразу во всех шаблонах модели. Если нужен именно массив, его возвращает метод $post->toArray().