新 ORM アップグレードガイド¶

Table オブジェクト¶

Table オブジェクトは、データへのゲートウェイです。 彼らは、以前のリリースで Model が行っていた多くのタスクを処理します。 Table クラスは次のようなタスクを処理します。

• クエリーの作成。

• Finder の提供。

• エンティティーのバリデーションと保存。

• エンティティーの削除。

• アソシエーションの定義とアクセス。

• コールバックイベントのトリガー。

• ビヘイビアーとの相互作用。

テーブルオブジェクト の章では、 このガイドよりも、Table オブジェクトを使用する 方法についてはるかに多くの詳細を提供します。一般的に既存のモデルコードを移行する場合、 Table オブジェクトになります。Table オブジェクトは、特定のプラットフォームに依存する SQL は含まれていません。その代わりに、エンティティーやクエリービルダーと連携して動作します。 さらに、Table オブジェクトは、発行されたイベントを通じてビヘイビアーやその他の関連処理と 相互に作用します。

Query オブジェクト¶

あなた自身で構築するクラスはありませんが、あなたのアプリケーションコードは、新しい ORM の 中心である クエリービルダー を広範に使うことになります。 クエリービルダーは、 HAVING 、 UNION 、およびサブクエリーのように、以前の CakePHP では非常に困難であったものを含む、単純または複雑なクエリーを構築することが容易になります。

あなたのアプリケーションの既存の様々な find() 呼び出しは、新しいクエリービルダーを使用するように 更新する必要があります。Query オブジェクトは、自分自身でクエリーを実行せずにクエリーを 作成するためのデータを収容するための責任を負います。出力として ResultSet を 作成するために実行されるプラットフォーム固有の SQL を生成するために、Connection (接続) や Dialect (方言) と連携します。

Entity オブジェクト¶

CakePHP の以前のバージョンの Model クラスは、任意のロジックや動作が含まれていない 単なる配列を返しました。コミュニティー内では CakeEntity のようなプロジェクトで欠点を補うことは できましたが、多くの場合、結果を配列で返すことは、多くの開発者のトラブルの原因となる欠点でした。 CakePHP 3.0 の場合、あなたが明示的にその機能を無効にしない限り、 ORM は常にオブジェクトの 結果セットを返します。 エンティティー の章はあなたのエンティティーで実行できる 様々なタスクをカバーしています。

エンティティーは、次のいずれかの方法で作成されます。データベースからデータのロード、 またはリクエストデータからエンティティーへの変換のいずれかです。 エンティティーを一度作成すると、それらに含まれるデータを操作したり、Table オブジェクトと 連携して、それらのデータを永続化することを可能にします。

語形変化 (Inflection) 規則の更新¶

あなたは、 Table クラスが複数形の名前であることに気づいたかもしれません。 複数形の名前を持つテーブルに加えて、アソシエーションもまた、複数形で呼ばれています。 これは、クラス名とアソシエーションの別名が単数形だった Model と対照的です。 この変更には、いくつかの理由があります。

• Table クラスは、単一の行ではなく、データの 集合 を表します。

• アソシエーションは、多くのものの間の関係を記述するために、テーブルを互いにリンクします。

Table オブジェクトの規約は常に複数形を使用することですが、あなたのエンティティーの関連付け プロパティーは、アソシエーションのタイプに基づいて入力されます。

Table オブジェクトの規約の変更は、クエリーを構築するときに最も明白です。 以下のようなクエリー表現の代わりに:

// 誤り
$query->where(['User.active' => 1]);

複数形を使用してください:

// 正しい
$query->where(['Users.active' => 1]);

find は Query オブジェクトを返します¶

新しい ORM での1つの重要な違いは、テーブルの find を呼び出すと、すぐに結果を返さずに、 Query オブジェクトを返すということです。これにはいくつかの目的があります。

find を呼び出した後、さらにクエリーを変更することができます。

