Page Contents

テーブルオブジェクト

テーブルオブジェクト¶

class Cake\ORM\Table

テーブルオブジェクトは特定のテーブルに保存されたエンティティーのコレクションへのアクセスを提供します。それぞれのテーブルは、与えられたテーブルによって繋がれた関連付けられたテーブルクラスを持ちます。もし、与えられたテーブルの振る舞いをカスタマイズする必要ないなら、CakePHP はテーブルのインスタンスを作ります。

テーブルオブジェクトと ORM を作る前に　データベースへの接続がなされているか確かめましょう。

基本的な使い方¶

まずはじめにテーブルクラスを作ってください。これらのクラスは src/Model/Table に作ります。テーブルは、リレーショナルデータベースに特化したモデルコレクションです。そして、CakePHP の ORM の中で、あなたのデータベースへの主なインターフェースです。最も基本的なテーブルクラスは次のようになります。

// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
}

このクラスで使用するテーブル名を ORM に伝えていないことに注目してください。規約により、テーブルオブジェクトは、クラス名を小文字とアンダースコアー区切りにした名前のテーブルを使用します。上記の例では articles テーブルが使用されます。テーブルクラスが BlogPosts という名前の場合、テーブルは blog_posts と名付けてください。あなたは、 setTable() メソッドを使用することでテーブルを指定できます。

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setTable('my_table');
    }
}

テーブルを指定した時は、命名規則は適用されません。規約により、ORM はそれぞれのテーブルが id という名前の主キーを持っていることを前提としています。もし主キーの名前を変更する必要がある場合、 setPrimaryKey() メソッドが使用できます。

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setPrimaryKey('my_id');
    }
}

テーブルが使うエンティティークラスのカスタマイズ¶

デフォルトではテーブルオブジェクトは命名規則に従った Entity クラスを使います。たとえば、 ArticlesTable というテーブルクラスの名前だったらエンティティーは Article に、 PurchaseOrdersTable というテーブルクラスの名前だったらエンティティーは PurchaseOrder になります。もし命名規約に従わない場合は、 setEntityClass() メソッドで設定を変えられます。

class PurchaseOrdersTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setEntityClass('App\Model\Entity\PO');
    }
}

上記の例では、テーブルオブジェクトはコンストラクターの最後に呼ばれる initialize() メソッドを持ちます。コンストラクターをオーバーライドする代わりに、このメソッドで初期化することを推奨します。

テーブルクラスのインスタンスを取得する¶

テーブルにクエリーを実行する前に、テーブルインスタンスを取得する必要があります。 TableLocator クラスを使用することで取得できます。

// コントローラー内で

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

TableLocator はテーブルを作るための様々な依存関係を提供します。そして、作成されたすべてのテーブルインスタンスの設定を維持し、リレーションの構築と ORM の設定を簡単にしてくれます。詳細は TableLocator の利用をご覧ください。

テーブルクラスがプラグインの中にある場合、あなたのテーブルクラスのために正しい名前を必ず使用してください。それに失敗すると、デフォルトのクラスが正しいクラスの代わりに使われてしまい、バリデーションルールやコールバックが呼ばれないなどの結果を生じます。プラグインのテーブルクラスを正しくロードするために、次のように使用してください。

// プラグインの Table
$articlesTable = $this->getTableLocator()->get('PluginName.Articles');

// ベンダープレフィックス付きのプラグイン Table
$articlesTable = $this->getTableLocator()->get('VendorName/PluginName.Articles');

コールバックのライフサイクル¶

上記で示した通り、テーブルオブジェクトは、いろいろなイベントを起こします。イベントは、 ORM 内でフックしたり、サブクラス化やメソッドをオーバーライドせずにロジックを加えたい時に便利です。イベントリスナーはテーブルクラスやビヘイビアークラスで定義できます。また、テーブルのイベントマネージャーをリスナーをバインドするために使えます。

コールバックメソッドを使うとき、 initialize() メソッドで追加されたビヘイビアーは、テーブルコールバックメソッドが開始する前に呼ばれるリスナーを持ちます。これは、コントローラーやコンポーネントと同じ流れに従います。

イベントリスナーにテーブルクラスやビヘイビアーを追加するには、単純にメソッド名を以下の様に使います。イベントサブシステムの使い方の詳細はイベントシステムをご覧ください。:

// コントローラー内で
$articles->save($article, ['customVariable1' => 'yourValue1']);

// ArticlesTable.php内で
public function afterSave(Event $event, EntityInterface $entity, ArrayObject $options)
{
    $customVariable = $options['customVariable1'];  // 'yourValue1'
    $options['customVariable2'] = 'yourValue2';
}

public function afterSaveCommit(Event $event, EntityInterface $entity, ArrayObject $options)
{
    $customVariable = $options['customVariable1'];  // 'yourValue1'
    $customVariable = $options['customVariable2'];  // 'yourValue2'
}

イベント一覧¶

