アップグレードAPI (Dev docs)

提供:MoodleDocs
移動先:案内検索
重要:

このページの内容は更新され、新しいMoodle Developer Resourcesに移行されました。このページに含まれる情報は、もはや最新であるとみなされるべきではありません。

このページを新サイトで閲覧する そして より多くのコンテンツを新サイトに移行するために協力する というのはいかがでしょうか!


(このページは現在翻訳中です。)

アップグレード API は、プラグインが自身のバージョンを追跡することで、インストールとアップグレードを行う方法です。

はじめに

あなたのプラグインにこの API を実装することで、あなたが管理者通知ページ (.../admin/index.php) を訪れたときに、Moodle はあなたに代わって自動的にデータベーステーブルを作成します。

この処理は、プラグイン内の3つのファイルによって制御されます (他にも様々なことに使用できるオプションのファイルがあります。これらはこのドキュメントの最後で説明します。):

version.php
これはプラグインコードのバージョンを記録します (注意: v2.0以下のMoodleインストールでは、ブロックの init() メソッドが返すバージョン番号を使用するため、これは必要ありません - ブロック開発ページをご覧ください)。新しいバージョンは、アップグレード手順の引き金となり、すべてのキャッシュをリセットするため、/db/ フォルダでの変更、javascript コードでの変更、新しい自動ロードクラス、新しい設定、言語パックでの変更の後に version.php でバージョンを増加させる必要があります。
db/install.xml
これは、誰かがあなたのプラグインを初めてインストールするときに使用されます。
db/upgrade.php
これは、古いバージョンのプラグインをインストールしていた人が、最新バージョンにアップグレードするときに使用されます。

さらに、Moodle は各プラグインの現在インストールされているバージョンもデータベースに保存します。

Moodle 1.x では、この値は mdl_config テーブルの plugintype_pluginname_version という名前の行に保存されます。例えば、qtype_myqtype_versionです。ただし、モジュールとブロックは例外です。インストールされているモジュールのバージョン番号は mdl_modules テーブルに格納されています。ブロックのバージョン番号は mdl_block に格納されています。

Moodle 2.x では、プラグインのバージョン番号は mdl_config_plugins テーブルに格納され、plugin カラムには plugintype_pluginname 、name カラムには 'version' が格納されます。

具体的な例

この文書の残りの部分では、説明が容易になるはずなので、特定の例を使用することにします。どのように一般化できるかがわかるはずです。

ここでは、新しい問題タイプ myqtype を作成すると仮定します。これはプラグインタイプの qtype で、コードは question/type/myqtype フォルダに入ります。現在インストールされているバージョン番号は、mdl_config_plugins テーブルの ('qtype_myqtype', 'version') 行に格納されます。

さらに、このプラグインの最初の2つのリリースを検討します。最初のリリースはバージョン番号 2008080100 で、2つのカラム col1 と col2 を持つデータベーステーブル mdl_myqtype_options を 1 つだけ使用する予定です。次に、2回目のリリースが 2008080200 であると仮定します。その場合、mdl_myqtype_options テーブルに newcol という追加の列を追加することが必要になります。

最初のリリースに必要なファイル

以下の説明では、置き換える必要のあるコードの部分を 太字 にしています。

version.php
$plugin->version  = 2008080100; // 本日の日付 (YYYYMMDD 形式) +2 桁の追加数値
$plugin->requires = XXXXXXXXXX; // Moodle バージョン - トップレベルの version.php ファイルの $version からコピーします。
バージョン番号は通常、YYYYMMDD 形式の当日の日付と、その後に続く2桁の数字で構成され、同じ日に複数のバージョンを持つことができます。例えば、2010年9月15日には、2010091500、2010091501、2010091502などのバージョンを持つことが可能です。
db/install.xml
このファイルはXMLDB エディタで作成し、mdl_myqtype_options テーブルの定義と、col1、col2の2つのカラムが含まれている必要があります。

