コンテンツマイグレーション

Craft プロジェクトが複数の人々によって開発されている場合、または複数の環境で開発されている場合、すべての環境を互いに同期させようとすると、構造の変更を管理するのが少し面倒になることがあります。

コンテンツマイグレーションをはじめてください。コンテンツマイグレーションとは、Craft 本体のアプリケーションやプラグインではなく、Craft プロジェクトのために書かれたり管理されているものに対してのマイグレーションです。

マイグレーションの作成

新しいマイグレーションを作成するために、ターミナルを開き Craft プロジェクトに移動してください。

cd /path/to/project

次のコマンドを実行し、新しいコンテンツマイグレーションファイルを生成します(<MigrationName> を実際のマイグレーション名に置き換えます)。

./craft migrate/create <MigrationName>

TIP

Craft のインストールが Vagrant box から実行されている場合、このコマンドを実行するために box に SSH 接続する必要があります。

TIP

マイグレーション名は有効な PHP クラス名でなければなりません。慣習として、StudlyCase よりも snake_case を使うことをお勧めします。

プロンプトで yes と入力すると、新しいマイグレーションファイルがプロジェクトルートの migrations/ フォルダに作成されます。

内部で行うこと

マイグレーションクラスには safeUp()safeDown() メソッドが含まれます。マイグレーションが 適用される ときに safeUp() が実行され、復帰させる ときに safeDown() が実行されます。

TIP

デフォルトでは、safeDown()false を返します。これは、マイグレーションの復帰はサポートされていないことを意味します。実際のマイグレーション復帰コードに置き換えるか、そのままにしておくかは、あなたの選択次第です。

マイグレーションの目的に応じて、マイグレーションの safeUp()safeDown() メソッドに必要なロジックを入力できます。プラグインやモジュールによって提供されるいかなる API と同様に、 Craft の API へフルアクセスできます。

TIP

Mike Hudson 氏は、新しいカスタムフィールドを作成するような一般的なタスクを実行するいくつかの実例を挙げながら、コンテンツマイグレーションについて素晴らしい記事を書かれています。

データベースデータの操作

マイグレーションクラスは craft\db\Migration を拡張し、データベースを操作するためのいくつかのメソッドを提供しています。マイグレーションメソッドはどちらも使いやすく、ターミナルにステータスメッセージを出力するため、craft\db\Command よりもこれらを使う方が良いでしょう。

// Bad:
$this->db->createCommand()
    ->insert('{{%tablename}}', $rows)
    ->execute();

// Good:
$this->insert('{{%tablename}}', $rows);

WARNING

api:api:yii\db\Migration::insert()batchInsert()、および、update() マイグレーションメソッドは、引数 $columns で指定したものに加えて dateCreateddateUpdateduid テーブルのカラムにあるデータを自動的に挿入 / アップデートします。操作しているテーブルにこれらのカラムがない場合、引数 $includeAuditColumnsfalse を渡して、SQL エラーにならないようにしてください。

TIP

craft\db\Migration はデータを 選択する ためのメソッドを持たないため、Yii のクエリビルダーを通す必要があります。

use craft\db\Query;

$result = (new Query())
    // ...
    ->all();

ロギング

マイグレーションコード内でメッセージを記録したい場合、Craft::info() を呼び出すよりも echo で出力してください。

echo "    > some note\n";

マイグレーションがコンソールリクエストから実行された場合、メッセージがターミナル内に出力されるため、マイグレーションを実行している人がそのメッセージを見ることを保証します。ウェブリクエストであれば、Craft::info() を使用したときと同様に、Craft がそれを取得して storage/logs/ に記録します。

マイグレーションの実行

コンテンツマイグレーションの実行には、ターミナルからとコントロールパネルのマイグレーションユーティリティからの2つの方法があります。

ターミナルからマイグレーションを実行するには、Craft プロジェクトに移動して次のコマンドを実行します。

./craft migrate/up

TIP

Craft のインストールが Vagrant box から実行されている場合、このコマンドを実行するために box に SSH 接続する必要があります。

マイグレーションユーティリティから実行するには、コントロールパネールで「ユーティリティ > マイグレーション」に移動し、「新しいマイグレーションを適用」ボタンをクリックします。