アクセスAPI (Dev docs)
English page: Dev:Access API
Moodle 2.2 アクセスAPIは、現在のユーザに何が許可されているか判断するための関数を提供します。また、モジュールが新しい機能でMoodleを拡張することを可能にします。
概要
Moodleはロールベースのアクセスコントロールモデルを使用しています。Moodleのほとんどのエンティティ (システム、ユーザ、コースカテゴリ、コース、モジュールおよびブロック) はコンテキストツリーと呼ばれるツリー状の階層に配置されたコンテキストによって表現されます。ロールはケイパビリティ定義のセットで、それぞれのケイパビリティは通常、ユーザが何かをするための能力を表します。役割は、システムコンテキストの最上位レベルで定義されます。役割の定義は下位のコンテキストレベルで上書きすることができる。ユーザのアクセス制御は、ユーザに割り当てられたロールの定義から計算されます。
まだログインしていないすべてのユーザは、自動的に $CFG->notloggedinroleid で定義されたデフォルトロールを取得し、この存在しないユーザIDに他のロールを割り当てることは不可能です。これは、ユーザがゲストログインボタンを使用してログインしたとき、あるいはゲスト自動ログインが有効になっているときに使用される特別なゲストユーザアカウントです。このアカウントには $CFG->guestroleid が自動的に割り当てられます。他のすべての認証済みユーザは、 $CFG->defaultuserroleid で指定したデフォルトのユーザロールを取得します。また、フロントページコンテキストでは $CFG->defaultfrontpageroleid で指定したロールを取得します。
プラグインで新しい機能を定義する方法
ケイパビリティは、db/access.phpファイルに定義されている $capabilities 配列で定義されます。ケイパビリティの名前は "plugintype/pluginname:capabilityname" で構成されます。
例:
$capabilities = [
'mod/folder:managefiles' => [
'riskbitmask' => RISK_SPAM,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => [
'editingteacher' => CAP_ALLOW,
],
],
];
ここで、配列のキーの意味は:
- riskbitmask - に関連するリスクについて説明します。これについては、新しいロールシステムの強化で説明しています。
- captype - readまたはwriteケイパビリティタイプ、セキュリティ上の理由から、ゲストアカウントおよび未ログインユーザにはすべての書き込み機能を提供しません。
- contextlevel - コンテキストレベル定数として指定されます。このケイパビリティがチェックされる典型的なコンテキストレベルを宣言します。このケイパビリティは、より低いレベルのコンテキストで確認することができます (例えば、'moodle/site:accessallgroups' - CONTEXT_MODULE で確認することができます)。
- archetypes - これはインストール、アップグレード、ロールのリセット時に使用されます(ここではCAP_ALLOWのみを使用することが推奨されます)。 アーキタイプはmdl_roleテーブルで定義されます。ロールのアーキタイプも参照してください。
- clonepermissionsfrom - 新しい機能を追加する場合、あなたはMoodleに他の機能の現在の設定から、各ロールのパーミッションをコピーするよう指示することができます。これはロールの設定を大幅にカスタマイズしている管理者にとっては、アーキタイプを使用するよりも良いデフォルトを与えることができます。完全な構文は: 'clonepermissionsfrom' => 'moodle/quiz:attempt',
- 2012年5月以前のリリースでは、clonepermissionsfrom は個々のプラグイン内またはコアでのみ動作します。それ以降のリリースでは、プラグインもコアからパーミッションを複製することができますが、他の複製操作の成功はアップグレード順に依存します。
アップグレードスクリプトがデータベースに必要な変更を加えることができるよう、db/access.php に変更があった場合、プラグインのバージョン番号を上げることが必要です。 アップグレードスクリプトを実行するには、管理者としてMoodleにログインし、サイトのホームページに移動して、指示に従ってください。 (あなたが、プラグインのバージョンを変更せずにアップグレードスクリプトをテストする必要がある場合、データベースのmdl_blockまたはmdl_modulesテーブルのバージョン番号を戻すことも可能です)。
ケイパビリティ名はプラグイン言語ファイルで定義され、文字列名は "pluginname:capacityname" で構成され、上記の例では次のようになります:
$string['folder:managefiles'] = 'Manage files in folder module';
便利な機能およびクラス
コンテキストの取得
プラグインでは、コンテキストインスタンスは、システムによって自動的にインスタンス化され、削除されるため、通常、インスタンス化されるだけです。
オブジェクトIDで取得する:
$systemcontext = context_system::instance();
$usercontext = context_user::instance($user->id);
$categorycontext = context_coursecat::instance($category->id);
$coursecontext = context_course::instance($course->id);
$contextmodule = context_module::instance($cm->id);
$contextblock = context_block::instance($this->instance->id);
コンテキストIDで取得する:
$context = context::instance_by_id($contextid);
注意事項:
- コンテキストを作成できない場合、デフォルトで例外がスローされます。
- 削除されたユーザはコンテキストを持たなくなります。
2.2 以降、非推奨のコンテキスト関連関数が複数存在しますが、すぐに置き換える必要はありません。以下の2つの関数は、上記のコンテキスト取得の例と同等です:
function get_context_instance($contextlevel, $instance = 0, $strictness = IGNORE_MISSING)
function get_context_instance_by_id($id, $strictness = IGNORE_MISSING)
ユーザが所定のケイパビリティを有するかどうかの判定
アクセス制御を行う際には、常に "そのユーザは何かをするケイパビリティを持っているか?" と問います。 "そのユーザはどこかのロールを持っているか?" と問うのは誤りです。
has_capability()
has_capability() は最も重要な機能です。
function has_capability($capability, context $context, $user = null, $doanything = true)
与えられたコンテキストにおいて、ユーザが特定のケイパビリティを持っているかどうかをチェックします。例えば:
$context = context_module::instance($cm->id);
if (has_capability('mod/folder:managefiles', $context)) {
// 何かをする、または表示する。
}
デフォルトでは、現在のユーザの能力をチェックしますが、別のユーザIDを渡すことができます。デフォルトでは、adminユーザに対してtrueを返すので、ここでfalseを使うことは推奨されません。
require_capability()
関数 require_capability() は非常によく似ており、ユーザがケイパビリティを持っていない場合、アクセス制御例外を投げます。
function require_capability($capability, context $context, $userid = null, $doanything = true, $errormessage = 'nopermissions', $stringfile = '') {
登録機能
登録APIを参照してください。
その他の関連機能
function require_login($courseorid = NULL, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false)
function require_course_login($courseorid, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false)
function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
$groups = '', $exceptions = '', $doanything_ignored = null, $view_ignored = null, $useviewallgroups = false)
function isguestuser($user = null)
function isloggedin()
function is_siteadmin($user_or_id = null)
function is_guest(context $context, $user = null)
function is_viewing(context $context, $user = null, $withcapability = '')
require_login()
各プラグインスクリプトは、PAGE->url を設定した後、require_login() または require_course_login() を含める必要があります。
この機能は、次のようなことを行います:
- コースや活動にアクセスする前に、ユーザがログインしていることを確認します(ログインしていないユーザは、コースに入ることができません)。
- ユーザが gu としてログインする。
- 秘匿されたコースや活動へのアクセスを確認する。
- 活動が指定された場合、その活動のアベイラビリテの制限を確認します。
- ユーザが登録されているか、ケイパビリティ 'moodle/course:view' を持っているか、登録プラグインが一時的なゲストアクセスを与えているか確認する。
- アクセスログ。
require_course_login()
この機能は、ログインせずにフロントページのコンテンツを読むことを許可したい活動でのみ使用されることになっています。例えば、リソースファイルの閲覧、用語集エントリの閲覧などです。
isguestuser(), isloggedin() および is_siteadmin()
これらの関数は、以前は特別なアカウントへのアクセスを制限するために必要でした。なぜなら、write や risky の機能は has_capability() で自動的に阻止されるようになったからです。
活動モジュールで is_siteadmin() を使用することは強く推奨されません。代わりに標準的なケイパビリティと登録ステータスを使用してください。
is_guest(), is_viewing() and is_enrolled()
コースデータにアクセスするために、これらの関数の1つはユーザに対してtrueを返す必要があります。
- is_enrolled() - user_enrolments テーブルにアクティブなレコードを持つユーザ。
- is_viewing() - ケイパビリティ 'moodle/course:view' を持つユーザ (コースにアクセスすることができますが、参加者とはみなされません)。
- is_guest() - 登録プラグインで一時的にゲストアクセス権が与えられたユーザ
get_users_by_capability()
このメソッドは与えられたケイパビリティを持つユーザのリストを返します。これは登録ステータスを無視するため、コースコンテクスト上でのみ使用されるべきです。