この段階では、db/upgrade.php ファイルは必要ありません。

2回目のリリースに必要なファイル

version.php
$plugin->version  = 2008080200;
$plugin->requires = XXXXXXXXXX; // トップレベルの version.php ファイルから現在の値をコピーします。
db/install.xml
このファイルには、mdl_myqtype_options テーブルの定義が更新され、3 つの列 col1、col2、newcol が含まれるようになります。このファイルは XMLDB エディタを使って変更します。
db/upgrade.php
このファイルには、あなたのプラグインのバージョン 2008080100 からアップグレードするために実行する必要があるコードが含まれているはずです。つまり、mdl_myqtype_options テーブルにカラム newcol を追加するコードです。このコードは XMLDB エディタが生成してくれるので、自分で書く必要はありません。upgrade.php ファイルには、次のような関数 xmldb_qtype_myqtype_upgrade がひとつだけ含まれているはずです:
function xmldb_qtype_myqtype_upgrade($oldversion) {
    global $DB;

    $dbman = $DB->get_manager();
 
    if ($oldversion < 2015031200) {
        // XMLDB エディタの 'View PHP Code' オプションで生成される、カラムを追加するコード。'''

        upgrade_plugin_savepoint(true, 2015031200, 'qtype', 'myqtype');
    }

    return true;
}

ヒント: フィールド/テーブルを修正または追加する場合、エディタで変更した に、XMLDB エディタに PHP アップデートコードを生成してもらいます。削除する場合は、変更する にPHPコードを生成する必要があります - さもないと、コードを書くフィールド/テーブルがもはや存在しないため、選択できなくなります。

ユーザがプラグインをインストールまたはアップグレードしたときの動作について

管理者が管理者通知ページ(.../admin/index.php)にアクセスすると、このプロセスが発生します。作業を行うコードは lib/upgradelib.php の upgrade_plugins 関数で、このコードを読むことが、何が起こっているかを正確に知るための最良の方法となります。擬似コードで言うと、何をするかというと:

For each plugin of this type (e.g. all qtype plugins) {
    // このループの本体では、現在処理されているプラグインが myqtype であるとします。

    Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

    if (get_config('qtype_myqtype', 'version') exists, and is less than the number in version.php) {
        Call the upgrade function xmldb_qtype_myqtype_upgrade from upgrade.php,
                passing the old version number that says what is currently installed
        set_config('version', latest number from version.php, 'qtype_myqtype')
                to record what is currently installed

    } else if (get_config('qtype_myqtype', 'version') does not exist) {
        Create the tables from the definitions in install.xml
        set_config('version', latest number from version.php, 'qtype_myqtype')
                to record what is currently installed
    }
}

もちろん、それよりも少し複雑です。しかし、 upgrade_plugins のコードは非常にわかりやすいので、ぜひそれを見て、どのように動作するかの詳細をすべて確認してください。

それでは、いくつかの例を見てみましょう:

ユーザによる myqtype のバージョン 2008080100 のインストール

そもそも mdl_myqtype_options が存在しないので、mdl_config_plugins テーブルに ('qtype_myqtype', 'version') 行が存在しないことになります。

  1. ユーザは、myqtype.zip を question/type フォルダに解凍することになります。
  2. ユーザは、管理者通知ページにアクセスします。
  3. これにより、Moodle はアップグレードするプラグインを検索するようになります。qtype_myqtype プラグインのコードが存在することがわかりますが、データベースにはその痕跡がないため、install.xml ファイルからプラグインをインストールすることになります。

この処理の結果、mdl_myqtype_options テーブルには col1 と col2 の2つの列が存在し、mdl_config_plugins テーブルの ('qtype_myqtype', 'version') 行には 2008080100 が含まれることになります。

ユーザによる myqtype のバージョン 2008080100 からバージョン 2008080200 へのアップグレード