Model.initialize
Model.beforeMarshal
Model.afterMarshal
Model.beforeFind
Model.buildValidator
Model.buildRules
Model.beforeRules
Model.afterRules
Model.beforeSave
Model.afterSave
Model.afterSaveCommit
Model.beforeDelete
Model.afterDelete
Model.afterDeleteCommit

initialize¶

Cake\ORM\Table::initialize(EventInterface $event, ArrayObject $data, ArrayObject $options)¶

Model.initialize イベントは、コンストラクターと initialize メソッドが呼ばれた後に発行されます。デフォルトでは、 Table クラスは、このイベントを購読しません。そして、代わりに initialize フックメソッドを使います。

Model.initialize イベントに応答するために、 EventListenerInterface を実装したリスナークラスを作成することができます。

use Cake\Event\EventListenerInterface;
class ModelInitializeListener implements EventListenerInterface
{
    public function implementedEvents()
    {
        return [
            'Model.initialize' => 'initializeEvent',
        ];
    }

    public function initializeEvent($event): void
    {
        $table = $event->getSubject();
        // ここで何かする
    }
}

そして、以下のように EventManager にリスナーを追加します。

use Cake\Event\EventManager;
$listener = new ModelInitializeListener();
EventManager::instance()->attach($listener);

これは、任意の Table クラスが構築されたとき、 initializeEvent を呼びます。

beforeMarshal¶

Cake\ORM\Table::beforeMarshal(EventInterface $event, ArrayObject $data, ArrayObject $options)¶

Model.beforeMarshal イベントは、リクエストデータがエンティティーに変換される前に発行されます。詳細はエンティティー構築前のリクエストデータ変更をご覧ください。

afterMarshal¶

Cake\ORM\Table::afterMarshal(EventInterface $event, EntityInterface $entity, ArrayObject $data, ArrayObject $options)¶

The Model.afterMarshal イベントは、リクエストデータがエンティティーに変換された後に発行されます。イベントハンドラは、変換されたエンティティ、元のリクエストデータ、および patchEntity() または newEntity() 呼び出しに提供されたオプションを取得します。

バージョン 4.1.0 で追加.

beforeFind¶

Cake\ORM\Table::beforeFind(EventInterface $event, Query $query, ArrayObject $options, $primary)¶

Model.beforeFind イベントは、各検索操作の前に発生します。イベントを停止し、クエリにカスタム結果セットを渡すことにより、検索操作を完全にバイパスできます。:

public function beforeFind(EventInterface $event, Query $query, ArrayObject $options, $primary)
{
    if (/* ... */) {
        $event->stopPropagation();
        $query->setResult(new \Cake\Datasource\ResultSetDecorator([]));

        return;
    }
    // ...
}

この例では、関連するテーブルまたはそのアタッチされたビヘイビアーで beforeFind イベントはトリガーされません。ただし、振る舞いイベントは通常、デフォルトの優先順位が与えられているため、以前に呼び出されます。クエリは Query::setResult() を介して渡された空の結果セットを返します。

イベントを止めて戻り値を返すことで find を完全にバイパスできます。 $query インスタンスに対してなされた全ての変更は find 処理の間維持されます。 $primary パラメーターは、これがルートクエリーなのか、それともアソシエーションのクエリーなのかを示します。クエリーに含まれる全てのアソシエーションで Model.beforeFind イベントが呼ばれます。 JOIN を使うアソシエーションに対しては、ダミーのクエリーが渡されます。イベントリスナーでは、追加のフィールド、検索条件、 JOIN や結果のフォーマッターを設定出来ます。これらのオプションや機能はルートクエリーにコピーされます。

CakePHP の旧バージョンでは afterFind コールバックがありましたが、結果を Map/Reduce で変更する機能とエンティティーのコンストラクターに置き換えられました。

buildValidator¶

Cake\ORM\Table::buildValidator(EventInterface $event, Validator $validator, $name)¶

Model.buildValidator イベントは $name バリデーターが作られた時に発行されます。ビヘイビアーは、バリデーションメソッドに追加するために、このフックが使用できます。

buildRules¶

Cake\ORM\Table::buildRules(EventInterface $event, RulesChecker $rules)¶

Model.buildRules イベントはルールインスタンスが作られた後と、 Table の beforeRules() メソッドが呼ばれた後に発行されます。

beforeRules¶

Cake\ORM\Table::beforeRules(EventInterface $event, EntityInterface $entity, ArrayObject $options, $operation)¶

Model.beforeRules イベントはエンティティーにルールが適用される前に発行されます。このイベントが止まると、チェックのためのルールを停止して、適用したルールの結果をセットすることができます。

afterRules¶

Cake\ORM\Table::afterRules(EventInterface $event, EntityInterface $entity, ArrayObject $options, $result, $operation)¶

Model.afterRules イベントはルールがエンティティーに適用された後に発行されます。このイベントが止まると、操作をチェックするためのルールの結果の値を返すことができます。

beforeSave¶

Cake\ORM\Table::beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.beforeSave イベントはエンティティーが保存する前に発行されます。このイベントを止めることによって、保存を停止できます。イベントが停止すると、このイベントの結果が返されます。

