クラス yii\rest\UrlRule
UrlRule は、RESTful API サポートのための URL ルールの作成を簡単にするために提供されています。
UrlRule の最も単純な使い方は、アプリケーション設定で次のようなルールを宣言することです。
[
'class' => 'yii\rest\UrlRule',
'controller' => 'user',
]
上記のコードは、次の RESTful API エンドポイントをサポートする URL ルールの完全なセットを作成します。
'PUT,PATCH users/<id>' => 'user/update'
: ユーザーを更新する'DELETE users/<id>' => 'user/delete'
: ユーザーを削除する'GET,HEAD users/<id>' => 'user/view'
: ユーザーの詳細/概要/オプションを返す'POST users' => 'user/create'
: 新しいユーザーを作成する'GET,HEAD users' => 'user/index'
: ユーザーのリスト/概要/オプションを返す'users/<id>' => 'user/options'
: ユーザーの処理されていないすべての動詞を処理する'users' => 'user/options'
: ユーザーコレクションの処理されていないすべての動詞を処理する
$only および/または $except を構成して、上記のルールの一部を無効にすることができます。 $patterns を構成して、独自のルールリストを完全に再定義することができます。 $controller を複数のコントローラ ID で構成して、これらすべてのコントローラに対するルールを生成することができます。たとえば、次のコードは、delete
ルールを無効にし、user
コントローラと post
コントローラの両方のルールを生成します。
[
'class' => 'yii\rest\UrlRule',
'controller' => ['user', 'post'],
'except' => ['delete'],
]
プロパティ $controller は必須で、1 つまたは複数のコントローラ ID を表す必要があります。各コントローラ ID には、コントローラがモジュール内にある場合は、モジュール ID が付いている必要があります。パターンで使用されるコントローラ ID は、自動的に複数形になります (たとえば、上記の例に示すように、user
は users
になります)。
UrlRule の詳細と使用法については、rest ルーティングに関するガイド記事を参照してください。
パブリックプロパティ
プロパティ | 型 | 説明 | 定義元 |
---|---|---|---|
$controller | string|array | このコンポジットルール内のルールが処理するコントローラ ID (例: user , post-comment )。 |
yii\rest\UrlRule |
$createStatus | integer|null | 最後の createUrl() 呼び出し後の URL 作成のステータス。 | yii\web\CompositeUrlRule |
$createUrlStatus | integer|null | 最後の createUrl() 呼び出し後の URL 作成のステータス。 | yii\web\CompositeUrlRule |
$except | array | 除外するアクションのリスト。 | yii\rest\UrlRule |
$extraPatterns | array | $patterns にリストされているものに加えて、追加のアクションをサポートするためのパターン。 | yii\rest\UrlRule |
$only | array | 受け入れ可能なアクションのリスト。 | yii\rest\UrlRule |
$patterns | array | URL ルールを作成するための可能なパターンと対応するアクションのリスト。 | yii\rest\UrlRule |
$pluralize | boolean | コントローラの URL 名を自動的に複数形にするかどうか。 | yii\rest\UrlRule |
$prefix | string|null | すべてのパターンで共有される共通のプレフィックス文字列。 | yii\rest\UrlRule |
$ruleConfig | array | このルールに含まれる各URLルールを作成するためのデフォルト設定。 | yii\rest\UrlRule |
$rules | yii\web\UrlRuleInterface[] | この複合ルールに含まれるURLルール。 | yii\web\CompositeUrlRule |
$suffix | string | 生成されるすべてのルールに対してyii\web\UrlRule::$suffixに割り当てられるサフィックス。 | yii\rest\UrlRule |
$tokens | array | 各パターンで置換されるべきトークンの一覧。 | yii\rest\UrlRule |
公開メソッド
メソッド | 説明 | 定義元 |
---|---|---|
__call() | クラスメソッドではない、指定された名前のメソッドを呼び出します。 | yii\base\BaseObject |
__construct() | コンストラクタ。 | yii\base\BaseObject |
__get() | オブジェクトプロパティの値を返します。 | yii\base\BaseObject |
__isset() | プロパティが設定されているか、つまり定義されていてnullでないかを確認します。 | yii\base\BaseObject |
__set() | オブジェクトプロパティの値を設定します。 | yii\base\BaseObject |
__unset() | オブジェクトプロパティをnullに設定します。 | yii\base\BaseObject |
canGetProperty() | プロパティが読み取り可能かどうかを示す値を返します。 | yii\base\BaseObject |
canSetProperty() | プロパティが設定可能かどうかを示す値を返します。 | yii\base\BaseObject |
className() | このクラスの完全修飾名を返します。 | yii\base\BaseObject |
createUrl() | 指定されたルートとパラメータに従ってURLを作成します。 | yii\rest\UrlRule |
getCreateUrlStatus() | 最後のcreateUrl()呼び出し後のURL作成のステータスを返します。 | yii\web\CompositeUrlRule |
hasMethod() | メソッドが定義されているかどうかを示す値を返します。 | yii\base\BaseObject |
hasProperty() | プロパティが定義されているかどうかを示す値を返します。 | yii\base\BaseObject |
init() | オブジェクトを初期化します。 | yii\rest\UrlRule |
parseRequest() | 指定されたリクエストを解析し、対応するルートとパラメータを返します。 | yii\rest\UrlRule |
保護されたメソッド
メソッド | 説明 | 定義元 |
---|---|---|
createRule() | 指定されたパターンとアクションを使用してURLルールを作成します。 | yii\rest\UrlRule |
createRules() | この複合ルール内に含まれるべきURLルールを作成します。 | yii\rest\UrlRule |
iterateRules() | 指定されたルールを反復処理し、それらの各々に対してcreateUrl()を呼び出します。 | yii\web\CompositeUrlRule |
プロパティの詳細
この複合ルール内のルールが扱うコントローラーID(例:user
、post-comment
)。コントローラーがモジュール内にある場合は、モジュールIDをプレフィックスとして付ける必要があります(例:admin/user
)。
デフォルトでは、コントローラーIDは、生成されたルールのパターンに配置されるときに自動的に複数形になります。コントローラーIDをパターンにどのように表示するかを明示的に指定したい場合は、配列のキーをパターンのコントローラーIDとして、配列の値を実際のコントローラーIDとする配列を使用できます。たとえば、['u' => 'user']
のようになります。
複数のコントローラーIDを配列として渡すこともできます。この場合、この複合ルールは、指定されたすべてのコントローラーに適用可能なURLルールを生成します。たとえば、['user', 'post']
のようになります。
除外されるべきアクションの一覧。この配列に見つかったアクションは、URLルールが作成されません。
$patternsも参照してください。
許可されるアクションの一覧。空でない場合、この配列内のアクションのみが対応するURLルールを作成します。
$patternsも参照してください。
URLルールを作成するための可能なパターンと対応するアクションの一覧。キーはパターンであり、値は対応するアクションです。パターンの形式はVerbs Pattern
です。Verbs
は、コンマ(スペースなし)で区切られたHTTP動詞のリストを表します。Verbs
が指定されていない場合は、すべての動詞が許可されていることを意味します。Pattern
はオプションです。$prefix/$controller/がプレフィックスとして付けられ、その中のトークンは$tokensで置換されます。
コントローラーのURL名を自動的に複数形にするかどうか。trueの場合、コントローラーIDはURLで複数形で表示されます。たとえば、user
コントローラーはURLでusers
として表示されます。
$controllerも参照してください。
このルールに含まれる各URLルールを作成するためのデフォルト設定。
生成されるすべてのルールに対してyii\web\UrlRule::$suffixに割り当てられるサフィックス。
メソッドの詳細
定義元: yii\base\BaseObject::__call()
クラスメソッドではない、指定された名前のメソッドを呼び出します。
このメソッドは、不明なメソッドが呼び出されたときに暗黙的に呼び出されるPHPのマジックメソッドであるため、直接呼び出さないでください。
public mixed __call ( $name, $params ) | ||
$name | string |
メソッド名 |
$params | array |
メソッドのパラメータ |
return | mixed |
メソッドの戻り値 |
---|---|---|
throws | yii\base\UnknownMethodException |
不明なメソッドを呼び出した場合 |
public function __call($name, $params)
{
throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
定義元: yii\base\BaseObject::__construct()
コンストラクタ。
デフォルトの実装では、次の2つのことを行います。
- 指定された構成
$config
でオブジェクトを初期化します。 - init()を呼び出します。
このメソッドが子クラスでオーバーライドされている場合、推奨されることは
- コンストラクタの最後のパラメータは、ここでの
$config
のように構成配列にすることです。 - コンストラクタの最後に親の実装を呼び出すことです。
public void __construct ( $config = [] ) | ||
$config | array |
オブジェクトのプロパティを初期化するために使用される名前と値のペア |
public function __construct($config = [])
{
if (!empty($config)) {
Yii::configure($this, $config);
}
$this->init();
}
定義元: yii\base\BaseObject::__get()
オブジェクトプロパティの値を返します。
このメソッドは、$value = $object->property;
を実行するときに暗黙的に呼び出されるPHPのマジックメソッドであるため、直接呼び出さないでください。
__set() も参照してください。
public mixed __get ( $name ) | ||
$name | string |
プロパティ名 |
return | mixed |
プロパティの値 |
---|---|---|
throws | yii\base\UnknownPropertyException |
プロパティが定義されていない場合 |
throws | yii\base\InvalidCallException |
プロパティが書き込み専用の場合 |
public function __get($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter();
} elseif (method_exists($this, 'set' . $name)) {
throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
}
throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
定義元: yii\base\BaseObject::__isset()
プロパティが設定されているか、つまり定義されていてnullでないかを確認します。
このメソッドは、isset($object->property)
を実行するときに暗黙的に呼び出されるPHPのマジックメソッドであるため、直接呼び出さないでください。
プロパティが定義されていない場合は、false が返されることに注意してください。
public boolean __isset ( $name ) | ||
$name | string |
プロパティ名またはイベント名 |
return | boolean |
指定された名前のプロパティが設定されているかどうか (nullではない)。 |
---|
public function __isset($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter() !== null;
}
return false;
}
定義元: yii\base\BaseObject::__set()
オブジェクトプロパティの値を設定します。
このメソッドは、$object->property = $value;
を実行するときに暗黙的に呼び出されるPHPのマジックメソッドであるため、直接呼び出さないでください。
__get() も参照してください。
public void __set ( $name, $value ) | ||
$name | string |
プロパティ名またはイベント名 |
$value | mixed |
プロパティの値 |
throws | yii\base\UnknownPropertyException |
プロパティが定義されていない場合 |
---|---|---|
throws | yii\base\InvalidCallException |
プロパティが読み取り専用の場合 |
public function __set($name, $value)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter($value);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
} else {
throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}
}
定義元: yii\base\BaseObject::__unset()
オブジェクトプロパティをnullに設定します。
このメソッドは、unset($object->property)
を実行するときに暗黙的に呼び出されるPHPのマジックメソッドであるため、直接呼び出さないでください。
プロパティが定義されていない場合、このメソッドは何もしないことに注意してください。プロパティが読み取り専用の場合、例外がスローされます。
public void __unset ( $name ) | ||
$name | string |
プロパティ名 |
throws | yii\base\InvalidCallException |
プロパティが読み取り専用の場合。 |
---|
public function __unset($name)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter(null);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
}
}
定義元: yii\base\BaseObject::canGetProperty()
プロパティが読み取り可能かどうかを示す値を返します。
プロパティは、次の場合に読み取り可能です。
- クラスに、指定された名前に関連付けられたゲッターメソッドがある場合(この場合、プロパティ名は大文字と小文字を区別しません)。
- クラスに、指定された名前を持つメンバー変数がある場合(
$checkVars
がtrueの場合)。
canSetProperty() も参照してください。
public boolean canGetProperty ( $name, $checkVars = true ) | ||
$name | string |
プロパティ名 |
$checkVars | boolean |
メンバー変数をプロパティとして扱うかどうか |
return | boolean |
プロパティが読み取れるかどうか |
---|
public function canGetProperty($name, $checkVars = true)
{
return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
定義元: yii\base\BaseObject::canSetProperty()
プロパティが設定可能かどうかを示す値を返します。
プロパティは、次の場合に書き込み可能です。
- クラスに、指定された名前に関連付けられたセッターメソッドがある場合(この場合、プロパティ名は大文字と小文字を区別しません)。
- クラスに、指定された名前を持つメンバー変数がある場合(
$checkVars
がtrueの場合)。
canGetProperty() も参照してください。
public boolean canSetProperty ( $name, $checkVars = true ) | ||
$name | string |
プロパティ名 |
$checkVars | boolean |
メンバー変数をプロパティとして扱うかどうか |
return | boolean |
プロパティが書き込み可能かどうか |
---|
public function canSetProperty($name, $checkVars = true)
{
return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
::class
を使用してください。
定義元: yii\base\BaseObject::className()
このクラスの完全修飾名を返します。
public static string className ( ) | ||
return | string |
このクラスの完全修飾名。 |
---|
public static function className()
{
return get_called_class();
}
指定されたパターンとアクションを使用してURLルールを作成します。
protected yii\web\UrlRuleInterface createRule ( $pattern, $prefix, $action ) | ||
$pattern | string | |
$prefix | string | |
$action | string |
protected function createRule($pattern, $prefix, $action)
{
$verbs = 'GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS';
if (preg_match("/^((?:($verbs),)*($verbs))(?:\\s+(.*))?$/", $pattern, $matches)) {
$verbs = explode(',', $matches[1]);
$pattern = isset($matches[4]) ? $matches[4] : '';
} else {
$verbs = [];
}
$config = $this->ruleConfig;
$config['verb'] = $verbs;
$config['pattern'] = rtrim($prefix . '/' . strtr($pattern, $this->tokens), '/');
$config['route'] = $action;
$config['suffix'] = $this->suffix;
return Yii::createObject($config);
}
この複合ルール内に含まれるべきURLルールを作成します。
protected yii\web\UrlRuleInterface[] createRules ( ) | ||
return | yii\web\UrlRuleInterface[] |
URLルール |
---|
protected function createRules()
{
$only = array_flip($this->only);
$except = array_flip($this->except);
$patterns = $this->extraPatterns + $this->patterns;
$rules = [];
foreach ($this->controller as $urlName => $controller) {
$prefix = trim($this->prefix . '/' . $urlName, '/');
foreach ($patterns as $pattern => $action) {
if (!isset($except[$action]) && (empty($only) || isset($only[$action]))) {
$rules[$urlName][] = $this->createRule($pattern, $prefix, $controller . '/' . $action);
}
}
}
return $rules;
}
指定されたルートとパラメータに従ってURLを作成します。
public string|boolean createUrl ( $manager, $route, $params ) | ||
$manager | yii\web\UrlManager |
URLマネージャ |
$route | string |
ルート。先頭または末尾にスラッシュを含めないでください。 |
$params | array |
パラメータ |
return | string|boolean |
作成されたURL。このルールでURLを作成できない場合は false。 |
---|
public function createUrl($manager, $route, $params)
{
$this->createStatus = WebUrlRule::CREATE_STATUS_SUCCESS;
foreach ($this->controller as $urlName => $controller) {
if (strpos($route, $controller) !== false) {
/* @var $rules UrlRuleInterface[] */
$rules = $this->rules[$urlName];
$url = $this->iterateRules($rules, $manager, $route, $params);
if ($url !== false) {
return $url;
}
} else {
$this->createStatus |= WebUrlRule::CREATE_STATUS_ROUTE_MISMATCH;
}
}
if ($this->createStatus === WebUrlRule::CREATE_STATUS_SUCCESS) {
// create status was not changed - there is no rules configured
$this->createStatus = WebUrlRule::CREATE_STATUS_PARSING_ONLY;
}
return false;
}
定義元: yii\web\CompositeUrlRule::getCreateUrlStatus()
最後のcreateUrl()呼び出し後のURL作成のステータスを返します。
複数のルールのステータスは、ビット単位の or
演算子で結合されます (例: UrlRule::CREATE_STATUS_PARSING_ONLY | UrlRule::CREATE_STATUS_PARAMS_MISMATCH
)。
参照
public integer|null getCreateUrlStatus ( ) | ||
return | integer|null |
最後の createUrl() 呼び出し後の URL 作成のステータス。ルールが作成ステータスに関する情報を提供しない場合は |
---|
public function getCreateUrlStatus()
{
return $this->createStatus;
}
定義元: yii\base\BaseObject::hasMethod()
メソッドが定義されているかどうかを示す値を返します。
デフォルトの実装は、PHP 関数 method_exists()
の呼び出しです。PHP マジックメソッド __call()
を実装した場合は、このメソッドをオーバーライドできます。
public boolean hasMethod ( $name ) | ||
$name | string |
メソッド名 |
return | boolean |
メソッドが定義されているかどうか |
---|
public function hasMethod($name)
{
return method_exists($this, $name);
}
定義元: yii\base\BaseObject::hasProperty()
プロパティが定義されているかどうかを示す値を返します。
プロパティは、以下の場合に定義されます。
- クラスが、指定された名前に関連付けられたゲッターまたはセッターメソッドを持っている場合 (この場合、プロパティ名はcase-insensitive)。
- クラスに、指定された名前を持つメンバー変数がある場合(
$checkVars
がtrueの場合)。
参照
public boolean hasProperty ( $name, $checkVars = true ) | ||
$name | string |
プロパティ名 |
$checkVars | boolean |
メンバー変数をプロパティとして扱うかどうか |
return | boolean |
プロパティが定義されているかどうか |
---|
public function hasProperty($name, $checkVars = true)
{
return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
オブジェクトを初期化します。
このメソッドは、オブジェクトが指定された構成で初期化された後、コンストラクタの最後に呼び出されます。
public void init ( ) |
public function init()
{
if (empty($this->controller)) {
throw new InvalidConfigException('"controller" must be set.');
}
$controllers = [];
foreach ((array) $this->controller as $urlName => $controller) {
if (is_int($urlName)) {
$urlName = $this->pluralize ? Inflector::pluralize($controller) : $controller;
}
$controllers[$urlName] = $controller;
}
$this->controller = $controllers;
$this->prefix = trim((string)$this->prefix, '/');
parent::init();
}
定義元: yii\web\CompositeUrlRule::iterateRules()
指定されたルールを反復処理し、それらの各々に対してcreateUrl()を呼び出します。
createUrl()も参照してください。
protected boolean|string iterateRules ( $rules, $manager, $route, $params ) | ||
$rules | yii\web\UrlRuleInterface[] |
反復処理するルール。 |
$manager | yii\web\UrlManager |
URLマネージャ |
$route | string |
ルート。先頭または末尾にスラッシュを含めないでください。 |
$params | array |
パラメータ |
return | boolean|string |
作成されたURL。指定されたどのルールもこのURLの作成に使用できない場合は、 |
---|
protected function iterateRules($rules, $manager, $route, $params)
{
/* @var $rule UrlRule */
foreach ($rules as $rule) {
$url = $rule->createUrl($manager, $route, $params);
if ($url !== false) {
$this->createStatus = UrlRule::CREATE_STATUS_SUCCESS;
return $url;
}
if (
$this->createStatus === null
|| !method_exists($rule, 'getCreateUrlStatus')
|| $rule->getCreateUrlStatus() === null
) {
$this->createStatus = null;
} else {
$this->createStatus |= $rule->getCreateUrlStatus();
}
}
return false;
}
指定されたリクエストを解析し、対応するルートとパラメータを返します。
public array|boolean parseRequest ( $manager, $request ) | ||
$manager | yii\web\UrlManager |
URLマネージャ |
$request | yii\web\Request |
リクエストコンポーネント |
return | array|boolean |
パース結果。ルートとパラメータは配列として返されます。false の場合、このルールはこのパス情報のパースに使用できないことを意味します。 |
---|
public function parseRequest($manager, $request)
{
$pathInfo = $request->getPathInfo();
if (
$this->prefix !== ''
&& strpos($this->prefix, '<') === false
&& strpos($pathInfo . '/', $this->prefix . '/') !== 0
) {
return false;
}
foreach ($this->rules as $urlName => $rules) {
if (strpos($pathInfo, $urlName) !== false) {
foreach ($rules as $rule) {
/* @var $rule WebUrlRule */
$result = $rule->parseRequest($manager, $request);
if (YII_DEBUG) {
Yii::debug([
'rule' => method_exists($rule, '__toString') ? $rule->__toString() : get_class($rule),
'match' => $result !== false,
'parent' => self::className(),
], __METHOD__);
}
if ($result !== false) {
return $result;
}
}
}
}
return false;
}
このクラスはデフォルトで、アクセスしようとしているリソースの ID を数字としてマッチングします。一意の識別子が単なる数字でない場合、例えば UUID V4 の場合、構成で
$tokens
メンバ変数をオーバーライドして、{id}
トークンがマッチする必要のあるものを指定できます。これは正規表現マッチングを使用します。'urlManager' => [ ... 'rules' => [ [ 'class' => 'yii\rest\UrlRule', 'controller' => ['controllername'], 'tokens' => ['{id}' => '<id:\\w+>'], ], ], ],
この例では、
{id}
を 1 回以上の任意の英数字[a-zA-Z0-9_]
にマッチングさせます。コメントするには、サインアップまたはログインしてください。