まず、mdl_myqtype_options テーブルには col1 と col2 の2つの列が存在し、mdl_config_plugins テーブルの ('qtype_myqtype', 'version') 行には 2008080100 が格納されます。

  1. ユーザは、古い question/type/myqtype フォルダを削除します。
  2. ユーザは、新しい myqtype.zip を question/type フォルダに解凍することになります。
  3. ユーザは、管理者通知ページにアクセスします。
  4. これにより、Moodle はアップグレードするプラグインを検索するようになります。バージョン 2008080200 の qtype_myqtype プラグインのコードが存在することがわかりますが、データベーステーブル ('qtype_myqtype', 'version') のインストールされたバージョンは 2008080100 です。したがって、upgrade.php から xmldb_qtype_myqtype_upgrade を呼び出し、$oldversion 引数として 2008080100 を渡すことになります。

この処理の結果、mdl_myqtype_options テーブルには col1, col2, newcol の3列ができ、mdl_config_plugins テーブルの ('qtype_myqtype', 'version') 行には 2008080200 が入ることになりました。

ユーザによる myqtype のバージョン 2008080200 の Moodle へのクリーンインストール

そもそも mdl_myqtype_options が存在しないので、mdl_config_plugins テーブルに ('qtype_myqtype', 'version') 行が存在しないことになります。

  1. ユーザは、2008080200 バージョンの myqtype.zip を question/type フォルダに解凍することになります。
  2. ユーザは、管理者通知ページにアクセスします。
  3. これにより、Moodle はアップグレードするプラグインを検索するようになります。qtype_myqtype プラグインのコードが存在することがわかりますが、データベースにはその痕跡がないため、install.xml ファイルからプラグインをインストールすることになります。

この処理の結果、mdl_myqtype_options テーブルは col1, col2, newcol の3列で存在し、mdl_config_plugins テーブルの ('qtype_myqtype', 'version') 行は 2008080200 を含むことになります。

アップグレードコードの制限

アップグレード中は、システムが完全に更新されていないため、コードが呼び出すべき関数に制約があります。

  • すべてのアップグレードコードは、基本的なデータベース API ($DB->... 関数) を使用することができます。
  • プラグイン では、アップグレードコードは プラグイン関数 を呼び出さないようにする必要があります。(例えば、あなたのプラグインがカエルの設定を '緑' に変更する関数を持っていて、アップグレードの際にこれを行う必要がある場合、この関数を呼び出すべきではありません。代わりに、カエルの設定が緑になるようにデータベースの行を手動で更新してください。) しかし、データベースのコアな部分を変更するのではなく、コアな機能を呼び出すべきです
  • コアでは、アップグレードコードは コアの関数 を一切呼び出すべきではありません。(例えば、カレンダーのイベントを追加する必要がある場合、関数を呼び出してイベントを追加するのではなく、データベースのテーブルに挿入することで行う必要があります。) set_config, get_config などのコメント付きの関数は除外されます。

その理由は、アップグレード時のシステムの状態にあります。

コアアップグレード中の状態は以下の通りです:

  • Core data: Old.
  • Plugin data: Old.

コア関数はコアデータが Current 状態であることを想定しているので、関数の docblock に以下の記載がない限り、安全に呼び出すことはできません: "注意:この関数は lib/db/upgrade.php から呼び出されます"。

プラグインアップグレード中の状態は、以下の通りです:

  • Core data: Current. (プラグインのアップグレードの前にコアのアップグレードが実行されるためです。)
  • Plugin data: Old.

コアデータが Current 状態であるため、コアファンクションが安全に呼び出せるようになりました。しかし、データが Current の状態であることを期待するプラグイン関数は安全ではありません。

要約

ユーザがプラグインのどのバージョンを最初にインストールするときも、install.xml ファイルを使用して必要なすべてのデータベーステーブルが作成されます。したがって、install.xml には常に最新のデータベース構造の定義が含まれている必要があります。Moodle はディスク上に version.php ファイルがあるため、この状況を認識していますが、mdl_config_plugins テーブルに (plugintype_pluginname, version) の値がありません。