// Prior to 3.6 use TableRegistry::get('Articles')
$articles = TableRegistry::getTableLocator()->get('Articles');
$query = $articles->find();
$query->where(['author_id' => 1])->order(['title' => 'DESC']);

クエリーが実行される前に、同じクエリーに条件、並び替え、制限、その他の句を追加するために カスタム finder を積み重ねることができます。

$query = $articles->find('approved')->find('popular');
$query->find('latest');

これまで以上に簡単にサブクエリーを作成するために、クエリーの中に別のクエリーを構成することができます。

$query = $articles->find('approved');
$favoritesQuery = $article->find('favorites', ['for' => $user]);
$query->where(['id' => $favoritesQuery->select(['id'])]);

データベースに触れることなくイテレータとメソッドの呼び出しを使用してクエリーを飾ることができます。 ビューのキャッシュを保持していて、データベースから取得された結果が実際には必要ない場合に、 これは素晴らしいです。

// この例では、クエリーを作成しませんでした！
$results = $articles->find()
    ->order(['title' => 'DESC'])
    ->formatResults(function (\Cake\Collection\CollectionInterface $results) {
        return $results->extract('title');
    });

クエリーを反復処理しようとする時や、 toArray() や Collection を継承したメソッドを呼び出した時、 クエリーは結果オブジェクトとみなされ、実行されるクエリーや返す結果の中に結果として返します。

CakePHP 2.x から見て最大の違いは、 find('first') は、もはや存在しないということです。 そこで、わずかな修正があります。それは first() メソッドです。

// 旧
$article = $this->Article->find('first');

// 新
$article = $this->Articles->find()->first();

// 旧
$article = $this->Article->find('first', [
    'conditions' => ['author_id' => 1]
]);

// 新
$article = $this->Articles->find('all', [
    'conditions' => ['author_id' => 1]
])->first();

// 以下のようにも書けます
$article = $this->Articles->find()
    ->where(['author_id' => 1])
    ->first();

主キーによって単一のレコードをロードする場合は、 get() を呼び出すだけの方がよいでしょう。

$article = $this->Articles->get(10);

Finder メソッドの変更¶

find メソッドから Query オブジェクトを返すことはいくつかの利点がありますが、 2.x から移行する人にとってはコストがかかります。あなたのモデルにいくつかの カスタム find メソッドを持っていた場合、それらはいくつかの変更が必要になります。 これは、3.0 でカスタム finder メソッドを作成する方法です。

class ArticlesTable
{

    public function findPopular(Query $query, array $options)
    {
        return $query->where(['times_viewed' > 1000]);
    }

    public function findFavorites(Query $query, array $options)
    {
        $for = $options['for'];
        return $query->matching('Users.Favorites', function ($q) use ($for) {
            return $q->where(['Favorites.user_id' => $for]);
        });
    }
}

見ての通り、カスタム finder メソッドは、とても簡単で、配列の代わりに Query オブジェクトを 取得し、 必ず Query オブジェクトを返します。カスタム finder に afterFind ロジックを 実装した 2.x のユーザーのためには、 結果を Map/Reduce で変更する セクションを確認したり、 コレクションオブジェクト 上で見られる機能を 使用すべきです。あなたのモデルで、すべての find の操作のために afterFind を行うことに 依存していた場合、いくつかの方法のいずれかでこのコードを移行できます。

1. あなたのエンティティーのコンストラクターメソッドをオーバーライドして、そこに追加の書式設定を行います。

2. バーチャルプロパティーを作成するには、エンティティーにアクセサーメソッドを作成します。

3. findAll() を再定義して、 formatResults を使用します。

上記の第三の場合のあなたのコードは以下のようになります。

public function findAll(Query $query, array $options)
{
    return $query->formatResults(function (\Cake\Collection\CollectionInterface $results) {
        return $results->map(function ($row) {
            // あなたの afterfind ロジック
        });
    })
}