afterSave¶

Cake\ORM\Table::afterSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.afterSave イベントはエンティティーを保存した後に発行されます。

afterSaveCommit¶

Cake\ORM\Table::afterSaveCommit(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.afterSaveCommit イベントは、保存処理がラップされたトランザクションがコミットされた後に発行されます。データベース操作が暗黙的にコミットされる非アトミックな保存でも引き起こされます。イベントは、 save() が直接呼ばれた最初のテーブルだけに引き起こされます。 save が呼ばれる前にトランザクションが始まっている場合、イベントは起こりません。

beforeDelete¶

Cake\ORM\Table::beforeDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.beforeDelete イベントはエンティティーを削除する前に発行されます。このイベントを停止することによって、削除を中止できます。イベントが停止すると、このイベントの結果が返されます。

afterDelete¶

Cake\ORM\Table::afterDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.afterDelete イベントはエンティティーが削除された後に発行されます。

afterDeleteCommit¶

Cake\ORM\Table::afterDeleteCommit(EventInterface $event, EntityInterface $entity, ArrayObject $options)¶

Model.afterDeleteCommit イベントは、削除処理がラップされたトランザクションがコミットされた後に発行されます。データベース操作が暗黙的にコミットされる非アトミックな保存でも引き起こされます。イベントは、 delete() が直接呼ばれた最初のテーブルだけに引き起こされます。 delete が呼ばれる前にトランザクションが始まっている場合、イベントは起こりません。

Stopping Table Events¶

保存を継続しないようにするには、コールバックでイベントの伝搬を停止するだけです:

public function beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)
{
    if (...) {
        $event->stopPropagation();
        $event->setResult(false);
        return;
    }
    ...
}

また、コールバックからfalseを返すこともできます。これはイベントの伝播を止めるのと同じ効果があります。

Callback priorities¶

テーブルやビヘイビアでイベントを使用する際には、優先順位とリスナーが付く順番に注意してください。ビヘイビアイベントは、テーブルイベントの前にアタッチされます。デフォルトの優先順位では、ビヘイビアのコールバックが同名のテーブルイベントの前にトリガーされます。

例えば、テーブルが TreeBehavior を使用している場合、 TreeBehavior::beforeDelete() メソッドは、テーブルの beforeDelete() メソッドよりも先に呼び出されてしまい、テーブルのメソッドで削除される子要素のレコードを操作することはできません。

イベントの優先順位を管理するには、いくつかの方法があります:

priority オプションを使って、ビヘイビアのリスナーの 優先度 を変更します。これは、ビヘイビアの すべての コールバックメソッドの優先度を変更します。

Behavior:
```
// In a Table initialize() method
$this->addBehavior('Tree', [
    // Default value is 10 and listeners are dispatched from the
    // lowest to highest priority.
    'priority' => 2,
]);
```

Model.implementedEvents() メソッドを使用し、 Table クラスの priority を変更します。これにより、コールバック関数ごとに異なる優先度を割り当てることができます:

// In a Table class.
public function implementedEvents()
{
    $events = parent::implementedEvents();
    $events['Model.beforeDelete'] = [
        'callable' => 'beforeDelete',
        'priority' => 3
    ];

    return $events;
}

ビヘイビアー¶

Cake\ORM\Table::addBehavior($name, array $options = [])¶

ビヘイビアーは、テーブルクラスにまたがって関連するロジックの再利用可能な部品を作成する簡単な方法を提供します。なぜビヘイビアーが通常のクラスで、トレイトではないのか不思議に思うかもしれません。第一の理由は、ビヘイビアーはイベントリスナーだからです。トレイトは再利用可能なロジックの部品になりえますが、イベントをバインドするのは厄介です。

ビヘイビアーをテーブルに追加するために addBehavior() メソッドが使えます。一般的に、これを initialize() でやるのがもっともよいです。

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Timestamp');
    }
}

アソシエーションにはプラグイン記法と追加の設定オプションが使えます。

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->addBehavior('Timestamp', [
            'events' => [
                'Model.beforeSave' => [
                    'created_at' => 'new',
                    'modified_at' => 'always'
                ]
            ]
        ]);
    }
}

CakePHP によって提供されるビヘイビアーを含む、ビヘイビアーに関する詳細はビヘイビアーの章をご覧ください。

接続設定¶

デフォルトでは、全てのテーブルインスタンスは default データベース接続を使用します。もし、複数のデータベース接続を使用している場合、どのコネクションを使用してテーブルを設定したくなるでしょう。これは、 defaultConnectionName() メソッドで出来ます。

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public static function defaultConnectionName(): string {
        return 'replica_db';
    }
}

注釈

defaultConnectionName() メソッドはスタティックで なければなりません 。

TableLocator の利用¶

class Cake\ORM\TableLocator¶

これまで見てきたように、TableLocator クラスは　factory/registry をアプリケーションのテーブルインスタンスにアクセスするために使うことを簡単にします。これには他にも便利な機能があります。