ユーザがあなたのプラグインのバージョンをすでにインストールしていた場合、その後新しいバージョンにアップグレードすると、Moodleは version.php ファイルに mdl_config_plugins テーブルの (plugintype_pluginname, version) 値より新しいバージョン番号が含まれるため、これを検出します。この場合、Moodle は if ($oldversion < XXXXXXXXX) ブロックのコードで制御されるように、アップグレードの正しいビットを実行できるよう、古いバージョン番号を渡して upgrade.php ファイルにあるコードを実行します。

install.xml と upgrade.php ファイルの内容は、XMLDB エディタを使用して生成する必要があります。

その他、db フォルダに入れることができるもの

このうち、必要なデータベース構造の作成に関係するのは install.php のみです。その他のファイルは、主にプラグインをインストールする際に必要となるその他のメタデータを提供するためのものです。可能な限り、他のドキュメントにリンクし、詳細を説明するようにしました。

install.php

(Moodle 2.0 以降)

xmldb_qtype_myqtype_install() のような関数を定義すると、プラグインのインストール時にこの PHP コードが実行されます。install.xml ではできないことができるチャンスです。コンポーネントに関連する DB スキーマ (install.xml) が作成された直後に実行されます。

(Moodle 1.9)

インストール関数は、モジュールのルートディレクトリにある lib.php で定義することができます。インストール関数は qtype_install() という名前でなければならず、引数を取りません (n.b. これは install.xml がパースされた後に lib/adminlib.php から呼び出されます)。

uninstall.php

(Moodle 2.0 以降)

前記の機能とバランスをとりながら、xmldb_qtype_myqtype_uninstall() のように、プラグインがアンインストールされたときに実行される関数を定義して、その DB スキーマを削除することも可能です。

access.php

(Moodle 1.7 以降)

このプラグインがアクセス APIで処理するケイパビリティを定義するために使用します。新しいケイパビリティを追加した後は、version.phpでバージョンを上げる必要があります。

events.php

(Moodle 1.9(?) 以降)

このプラグインがイベント APIに送信するイベントを定義するために使用します。 イベントの修正・追加を行った後は、version.php でバージョンを上げる必要があります。

log.php

(Moodle 2.0 以降)

このプラグインが作成するログエントリの種類を記述するために使用します。詳しくは、ロギング APIlog.php の項を参照してください。You must increase version in version.php after any change.

messages.php

(Moodle 2.0 以降)

このプラグインがメッセージ APIを通じて送信するメッセージを定義するために使用します。変更後は、version.php でバージョンを上げる必要があります。

services.php

(Moodle 2.0 以降)

このプラグインが ウェブサービス API を通じて公開する機能およびサービスを定義するために使用します。通常、これらの関数はすべて外部関数 APIに含まれます。変更後は、version.php でバージョンを上げる必要があります。

upgradelib.php

upgrade.php ファイルで使用するいくつかの ヘルパー関数 の下にアップグレードのコードをまとめることができるオプションのファイルです。必要であれば、このファイルは upgrade.php から一度だけ 手動で要求する 必要があります。その主な目的は、upgrade.php のスクリプトを減らし、すっきりさせることです(xmldb_xxx_upgrade() 以外の関数自身を含むことはできません)。

upgradelib.php は常に生の (低レベルの) データベースアクセスのみを使用し、Moodle API の使用を避けて、タスクを実行することが 重要 です。

mod/.../db/subplugins.php

(Moodle 2.0 以降)

これは活動モジュールにのみ適用され、他のタイプのプラグインには適用されません。これは、活動モジュールに独自のプラグインを持たせるための方法です。例えば、ワークショップの配分計画や、小テストのレポートなどです。

言語パック