カスタム finder はオプション配列を受け取ることに気づいたかもしれません。 このパラメーターを使用して、finder に追加の情報を渡すことができます。 これは、2.x のから移行する人々にとって素晴らしいニュースです。 以前のバージョンで使用されたクエリーのいずれかのキーは、3.x では正しい機能に自動的に変換されます。

// これは CakePHP 2.x と 3.0 の両方で動作します
$articles = $this->Articles->find('all', [
    'fields' => ['id', 'title'],
    'conditions' => [
        'OR' => ['title' => 'Cake', 'author_id' => 1],
        'published' => true
    ],
    'contain' => ['Authors'], // 変更はここだけ！(複数形に注意)
    'order' => ['title' => 'DESC'],
    'limit' => 10,
]);

アプリケーションが「マジック」または 動的な Finder を使用している場合、 あなたはそれらの呼び出しを改造する必要があります。3.x では findAllBy* メソッドは 削除され、代わりに findBy* が常に Query オブジェクトを返します。 最初の結果を取得するには、 first() メソッドを使用する必要があります。

$article = $this->Articles->findByTitle('A great post!')->first();

うまくいけば、旧バージョンからの移行は、それが最初に思ったほど困難ではありません。 私たちが追加した機能の多くは、あなたが新しい ORM を使用して、要件をより良く表現することが できるようにコードを減らすと同時に、互換性のラッパーはあなたが迅速かつ楽な方法でコードの 書き換えを少なくするのに役立ちます。

3.x での finder メソッド周りその他の素敵な改良点の一つは、簡単にビヘイビアーで finder メソッドを実装することができるということです。ビヘイビアーに一致する名前とシグネチャを 持つメソッドを定義することにより finder は自動的に動作が接続されているすべてのテーブル上で 利用できるようになります。

Recursive と ContainableBehavior の削除¶

CakePHP の以前のバージョンでは、あなたが関心があるアソシエーションのセットとしてロードされた データを削減するためには recursive、 bindModel()、 unbindModel() と ContainableBehavior を使用する必要がありました。 アソシエーションを管理するための一般的な戦術は recursive に -1 を設定し、 すべてのアソシエーションを管理するために Containable を使用することでした。 CakePHP 3.0 では、 ContainableBehavior、recursive、bindModel、および unbindModel は すべて削除されました。代わりに contain() メソッドが、クエリービルダーのコア機能に 昇格されました。彼らは明示的にオンになっている場合のみ、アソシエーションはロードされます。 例えば:

$query = $this->Articles->find('all');

上記は、アソシエーションが含まれない articles テーブルから のみ データを ロードします。あなたが articles とそれに関連する作者をロードするには:

$query = $this->Articles->find('all')->contain(['Authors']);

特に必要とされる関連データのみをロードすることで、あなたの欲しいデータのみを取得しようと ORM と悪戦苦闘せずに済みます。

afterFind イベントやバーチャルフィールドはありません¶

CakePHP の以前のバージョンでは、生成されたデータのプロパティーを作成するために afterFind コールバックやバーチャルフィールドを広範囲に使用する必要がありました。 これらの機能は 3.0 で削除されました。ResultSet が反復的にエンティティーを生成するため、 afterFind コールバックは不可能でした。afterFind とバーチャルフィールドの両方の大部分は エンティティーのバーチャルプロパティーに置き換えることができます。 例えば、あなたの User エンティティーが姓と名のカラムの両方を持っている場合、 full_name ためのアクセサーを追加し、動的にプロパティーを生成することができます。

namespace App\Model\Entity;

use Cake\ORM\Entity;

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

定義されたら、 $user->full_name を使用して、新しいプロパティーにアクセスすることができます。 ORM の 結果を Map/Reduce で変更する 機能を使用すると、結果から集約されたデータを構築することができます。 afterFind コールバックがしばしば使用された別のユースケースです。

バーチャルフィールドはもはや ORM の強調すべき特徴ではありません。finder メソッドで、 計算されたフィールドを追加することは簡単です。クエリービルダーと式オブジェクトを使用することで、 バーチャルフィールドで得られたのと同じ結果を得ることができます。

