framework/rest/UrlRule.php
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
namespace yii\rest;
use Yii;
use yii\base\InvalidConfigException;
use yii\helpers\Inflector;
use yii\web\CompositeUrlRule;
use yii\web\UrlRule as WebUrlRule;
use yii\web\UrlRuleInterface;
/**
* UrlRule is provided to simplify the creation of URL rules for RESTful API support.
*
* The simplest usage of UrlRule is to declare a rule like the following in the application configuration,
*
* ```php
* [
* 'class' => 'yii\rest\UrlRule',
* 'controller' => 'user',
* ]
* ```
*
* The above code will create a whole set of URL rules supporting the following RESTful API endpoints:
*
* - `'PUT,PATCH users/<id>' => 'user/update'`: update a user
* - `'DELETE users/<id>' => 'user/delete'`: delete a user
* - `'GET,HEAD users/<id>' => 'user/view'`: return the details/overview/options of a user
* - `'POST users' => 'user/create'`: create a new user
* - `'GET,HEAD users' => 'user/index'`: return a list/overview/options of users
* - `'users/<id>' => 'user/options'`: process all unhandled verbs of a user
* - `'users' => 'user/options'`: process all unhandled verbs of user collection
*
* You may configure [[only]] and/or [[except]] to disable some of the above rules.
* You may configure [[patterns]] to completely redefine your own list of rules.
* You may configure [[controller]] with multiple controller IDs to generate rules for all these controllers.
* For example, the following code will disable the `delete` rule and generate rules for both `user` and `post` controllers:
*
* ```php
* [
* 'class' => 'yii\rest\UrlRule',
* 'controller' => ['user', 'post'],
* 'except' => ['delete'],
* ]
* ```
*
* The property [[controller]] is required and should represent one or multiple controller IDs.
* Each controller ID should be prefixed with the module ID if the controller is within a module.
* The controller ID used in the pattern will be automatically pluralized (e.g. `user` becomes `users`
* as shown in the above examples).
*
* For more details and usage information on UrlRule, see the [guide article on rest routing](guide:rest-routing).
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
class UrlRule extends CompositeUrlRule
{
/**
* @var string|null the common prefix string shared by all patterns.
*/
public $prefix;
/**
* @var string the suffix that will be assigned to [[\yii\web\UrlRule::suffix]] for every generated rule.
*/
public $suffix;
/**
* @var string|array the controller ID (e.g. `user`, `post-comment`) that the rules in this composite rule
* are dealing with. It should be prefixed with the module ID if the controller is within a module (e.g. `admin/user`).
*
* By default, the controller ID will be pluralized automatically when it is put in the patterns of the
* generated rules. If you want to explicitly specify how the controller ID should appear in the patterns,
* you may use an array with the array key being as the controller ID in the pattern, and the array value
* the actual controller ID. For example, `['u' => 'user']`.
*
* You may also pass multiple controller IDs as an array. If this is the case, this composite rule will
* generate applicable URL rules for EVERY specified controller. For example, `['user', 'post']`.
*/
public $controller;
/**
* @var array list of acceptable actions. If not empty, only the actions within this array
* will have the corresponding URL rules created.
* @see patterns
*/
public $only = [];
/**
* @var array list of actions that should be excluded. Any action found in this array
* will NOT have its URL rules created.
* @see patterns
*/
public $except = [];
/**
* @var array patterns for supporting extra actions in addition to those listed in [[patterns]].
* The keys are the patterns and the values are the corresponding action IDs.
* These extra patterns will take precedence over [[patterns]].
*/
public $extraPatterns = [];
/**
* @var array list of tokens that should be replaced for each pattern. The keys are the token names,
* and the values are the corresponding replacements.
* @see patterns
*/
public $tokens = [
'{id}' => '<id:\\d[\\d,]*>',
];
/**
* @var array list of possible patterns and the corresponding actions for creating the URL rules.
* The keys are the patterns and the values are the corresponding actions.
* The format of patterns is `Verbs Pattern`, where `Verbs` stands for a list of HTTP verbs separated
* by comma (without space). If `Verbs` is not specified, it means all verbs are allowed.
* `Pattern` is optional. It will be prefixed with [[prefix]]/[[controller]]/,
* and tokens in it will be replaced by [[tokens]].
*/
public $patterns = [
'PUT,PATCH {id}' => 'update',
'DELETE {id}' => 'delete',
'GET,HEAD {id}' => 'view',
'POST' => 'create',
'GET,HEAD' => 'index',
'{id}' => 'options',
'' => 'options',
];
/**
* @var array the default configuration for creating each URL rule contained by this rule.
*/
public $ruleConfig = [
'class' => 'yii\web\UrlRule',
];
/**
* @var bool whether to automatically pluralize the URL names for controllers.
* If true, a controller ID will appear in plural form in URLs. For example, `user` controller
* will appear as `users` in URLs.
* @see controller
*/
public $pluralize = true;
/**
* {@inheritdoc}
*/
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();
}
/**
* {@inheritdoc}
*/
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;
}
/**
* Creates a URL rule using the given pattern and action.
* @param string $pattern
* @param string $prefix
* @param string $action
* @return UrlRuleInterface
*/
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);
}
/**
* {@inheritdoc}
*/
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;
}
/**
* {@inheritdoc}
*/
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;
}
}