言語ファイル lang/en/type_yourplugin.php を修正した後は、バージョン番号を上げることを忘れないでください。詳しくは、言語/AMOS セクションの AMOS スクリプトをご覧ください。

アップグレード API チートシート

アップグレード API は、すべてのアーティファクトをインストール/アップグレードするために使用される API である限り、多くの異なるファイルや API (アクセス、イベント、ログ、ウェブサービス...) と 関連して います。これまでのセクションでは、可能な限りこれらの依存関係をすべてリストアップするように努めました。

また、アップグレードAPIは、Moodle システムの変更を進めるために、他のAPI (ddldml) およびツール (XMLDB エディタ...) を非常に集中的に使用します。

以上のように、APIは いくつかのファイルと関数の集合体である とまとめることができますので、以下に紹介します:

ファイル: 各コンポーネントについて、その "db" ディレクトリの下に置くことができます。

  • version.php: ここで $version が指定され、バンプされた場合、アップグレードの機械が起動され、すべてのキャッシュがリセットされます。/db/, /lang/, テーマ, JavaScriptを変更したら、バージョンを上げます。
  • install.xml: DB スキーマの XMLDB 定義です。XMLDB エディタで生成されます。
  • install.php: スキーマが作成された後に実行されるインストール後のファイルです。
  • uninstall.php: スキーマをドロップする前に実行されるプリアンインストールファイルです。
  • upgrade.php: アップグレードステップを順番に並べたもので、各ステップは明確に定義されたタスクを実行します。
  • upgradelib.php: upgrade.php が使用するヘルパー関数で構成されるライブラリファイルです。

機能一覧: コンポーネントごとに異なる名称を持ちますが、すべてのコンポーネントで利用可能です:

  • xmldb_[main|frankenstyle]_install(): install.php ファイルで使用します。
  • xmldb_[main|frankenstyle]_uninstall(): uninstall.php ファイルで使用します。
  • xmldb_[main|frankenstyle]_upgrade(): upgrade.php ファイルで使用します。
  • upgrade_set_timeout(): upgrade.phpファイルのアップグレードステップ内で使用することで、そのステップに多くの時間を与えることができます。
  • upgrade_[main|mod|block|plugin]_savepoint(): 1つのアップグレードステップが完了したとみなし、タイムアウトをリセットします。二重実行を避けることができます。

もちろん、このAPIの実用的な使用例については、現在のコードを調べて理解することが強く推奨されます 。なんでもありの状態です。

データベースのアップグレードと安定版ブランチ

単純なルールとして、安定版ブランチでは絶対にデータベースを変更しないことです。このセクションを読む必要があるのは、安定版ブランチでのデータベース変更が避けられないような稀な状況だけです。

警告!!!高度な資料が続きます。

例えば、バグを修正するために、あなたが Moodle 1.9.3+でデータベースを変更する必要があるとします (これは HEAD にもマージされる必要があります)。問題の根源は、人々が3つの異なる方法で Moodle をアップグレードする可能性があることです。

  • Upgrade from <=1.9.3 to 1.9.4 - これは 1.9 ブランチの ugprade スクリプトを実行するものです。
  • Upgrade from <=1.9.3 directly to >=2.0 - これは、HEAD ブランチのアップグレードスクリプトを実行するものです。
  • Upgrade from 1.9.4 to >=2.0 - この場合、HEAD 上でのアップグレードが実行されないようにする必要があります。

通常の方法では、データベースのアップグレードが冪等であることを確認する必要があります。つまり、2回やっても問題ないのです。ですから、例えば、次のようにする代わりに

       $dbman->create_table($table);

以下のようにする必要があります。

       if (!$dbman->table_exists($table)) {
           $dbman->create_table($table);
       }

また、各ブランチの version.php ファイルにどのようなバージョン番号を記載するかについても考えておく必要があります。なによりも、慎重にテストしてください。

関連項目