namespace App\Model\Table;

use Cake\ORM\Table;
use Cake\ORM\Query;

class ReviewsTable extends Table
{
    public function findAverage(Query $query, array $options = [])
    {
        $avg = $query->func()->avg('rating');
        $query->select(['average' => $avg]);
        return $query;
    }
}

アソシエーションはプロパティーとして定義されなくなりました¶

CakePHP の以前のバージョンでは、あなたのモデルが持っていた様々なアソシエーションが $belongsTo や $hasMany などのプロパティーで定義されていました。 CakePHP 3.0 では、アソシエーションはメソッドを使用して作成されます。 メソッドを使用することで、クラス定義が持っている多くの制限を回避し、アソシエーションを 定義する唯一の方法を提供することができます。 あなたの initialize() メソッドとアプリケーションコードの他のすべての部分は、 アソシエーションを操作するとき、同じ API でやり取りします。

namespace App\Model\Table;

use Cake\ORM\Table;
use Cake\ORM\Query;

class ReviewsTable extends Table
{

    public function initialize(array $config)
    {
        $this->belongsTo('Movies');
        $this->hasOne('Ratings');
        $this->hasMany('Comments')
        $this->belongsToMany('Tags')
    }

}

上記の例からわかるように、各アソシエーションタイプは関連付けを作成するためのメソッドを使用します。 もう一つの違いは、 hasAndBelongsToMany が belongsToMany に名前が変更されたことです。 3.0 でアソシエーションを作成する方法についての詳細を調べるには、アソシエーション - モデル同士を繋ぐ 上のセクションをご覧ください。

CakePHP の別のうれしい改善は、独自のアソシエーションクラスを作成する機能です。 組み込みの関連付けタイプでカバーされていないアソシエーションタイプを持っている場合、 独自の Association サブクラスを作成し、必要な関連付けロジックを定義することができます。

バリデーションはプロパティーとして定義されなくなりました¶

CakePHP の以前のバージョンでは、アソシエーションと同様に、バリデーションルールは クラスプロパティーとして定義されていました。 この配列は、遅延して ModelValidator オブジェクトに変換されることになります。 この変換ステップは、間接のレイヤーを追加しました。複雑なルールは、実行時に変更します。 さらに、プロパティーとして定義されたバリデーションルールは、モデルにとってバリデーションルールの 複数セットを持つことが難しくなります。 CakePHP 3.0 では、これらの両方の問題が改善されてきました。 バリデーションルールは常に Validator オブジェクトで構築され、簡単に複数のルールのセットを 持たせられます。

namespace App\Model\Table;

use Cake\ORM\Table;
use Cake\ORM\Query;
use Cake\Validation\Validator;

class ReviewsTable extends Table
{

    public function validationDefault(Validator $validator)
    {
        $validator->requirePresence('body')
            ->add('body', 'length', [
                'rule' => ['minLength', 20],
                'message' => 'Reviews must be 20 characters or more',
            ])
            ->add('user_id', 'numeric', [
                'rule' => 'numeric'
            ]);
        return $validator;
    }

}

必要な数のバリデーションメソッドを定義することができます。各メソッドは validation プレフィックスと $validator 引数を受け付けなければなりません。

CakePHP の以前のバージョンでは、「バリデーション」および関連するコールバックは、 いくつかの関連しつつも異なる用途をカバーしました。 CakePHP 3.0 では、バリデーションと呼ばれていたものは、現在は２つの概念に分割されています。

1. データ型とフォーマットのバリデーション。

2. アプリケーション、またはビジネス・ルールの実施。

ORM エンティティーがリクエストデータから作成される前に、バリデーションは適用されます。 この手順は、データがデータ型、書式、およびあなたのアプリケーションが期待する基本的な形状と 一致することを保証できます。 validate オプションを使用してエンティティーにリクエストデータを変換するときに、 あなたのバリデータを使用することができます。 詳細については、 リクエストデータのエンティティーへの変換 上のドキュメントをご覧ください。

