Spec-Zone.ru › Yii 1.1

CUrlManager

Пакет system.web
Наследование class CUrlManager » CApplicationComponent » CComponent
Реализует IApplicationComponent
С версии 1.0
Исходный код framework/web/CUrlManager.php
CUrlManager управляет URL-адресами веб-приложений Yii.

Он предоставляет функциональность построения 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 и реализовывать следующие два метода:
  • CBaseUrlRule::createUrl()
  • CBaseUrlRule::parseUrl()


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, они будут вставлены в начало.
Исходный код: framework/web/CUrlManager.php#240 (показать)
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} строка созданный путь
Исходный код: framework/web/CUrlManager.php#431 (показать)
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
Исходный код: framework/web/CUrlManager.php#283 (показать)
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
Исходный код: framework/web/CUrlManager.php#320 (показать)
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
Исходный код: framework/web/CUrlManager.php#263 (показать)
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, он будет включать имя скрипта. В противном случае, он не будет, и конечные слэши будут удалены.
Исходный код: framework/web/CUrlManager.php#467 (показать)
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'. См. руководство для более подробной информации о различиях между этими двумя форматами.
Исходный код: framework/web/CUrlManager.php#499 (показать)
public function getUrlFormat()
{
    return 
$this->_urlFormat;
}

Возвращает формат URL.

init() метод

public void init()
Исходный код: framework/web/CUrlManager.php#203 (показать)
public function init()
{
    
parent::init();
    
$this->processRules();
}

Инициализирует компонент приложения.

parsePathInfo() метод

public void parsePathInfo(string $pathInfo)
$pathInfo строка путь
Исходный код: framework/web/CUrlManager.php#393 (показать)
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 в формате пути.
Исходный код: framework/web/CUrlManager.php#362 (показать)
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()
Исходный код: framework/web/CUrlManager.php#212 (показать)
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.
Исходный код: framework/web/CUrlManager.php#453 (показать)
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 приложения
Исходный код: framework/web/CUrlManager.php#489 (показать)
public function setBaseUrl($value)
{
    
$this->_baseUrl=$value;
}

Устанавливает базовый URL приложения (часть после имени хоста и перед строкой запроса). Этот метод предоставляется на случай, если базовый URL не может быть определён автоматически. Конечные слэши должны быть удалены. Также вы несете ответственность за удаление имени скрипта, если вы установили showScriptName в false.

setUrlFormat() метод

public void setUrlFormat(string $value)
$value строка формат URL. Должен быть либо 'path', либо 'get'.
Исходный код: framework/web/CUrlManager.php#509 (показать)
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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API