エンティティー¶

エンティティークラスの生成¶

CakePHP の ORM を使うためにエンティティークラスを生成する必要はありません。 しかし、使用するエンティティーでロジックをカスタマイズしたいなら、クラスを作る必要があります。 慣例通りなら src/Model/Entity/ にクラスが存在しています。 もし、 articles テーブルが存在するなら、以下のエンティティーが作れます。

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

use Cake\ORM\Entity;

class Article extends Entity
{
}

今のところ、このエンティティーは何も出来ません。とはいえ、データを article テーブルからロードすれば、 このクラスのインスタンスを得られます。

エンティティー生成¶

直接、エンティティーのインスタンスを生成できます。

use App\Model\Entity\Article;

$article = new Article();

エンティティーからインスタンスを生成する時、インスタンスに必要なプロパティーを渡すことができます。

use App\Model\Entity\Article;

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

エンティティーを生成するお勧めの方法は、 Table オブジェクトの newEntity() メソッドです。

use Cake\ORM\TableRegistry;

$article = TableRegistry::getTableLocator()->get('Articles')->newEmptyEntity();

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

$article は、 App\Model\Entity\Article のインスタンスになります。もしくは Article クラスが作成しなかった場合は、代替として Cake\ORM\Entity のインスタンスになります。

エンティティーのデータへのアクセス¶

エンティティーは保有するデータにアクセスするいくつかの方法を提供します。 最も一般的なのは、オブジェクトの表記を使ってエンティティー内のデータにアクセスすることです。

use App\Model\Entity\Article;

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

また、 get() と set() メソッドも使えます。

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

set() を使う時、一つの配列で複数のプロパティーを一度に更新できます。

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

has() を使ってエンティティーにプロパティが定義されているかどうかを確認できます。

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

has() メソッドは、プロパティが定義されていてヌル以外の値を持つ場合、 true を返します。 isEmpty() と hasValue() を使って、プロパティに '空でない' 値が含まれているかどうかを 調べることができます。

$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

アクセサーとミューテーター¶

シンプルな get/set インターフェイスに加えて、エンティティーは アクセサーメソッドとミューテーターメソッドを提供できるようになっています。 これらのメソッドは、プロパティーがどうやってセットされたり、読まれたりするかを カスタマイズするために使えます。

アクセサーは _get + フィールド名のキャメルケースという命名ルールを使います。

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

このメソッドは唯一の引数として _fields 配列内にある基本の値を受け取ります。 アクセサーはエンティティーを保存する際に使われますので、データをフォーマットするメソッド を定義する場合は注意が必要です。データはフォーマットされた状態で保存されることになります。 例えば、

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

アクセサーは以下の２つの方法でプロパティーを取得する際に実行されます。

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

ミューテーターを定義することによって、プロパティーの設定方法をカスタマイズできます。

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

ミューテーターは常にプロパティーに保存すべき値を返すようにしてください。 上の例のように、ミューテーターを使って他の計算されたプロパティーを設定することもできます。 これをする際に、呼び出しがループしてしまわないように注意して下さい。CakePHP はミューテーターの 無限ループを防ぐことが出来ません。

ミューテーターによりセットされるプロパティーを変換したり、 計算されたデータを作成したりすることができるようになります。ミューテーターとアクセサーは オブジェクト表記や、 get() や set() を使ってプロパティーが読まれた場合に適用されます。 例えば、

namespace App\Model\Entity;

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

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

}

ミューテーターは、以下の２つの方法でプロパティーを設定するときに実行されます。

$user->title = 'foo'; // 同時に slug が設定されます。
$user->set('title', 'foo'); // 同時に slug が設定されます。

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;

エンティティーが変更されたかチェックする¶

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

エンティティーのプロパティーが変更されたかどうかに応じるコードを 作りたいと思うことがあるかもしれません。例えば、フィールドが変更された時にだけ バリデートしたい場合です。

// タイトルが変更された時に
$article->isDirty('title');

フィールドに変更されたという印をつける事もできます。これは配列のプロパティーに追加した場合に便利です。

// コメントを追加して、フィールドが変更されたと印をつけます。
$article->comments[] = $newComment;
$article->setDirty('comments', true);

加えて、 getOriginal() メソッドを使うことで元のプロパティー値に応じたコードを書くこともできます。 このメソッドは値が変更されているなら元の値を返し、そうでなければ実際の値を返します。

また、エンティティー内のプロパティーのいずれかが変化したかをチェックすることもできます。

// エンティティーが変更されたか確かめる
$article->isDirty();

clean() メソッドで不必要な印をエンティティーのフィールドから除去できます。

$article->clean();

オプションを追加で渡すことで、フィールドに印が付くのを避けることができます。

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

Entity の全ての変更されたプロパティーの一覧を取得するには、次のように呼ぶことができます。

$dirtyFields = $entity->getDirty();

バリデーションエラー¶

エンティティーの保存 がされた後、どんなバリデーションエラーも エンティティー自身に保存されます。バリデーションエラーには getErrors() や getError() 、 hasErrors() メソッドを使ってアクセスできます。

// エラーの取得
$errors = $user->getErrors();