アプリケーションルール は、あなたのアプリケーションのルール、 状態、およびワークフローが適用されることを保証するルールを定義することができます。 ルールは、あなたの Table の buildRules() メソッドで定義されています。 ビヘイビアーは buildRules() フックメソッドを使用してルールを追加することができます。 articles テーブルの buidRules() メソッドの例は、以下の通りです。

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

use Cake\ORM\Table;
use Cake\ORM\RulesChecker;

class ArticlesTable extends Table
{
    public function buildRules(RulesChecker $rules)
    {
        $rules->add($rules->existsIn('user_id', 'Users'));
        $rules->add(
            function ($article, $options) {
                return ($article->published && empty($article->reviewer));
            },
            'isReviewed',
            [
                'errorField' => 'published',
                'message' => 'Articles must be reviewed before publishing.'
            ]
        );
        return $rules;
    }
}

識別子のクォートはデフォルトで無効¶

以前の CakePHP は常に識別子を引用符で囲んでいました。 SQL スニペットを解析し、識別子を引用符で囲もうとすると、エラーが発生しやすく、重い処理でした。 CakePHP が定めた規約に従っている場合は、識別子を引用符で囲むコストは、それが提供する任意の 利益をはるかに上回ります。このため、識別子を引用符で囲むことは、3.0 ではデフォルトで無効に なっています。特殊文字や予約語が含まれているカラム名やテーブル名を使用している場合にのみ 識別子のクォートを有効にする必要があります。 必要な場合は、接続を設定するときに識別子のクォートを有効にすることができます。

// config/app.php 内で
'Datasources' => [
    'default' => [
        'className' => 'Cake\Database\Driver\Mysql',
        'username' => 'root',
        'password' => 'super_secret',
        'host' => 'localhost',
        'database' => 'cakephp',
        'quoteIdentifiers' => true
    ]
],

新しい基本クラス¶

ビヘイビアーのための基本クラスが変更されました。 ビヘイビアーは現在 Cake\ORM\Behavior を継承する必要があります。ビヘイビアーが、 このクラスを継承しない場合は、例外が発生します。基本クラスの変更に加えて、 ビヘイビアーのコンストラクターが変更されて、 startup() メソッドは削除されました。 テーブルにアクセスする必要があるビヘイビアーは、テーブルとのアタッチをコンストラクターで 定義する必要があります。

namespace App\Model\Behavior;

use Cake\ORM\Behavior;

class SluggableBehavior extends Behavior
{

    protected $_table;

    public function __construct(Table $table, array $config)
    {
        parent::__construct($table, $config);
        $this->_table = $table;
    }

}

ミックスインメソッドのシグネチャ変更¶

ビヘイビアーは、Table オブジェクトへの「ミックスイン」メソッドを追加する機能の提供を続けます。 しかし、これらのメソッドのメソッドシグネチャが変更されました。 CakePHP 3.0 では、ビヘイビアーのミックスインメソッドは、テーブルの 'メソッド' と 同じ 引数を提供することが期待できます。例えば:

// ビヘイビアーによって提供される slug() メソッドをテーブルが持っていると仮定
$table->slug($someValue);

ビヘイビアーの slug() メソッドは1つだけ引数を受け取り、そのメソッドのシグネチャは 次のようになります。

public function slug($value)
{
    // ここにコード
}

コールバックメソッドのシグネチャ変更¶

ビヘイビアーのコールバックは、他のすべてのリスナーメソッドで統一されています。 以前の引数の代わりに、最初の引数としてイベントオブジェクトを受け取る必要があります。

public function beforeFind(Event $event, Query $query, array $options)
{
    // コード
}

ビヘイビアーが購読することができるすべてのコールバックのシグネチャに関しては コールバックのライフサイクル をご覧ください。