CUrlManager
| Пакет | system.web |
|---|---|
| Наследование | class CUrlManager » CApplicationComponent » CComponent |
| Реализует | IApplicationComponent |
| С версии | 1.0 |
| Исходный код | framework/web/CUrlManager.php |
Он предоставляет функциональность построения URL (createUrl()) и парсинга (parseUrl()).
URL-адреса, управляемые CUrlManager, могут иметь один из двух форматов, устанавливая свойство urlFormat:
- Формат 'path': /path/to/EntryScript.php/name1/value1/name2/value2...
- Формат 'get': /path/to/EntryScript.php?name1=value1&name2=value2...
При использовании формата 'path', CUrlManager использует набор правил для:
- разбора запрошенного URL-адреса на маршрут ('ControllerID/ActionID') и параметры GET;
- создания URL-адресов на основе заданного маршрута и параметров GET.
Правило состоит из маршрута и шаблона. Последний используется CUrlManager для определения правила, используемого для разбора/создания URL-адресов. Шаблон предназначен для соответствия части пути URL-адреса. Он может содержать именованные параметры с помощью синтаксиса '<ParamName:RegExp>'.
При разборе URL-адреса соответствующее правило извлечёт именованные параметры из части пути и поместит их в переменную $_GET; при создании URL-адреса соответствующее правило извлечёт именованные параметры из $_GET и поместит их в часть пути создаваемого URL-адреса.
Если шаблон заканчивается на '/*', это означает, что дополнительные параметры GET могут быть добавлены к части пути URL-адреса; в противном случае параметры GET могут появляться только в части запроса.
Для указания правил URL-адресов установите свойство rules в виде массива правил (pattern=>route). Например,
array(
'articles'=>'article/list',
'article/<id:\d+>/*'=>'article/read',
)
В примере выше указаны два правила: - Первое правило гласит, что если пользователь запрашивает URL '/path/to/index.php/articles', он должен обрабатываться как '/path/to/index.php/article/list'; и наоборот при построении такого URL-адреса.
- Второе правило содержит именованный параметр 'id', который указан с помощью синтаксиса <ParamName:RegExp>. Оно говорит, что если пользователь запрашивает URL '/path/to/index.php/article/13', он должен обрабатываться как '/path/to/index.php/article/read?id=13'; и наоборот при построении такого URL-адреса.
Часть маршрута может содержать ссылки на именованные параметры, определённые в части шаблона. Это позволяет применять правило к различным маршрутам на основе критериев соответствия. Например,
array(
'<_c:(post|comment)>/<id:\d+>/<_a:(create|update|delete)>'=>'<_c>/<_a>',
'<_c:(post|comment)>/<id:\d+>'=>'<_c>/view',
'<_c:(post|comment)>s/*'=>'<_c>/list',
)
В примере выше мы используем два именованных параметра '<_c>' и '<_a>' в части маршрута. Параметр '<_c>' соответствует либо 'post', либо 'comment', а параметр '<_a>' соответствует идентификатору действия. Как и обычные правила, эти правила могут использоваться как для разбора, так и для создания URL-адресов. Например, используя правила выше, URL '/index.php/post/123/create' будет разборён как маршрут 'post/create' с параметром GET 'id' со значением 123. И, задав маршрут 'post/list' и параметр GET 'page' со значением 2, мы получим URL '/index.php/posts/page/2'.
Также возможно включение имени хоста в правила для разбора и создания URL-адресов. Можно извлечь часть имени хоста и использовать её как параметр GET. Например, URL
http://admin.example.com/en/profile может быть разборён на параметры GET user=admin и lang=en. С другой стороны, правила с именем хоста также могут использоваться для создания URL-адресов с параметризованными именами хостов. Для использования параметризованных имён хостов просто объявите правила URL-адресов с информацией о хосте, например:
array(
'http://<user:\w+>.example.com/<lang:\w+>/profile' => 'user/profile',
)
Начиная с версии 1.1.8, можно создавать пользовательские классы правил URL-адресов и использовать их для одного или нескольких правил URL-адресов. Например,
array(
// a standard rule
'<action:(login|logout)>' => 'site/<action>',
// a custom rule using data in DB
array(
'class' => 'application.components.MyUrlRule',
'connectionID' => 'db',
),
)
Обратите внимание, что пользовательский класс правила URL-адреса должен наследоваться от CBaseUrlRule и реализовывать следующие два метода: CUrlManager — это компонент приложения по умолчанию, к которому можно получить доступ через CWebApplication::getUrlManager().
Свойства Public
| Свойство | Тип | Описание | Определено в |
|---|---|---|---|
| appendParams | boolean | Добавлять ли параметры GET к части пути. | CUrlManager |
| baseUrl | string | Возвращает базовый URL приложения. | CUrlManager |
| behaviors | array | Поведения, которые должны быть присоединены к этому компоненту. | CApplicationComponent |
| cacheID | string | ID компонента кэширования, используемого для кэширования правил разбора URL. | CUrlManager |
| caseSensitive | boolean | Маршруты чувствительны к регистру. | CUrlManager |
| isInitialized | boolean | Проверяет, был ли инициализирован этот компонент приложения. | CApplicationComponent |
| matchValue | boolean | Значения параметров GET должны соответствовать соответствующим подшаблонам в правиле, прежде чем использовать его для создания URL-адреса. | CUrlManager |
| routeVar | string | Имя переменной GET для маршрута. | CUrlManager |
| rules | array | Правила URL-адресов (pattern=>route). | CUrlManager |
| showScriptName | boolean | Показывать ли имя скрипта входа в созданный URL-адрес. | CUrlManager |
| urlFormat | string | Возвращает формат URL-адреса. | CUrlManager |
| urlRuleClass | string | Имя класса или псевдоним пути для экземпляров правил URL-адресов. | CUrlManager |
| urlSuffix | string | Суффикс URL-адреса, используемый при формате 'path'. | CUrlManager |
| useStrictParsing | boolean | Включить строгий разбор URL-адресов. | CUrlManager |
Публичные методы
| Метод | Описание | Определено в |
|---|---|---|
| __call() | Вызывает метод по имени, который не является методом класса. | CComponent |
| __get() | Возвращает значение свойства, список обработчиков событий или поведение, основываясь на его имени. | CComponent |
| __isset() | Проверяет, является ли значение свойства нулевым. | CComponent |
| __set() | Устанавливает значение свойства компонента. | CComponent |
| __unset() | Устанавливает свойство компонента в значение null. | CComponent |
| addRules() | Добавляет новые правила URL. | CUrlManager |
| asa() | Возвращает объект поведения по имени. | CComponent |
| attachBehavior() | Прикрепляет поведение к этому компоненту. | CComponent |
| attachBehaviors() | Прикрепляет список поведений к компоненту. | CComponent |
| attachEventHandler() | Прикрепляет обработчик событий к событию. | CComponent |
| canGetProperty() | Определяет, можно ли прочитать свойство. | CComponent |
| canSetProperty() | Определяет, можно ли установить свойство. | CComponent |
| createPathInfo() | Создаёт информацию о пути на основе заданных параметров. | CUrlManager |
| createUrl() | Строит URL. | CUrlManager |
| detachBehavior() | Открепляет поведение от компонента. | CComponent |
| detachBehaviors() | Открепляет все поведения от компонента. | CComponent |
| detachEventHandler() | Открепляет существующий обработчик событий. | CComponent |
| disableBehavior() | Отключает прикреплённое поведение. | CComponent |
| disableBehaviors() | Отключает все прикреплённые к этому компоненту поведения. | CComponent |
| enableBehavior() | Включает прикреплённое поведение. | CComponent |
| enableBehaviors() | Включает все прикреплённые к этому компоненту поведения. | CComponent |
| evaluateExpression() | Вычисляет PHP выражение или обратный вызов в контексте этого компонента. | CComponent |
| getBaseUrl() | Возвращает базовый URL приложения. | CUrlManager |
| getEventHandlers() | Возвращает список прикреплённых обработчиков событий для события. | CComponent |
| getIsInitialized() | Проверяет, был ли инициализирован этот компонент приложения. | CApplicationComponent |
| getUrlFormat() | Возвращает формат URL. | CUrlManager |
| hasEvent() | Определяет, определено ли событие. | CComponent |
| hasEventHandler() | Проверяет, есть ли обработчики для данного события. | CComponent |
| hasProperty() | Определяет, определено ли свойство. | CComponent |
| init() | Инициализирует компонент приложения. | CUrlManager |
| parsePathInfo() | Парсит информацию о пути в URL сегменты и сохраняет их в $_GET и $_REQUEST. | CUrlManager |
| parseUrl() | Парсит запрос пользователя. | CUrlManager |
| raiseEvent() | Возбуждает событие. | CComponent |
| removeUrlSuffix() | Удаляет суффикс URL из информации о пути. | CUrlManager |
| setBaseUrl() | Устанавливает базовый URL приложения (часть после имени хоста и перед строкой запроса). | CUrlManager |
| setUrlFormat() | Устанавливает формат URL. | CUrlManager |
Защищённые методы
| Метод | Описание | Определено в |
|---|---|---|
| createUrlDefault() | Создаёт URL на основе стандартных настроек. | CUrlManager |
| createUrlRule() | Создаёт экземпляр правила URL. | CUrlManager |
| processRules() | Обрабатывает правила URL. | CUrlManager |
Подробное описание свойств
appendParams свойство
public boolean $appendParams;
присоединять параметры GET к части пути. По умолчанию true. Это свойство эффективно только когда urlFormat равен 'path' и используется главным образом при создании URL. Если true, параметры GET будут добавлены к пути, разделённые слешами. Если false, параметры GET будут в части запроса.
baseUrl свойство
public string getBaseUrl()
public void setBaseUrl(string $value)
Возвращает базовый URL приложения.
cacheID свойство
public string $cacheID;
идентификатор компонента кэширования приложения, используемого для кэширования обработанных правил URL. По умолчанию 'cache', что относится к основному компоненту кэширования. Установите это свойство в false, если хотите отключить кэширование правил URL.
caseSensitive свойство
public boolean $caseSensitive;
являются ли маршруты регистрозависимыми. По умолчанию true. Установив это в false, маршрут в входящем запросе сначала будет преобразован в нижний регистр перед дальнейшей обработкой. В результате вам следует придерживаться соглашения, что вы используете строчные буквы при указании сопоставления контроллеров (CWebApplication::controllerMap) и действий (CController::actions). Кроме того, имена каталогов для организации контроллеров должны быть в нижнем регистре.
matchValue свойство (доступно с версии v1.1.0)
public boolean $matchValue;
должны ли значения параметров GET соответствовать соответствующим подшаблонам в правиле перед использованием его для создания URL. По умолчанию false, что означает, что правило будет использоваться для создания URL только в том случае, если совпадают маршрут и имена параметров. Если это свойство установлено в true, то заданные значения параметров также должны соответствовать соответствующим параметрам подшаблонам. Обратите внимание, что установка этого свойства в true повлияет на производительность.
routeVar свойство
public string $routeVar;
имя переменной GET для маршрута. По умолчанию 'r'.
rules свойство
public array $rules;
правила URL (pattern=>route).
showScriptName свойство
public boolean $showScriptName;
отображать ли имя скрипта входа в сгенерированном URL. По умолчанию true.
urlFormat свойство
public string getUrlFormat()
public void setUrlFormat(string $value)
Возвращает формат URL.
urlRuleClass свойство (доступно с версии v1.1.8)
public string $urlRuleClass;
имя класса или псевдоним пути для экземпляров правил URL. По умолчанию 'CUrlRule'. Если вы измените это на что-то другое, убедитесь, что новый класс наследуется от CBaseUrlRule и имеет ту же сигнатуру конструктора, что и CUrlRule. Он также должен быть сериализуемым и доступным для автозагрузки.
urlSuffix свойство
public string $urlSuffix;
суффикс URL, используемый в формате «путь». Например, «.html» может использоваться, чтобы URL выглядел как указывающий на статическую HTML-страницу. По умолчанию пусто.
useStrictParsing свойство
public boolean $useStrictParsing;
включить строгий анализ URL. Это свойство эффективно только когда urlFormat равен 'path'. Если оно установлено в true, тогда входящий URL должен соответствовать одному из правил URL. В противном случае, он будет рассматриваться как неверный запрос и вызовет исключение 404 HTTP. По умолчанию false.
Подробное описание методов
addRules() метод (доступен начиная с версии v1.1.4)
public void addRules(array $rules, boolean $append=true) | ||
| $rules | массив | новые правила URL (шаблон=>маршрут). |
| $append | boolean | должны ли новые правила URL быть добавлены в конец существующих. Если false, они будут вставлены в начало. |
public function addRules($rules,$append=true)
{
if ($append)
{
foreach($rules as $pattern=>$route)
$this->_rules[]=$this->createUrlRule($route,$pattern);
}
else
{
$rules=array_reverse($rules);
foreach($rules as $pattern=>$route)
array_unshift($this->_rules, $this->createUrlRule($route,$pattern));
}
}
Добавляет новые правила URL. Для того, чтобы новые правила вступили в силу, этот метод должен быть вызван ДО CWebApplication::processRequest.
createPathInfo() метод
public string createPathInfo(array $params, string $equal, string $ampersand, string $key=NULL) | ||
| $params | массив | список параметров GET |
| $equal | строка | разделитель между именем и значением |
| $ampersand | строка | разделитель между парами имя-значение |
| $key | строка | используется внутри. |
| {return} | строка | созданный путь |
public function createPathInfo($params,$equal,$ampersand, $key=null)
{
$pairs = array();
foreach($params as $k => $v)
{
if ($key!==null)
$k = $key.'['.$k.']';
if (is_array($v))
$pairs[]=$this->createPathInfo($v,$equal,$ampersand, $k);
else
$pairs[]=urlencode($k).$equal.urlencode($v);
}
return implode($ampersand,$pairs);
}
Создаёт путь на основе заданных параметров.
createUrl() метод
public string createUrl(string $route, array $params=array ( ), string $ampersand='&') | ||
| $route | строка | контроллер и действие (например, article/read) |
| $params | массив | список параметров GET (имя=>значение). И имя, и значение будут закодированы в URL. Если имя равно '#', соответствующее значение будет рассматриваться как якорь и будет добавлен в конце URL. |
| $ampersand | строка | разделитель пар имя-значение в URL. По умолчанию '&'. |
| {return} | строка | сформированный URL |
public function createUrl($route,$params=array(),$ampersand='&')
{
unset($params[$this->routeVar]);
foreach($params as $i=>$param)
if($param===null)
$params[$i]='';
if(isset($params['#']))
{
$anchor='#'.$params['#'];
unset($params['#']);
}
else
$anchor='';
$route=trim($route,'/');
foreach($this->_rules as $i=>$rule)
{
if(is_array($rule))
$this->_rules[$i]=$rule=Yii::createComponent($rule);
if(($url=$rule->createUrl($this,$route,$params,$ampersand))!==false)
{
if($rule->hasHostInfo)
return $url==='' ? '/'.$anchor : $url.$anchor;
else
return $this->getBaseUrl().'/'.$url.$anchor;
}
}
return $this->createUrlDefault($route,$params,$ampersand).$anchor;
}
Строит URL.
createUrlDefault() метод
protected string createUrlDefault(string $route, array $params, string $ampersand) | ||
| $route | строка | контроллер и действие (например, article/read) |
| $params | массив | список параметров GET |
| $ampersand | строка | разделитель пар имя-значение в URL. |
| {return} | строка | сформированный URL |
protected function createUrlDefault($route,$params,$ampersand)
{
if($this->getUrlFormat()===self::PATH_FORMAT)
{
$url=rtrim($this->getBaseUrl().'/'.$route,'/');
if($this->appendParams)
{
$url=rtrim($url.'/'.$this->createPathInfo($params,'/','/'),'/');
return $route==='' ? $url : $url.$this->urlSuffix;
}
else
{
if($route!=='')
$url.=$this->urlSuffix;
$query=$this->createPathInfo($params,'=',$ampersand);
return $query==='' ? $url : $url.'?'.$query;
}
}
else
{
$url=$this->getBaseUrl();
if(!$this->showScriptName)
$url.='/';
if($route!=='')
{
$url.='?'.$this->routeVar.'='.$route;
if(($query=$this->createPathInfo($params,'=',$ampersand))!=='')
$url.=$ampersand.$query;
}
elseif(($query=$this->createPathInfo($params,'=',$ampersand))!=='')
$url.='?'.$query;
return $url;
}
}
Создаёт URL на основе стандартных настроек.
createUrlRule() метод (доступен начиная с версии v1.1.0)
protected CUrlRule createUrlRule(mixed $route, string $pattern) | ||
| $route | смешанный тип | часть правила маршрута. Может быть строкой или массивом |
| $pattern | строка | часть правила шаблона |
| {return} | CUrlRule | экземпляр правила URL |
protected function createUrlRule($route,$pattern)
{
if(is_array($route) && isset($route['class']))
return $route;
else
{
$urlRuleClass=Yii::import($this->urlRuleClass,true);
return new $urlRuleClass($route,$pattern);
}
}
Создаёт экземпляр правила URL. По умолчанию возвращает объект CUrlRule.
getBaseUrl() метод
public string getBaseUrl() | ||
| {return} | строка | базовый URL приложения (часть после имени хоста и перед строкой запроса). Если showScriptName true, он будет включать имя скрипта. В противном случае, он не будет, и конечные слэши будут удалены. |
public function getBaseUrl()
{
if($this->_baseUrl!==null)
return $this->_baseUrl;
else
{
if($this->showScriptName)
$this->_baseUrl=Yii::app()->getRequest()->getScriptUrl();
else
$this->_baseUrl=Yii::app()->getRequest()->getBaseUrl();
return $this->_baseUrl;
}
}
Возвращает базовый URL приложения.
getUrlFormat() метод
public string getUrlFormat() | ||
| {return} | строка | формат URL. По умолчанию 'path'. Допустимые значения включают 'path' и 'get'. См. руководство для более подробной информации о различиях между этими двумя форматами. |
public function getUrlFormat()
{
return $this->_urlFormat;
}
Возвращает формат URL.
init() метод
public void init() |
public function init()
{
parent::init();
$this->processRules();
}
Инициализирует компонент приложения.
parsePathInfo() метод
public void parsePathInfo(string $pathInfo) | ||
| $pathInfo | строка | путь |
public function parsePathInfo($pathInfo)
{
if($pathInfo==='')
return;
$segs=explode('/',$pathInfo.'/');
$n=count($segs);
for($i=0;$i<$n-1;$i+=2)
{
$key=$segs[$i];
if($key==='') continue;
$value=$segs[$i+1];
if(($pos=strpos($key,'['))!==false && ($m=preg_match_all('/\[(.*?)\]/',$key,$matches))>0)
{
$name=substr($key,0,$pos);
for($j=$m-1;$j>=0;--$j)
{
if($matches[1][$j]==='')
$value=array($value);
else
$value=array($matches[1][$j]=>$value);
}
if(isset($_GET[$name]) && is_array($_GET[$name]))
$value=CMap::mergeArray($_GET[$name],$value);
$_REQUEST[$name]=$_GET[$name]=$value;
}
else
$_REQUEST[$key]=$_GET[$key]=$value;
}
}
Разбирает путь в сегменты URL и сохраняет их в $_GET и $_REQUEST.
parseUrl() метод
public string parseUrl(CHttpRequest $request) | ||
| $request | CHttpRequest | компонент приложения запроса |
| {return} | строка | маршрут (controllerID/actionID) и, возможно, параметры GET в формате пути. |
public function parseUrl($request)
{
if($this->getUrlFormat()===self::PATH_FORMAT)
{
$rawPathInfo=$request->getPathInfo();
$pathInfo=$this->removeUrlSuffix($rawPathInfo,$this->urlSuffix);
foreach($this->_rules as $i=>$rule)
{
if(is_array($rule))
$this->_rules[$i]=$rule=Yii::createComponent($rule);
if(($r=$rule->parseUrl($this,$request,$pathInfo,$rawPathInfo))!==false)
return isset($_GET[$this->routeVar]) ? $_GET[$this->routeVar] : $r;
}
if($this->useStrictParsing)
throw new CHttpException(404,Yii::t('yii','Unable to resolve the request "{route}".',
array('{route}'=>$pathInfo)));
else
return $pathInfo;
}
elseif(isset($_GET[$this->routeVar]))
return $_GET[$this->routeVar];
elseif(isset($_POST[$this->routeVar]))
return $_POST[$this->routeVar];
else
return '';
}
Разбирает запрос пользователя.
processRules() метод
protected void processRules() |
protected function processRules()
{
if(empty($this->rules) || $this->getUrlFormat()===self::GET_FORMAT)
return;
if($this->cacheID!==false && ($cache=Yii::app()->getComponent($this->cacheID))!==null)
{
$hash=md5(serialize($this->rules));
if(($data=$cache->get(self::CACHE_KEY))!==false && isset($data[1]) && $data[1]===$hash)
{
$this->_rules=$data[0];
return;
}
}
foreach($this->rules as $pattern=>$route)
$this->_rules[]=$this->createUrlRule($route,$pattern);
if(isset($cache))
$cache->set(self::CACHE_KEY,array($this->_rules,$hash));
}
Обрабатывает правила URL.
removeUrlSuffix() метод
public string removeUrlSuffix(string $pathInfo, string $urlSuffix) | ||
| $pathInfo | строка | часть пути в URL |
| $urlSuffix | строка | суффикс URL, который нужно удалить |
| {return} | строка | путь с удалённым суффиксом URL. |
public function removeUrlSuffix($pathInfo,$urlSuffix)
{
if($urlSuffix!=='' && substr($pathInfo,-strlen($urlSuffix))===$urlSuffix)
return substr($pathInfo,0,-strlen($urlSuffix));
else
return $pathInfo;
}
Удаляет суффикс URL из пути.
setBaseUrl() метод (доступен с версии v1.1.1)
public void setBaseUrl(string $value) | ||
| $value | строка | базовый URL приложения |
public function setBaseUrl($value)
{
$this->_baseUrl=$value;
}
Устанавливает базовый URL приложения (часть после имени хоста и перед строкой запроса). Этот метод предоставляется на случай, если базовый URL не может быть определён автоматически. Конечные слэши должны быть удалены. Также вы несете ответственность за удаление имени скрипта, если вы установили showScriptName в false.
setUrlFormat() метод
public void setUrlFormat(string $value) | ||
| $value | строка | формат URL. Должен быть либо 'path', либо 'get'. |
public function setUrlFormat($value)
{
if($value===self::PATH_FORMAT || $value===self::GET_FORMAT)
$this->_urlFormat=$value;
else
throw new CException(Yii::t('yii','CUrlManager.UrlFormat must be either "path" or "get".'));
}
Устанавливает формат URL.
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CUrlManager