// １つのフィールドのエラーを取得
$errors = $user->getError('password');

// エンティティーまたはネストされたエンティティーにエラーがあるか
$user->hasErrors();

// ルートエンティティーのみにエラーがあるか
$user->hasErrors(false);

setErrors() や setError() はまたエンティティーにエラーをセットするために使うこともできます。 これにより、エラーメッセージで動くコードのテストが簡単になります。

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

一括代入 (Mass Assignment)¶

一括でエンティティーのプロパティーを設定するのは単純で便利ですが、 これには重大なセキュリティ問題が伴います。 リクエストからユーザーデータをエンティティーへと一括代入してしまうと、 ユーザーはどの列でも変更できるようになってしまいます。 匿名のエンティティークラスを使ったり、 Bake コンソール でエンティティーを生成すると、 CakePHP は一括代入から保護しません。

_accessible プロパティーにより、プロパティーと一括代入できるかどうかのマップを提供できるようになります。 true と false の値はそれぞれ、その列が一括代入できるか、できないかを示しています。

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

具体的なフィールドに加え、名前が指定されなかった場合の受け皿となる * という特別なフィールドが 存在します。

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

use App\Model\Entity\Article;

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

// user_id にアクセスできるようにする
$article->setAccess('user_id', true);

// title を保護する。
$article->setAccess('title', false);

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

if (!$article->isNew()) {
    echo '既に保存されました!';
}

$article->setNew(false);

$article->setNew(true);

アソシエーションの Lazy ローディング¶

アソシエーションの eager ローディングは大抵の場合において最も有効なアクセス法ではありますが、 アソシエーションデータを lazy ロードしたいときもあるかもしれません。 この方法を見ていく前に、 eager ローディングと lazy ローディングの違いを見てみましょう:

Eager ローディング

できるだけ 少ない クエリーでDBから情報を取得できるようにJOINを（可能なときは）使います。 HasMany アソシエーションを使うような分割したクエリーが必要なときは、1つのクエリーで、 現在のオブジェクト一式に必要な 全て の関連データを取ってこようとします。

Lazy ローディング

絶対に必要になるまでアソシエーションのロードを遅延させます。 これにより、不要なデータがオブジェクト化されないので CPU 時間を節約できますが、 大量のクエリーがDBに送られることになるかもしれません。 例えば、 複数の記事 (articles) とそれに属するコメント (comments) を舐めるループでは、 イテレートされた記事の数だけクエリーが何度も送られることになります。

CakePHP の ORM には lazy ローディングは含まれませんが、実現するためにコミュニティープラグインの １つを使うことができます。私たちは LazyLoad プラグイン をお勧めします。

あなたのエンティティーにプラグインを追加した後、以下のようにできます。

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

// comments プロパティーは lazy ロードされます。
foreach ($article->comments as $comment) {
    echo $comment->body;
}

トレイトを使った再利用可能なコードの生成¶

いくつかのエンティティークラスで同じロジックを使わなければならないことに気づくことがあるでしょう。 PHP のトレイトはこういった場合に威力を発揮します。 src/Model/Entity に自作のトレイトを 置くことができます。慣習的に CakePHP のトレイトは末尾に Trait が付いていますので、 クラスやインターフェイスでないことが判るようになっています。トレイトは振る舞いを補完するもので、 これを使うことで、テーブルオブジェクトやエンティティーオブジェクトに機能を提供できるようになっています。

例えば、 SoftDeletable プラグインを使っていたとして、これがトレイトを提供します。 このトレイトは、エンティティーに 'deleted' マークを付けるためのメソッドを提供します。 softDelete メソッドがトレイトにより提供されるのです。

// SoftDelete/Model/Entity/SoftDeleteTrait.php

namespace SoftDelete\Model\Entity;

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

}

そして、このトレイトをインポートし、インクルードすることで、独自のエンティティークラスで使えます。

namespace App\Model\Entity;

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

class Article extends Entity
{
    use SoftDeleteTrait;
}

配列や JSON への変換¶

API を作る時、しばしば、エンティティーを配列や JSON に変換する必要があるでしょう。 CakePHP では以下のように簡単にできます。

// 配列を取得します。
// アソシエーションも toArray() で変換されます。
$array = $user->toArray();

// JSON に変換します。
// アソシエーションも jsonSerialize フックで変換されます。
$json = json_encode($user);

エンティティーを JSON へと変換する際に、仮想 (virtual) フィールドや隠し (hidden) フィールドの リストが適用されます。エンティティーは再帰的に JSON へと変換されます。これは、エンティティーと アソシエーションを eager ロードする場合、CakePHP は関連データを正しいフォーマットへと 正しく変換できることを意味します。

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

$user->setVirtual(['full_name', 'is_admin']);

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

$user->setHidden(['password', 'recovery_question']);

複合型の保存¶

DB の複合型のデータをシリアライズ/デシリアライズするためのロジックが エンティティーのアクセサーとミューテーターに含まれることは想定されていません。 配列型やオブジェクト型のような複合的なデータ型をどうやって保存するのかを理解するには 複雑な型の保存 を参照して下さい。