1. Документация
  2. Для разработчика сайта
  3. Функции и классы
  4. Встроенные классы

Класс Url

Методы для работы с URL.

Url::convertToAbsolute($url, $baseUrl=null)

Преобразует URL в любом виде в абсолютный URL.

  • Возвращает абсолютный URL (строка).
  • $url — URL в любом виде (строка).
  • $baseUrl — абсолютный URL отправной страницы (со слешем на конце). Если $baseUrl не указано, берется URL главной страницы сайта.

Url::convertToRelative($url, $baseUrl=null)

Преобразует URL в любом виде в относительный URL.

  • Возвращает относительный URL (строка).
  • $url — URL в любом виде (строка).
  • $baseUrl — абсолютный URL отправной страницы (со слешем на конце). Если $baseUrl не указано, берется URL главной страницы сайта.

Url::decode($str)

Метод используется для раскодирования строк, закодированных методом Url::encode().

  • Возвращает раскодированную строку.
  • $str — строка, закодированная методом Url::encode().

Url::encode($str)

Кодирует строку следующими знаками: буквы латинского алфавита обоих регистров, цифры, дефис и нижняя черта.

  • Возвращает закодированную строку
  • $str — любая строка.

Используется обычно для передачи через URL другого URL как параметра, в основном в служебных скриптах системы управления. Хотя для этой цели годится и функция urlencode(), однако последняя не подойдет для повторной передачи того же параметра, так как при получении параметр будет автоматически раскодирован.

Закодированный же методом Url::encode() параметр можно подвергать многократным редиректам. В конце цепочки передач этот параметр нужно раскодировать с помощью метода Url::decode(). Кодирование основано на функции base64_encode() с доп. заменой трех запрещенных в URL знаков: +/=.

Url::exists($url)

Проверить, существует ли URL. Рекомендуется использовать для внешних ссылок.

  • Возвращает true|false.
  • $url — абсолютный URL.

Url::parse($url)

Разбирает URL вида:
http://username:password@hostname:port/path?query#fragment
и возвращает его компоненты.

  • Возвращает массив компонентов URL.
  • $url — абсолютный URL.

Данный метод сделан на основе php-функции parse_url(). Отличие заключается в том, что метод возвращает элементы массива вместе со спецсимволами URL. Таким образом, собрать URL можно путем конкатенации элементов массива: 

$c = Url::parse($url);
#url2 = 
     $c['scheme']
    .$c['username']
    .$c['password']
    .$c['hostname']
    .$c['port']
    .$c['path']
    .$c['query']
    .$c['fragment']
;

Сравнение возвращаемых массивов:

Url::parse()
'scheme' => http://
'host' => hostname
'port' => :port
'user' => username ИЛИ username@
'pass' => :password@
'path' => /path
'query' => ?query
'fragment' => #fragment
parse_url()
'scheme' => http
'host' => hostname
'port' => port
'user' => username
'pass' => password
'path' => /path
'query' => query
'fragment' => fragment

Url::punyDecode($url)

Декодирует доменное имя в составе URL из punycode в оригинальный вид.

  • Возвращает URL в национальном алфавите, если было закодировано в punycode (например, http://xn--90at9a.xn--p1ai/новости/ в http://члб.рф/новости/)
  • $url — URL или доменное имя (строка).

Пример: $decodedUrl = Url::punyDecode($encodedUrl);

Url::punyEncode($url)

Кодирует доменное имя, написанное не ASCII-символами, в составе URL в punycode, который будет состоять только из алфавитно-цифровых символов, разрешенных в доменных именах.

  • Возвращает URL с доменом, закодированным в punycode (например, http://члб.рф/новости/ в http://xn--90at9a.xn--p1ai/новости/)
  • $url — URL или доменное имя (строка).

Пример: $encodedUrl = Url::punyEncode($url);

По состоянию на ноябрь 2015 года, для современных браузеров кодирование URL производить не нужно, кроме Mozilla Firefox.

Url::arrayToQuery($arr, $options=[])

Аналог функции http_build_query(). Отличие данного метода заключается в том, что квадратные скобки самого массива не кодируются — кодируются только значения.
  • Возвращает строку с URL параметрами. Значения параметров кодируются функцией urlencode(). В начале строки присутствует знак &.
  • $arr — массив любой размерности, как правило, полченный из Request::get();
  • $options — массив с опциями: 
    $options = [
    'encode'=>true, # Кодировать значения параметров с помощью функции urlencode()..
];

    Можно применять короткую форму записи опций — см. Arr::formatOptions().

Пример: echo Url::arrayToQuery(['pick' => [1=>['eq'=>3], 2=>['eq'=>'https://bloxcms.net']]]);
выведет '&pick[1][eq]=3&pick[2][eq]=https%3A%2F%2Fbloxcms.net'.

См. также Request::convertToQuery()

Url::queryToArray($phref, $options=[])

  • Возвращает ассоциативный массив.
  • $phref — относительный параметрический URL вида ?page=2&block=4&... (или фрагмент url-запроса).
  • $options — массив с опциями: 
    $options = [
    'decode'=>true, # Декодировать значения параметров с помощью функции urldecode().
    'remove-lost'=>true, # Удалить элементы с потерянными значениями, 
        # то есть, знак "=" после имени параметра имеется, но значение пусто.
];

    Можно применять короткую форму записи опций — см. Arr::formatOptions().

Url::redirect($url, $options=[])

Метод для перенаправления на другой URL.

  • Возвращает false при попытке перенаправить на адрес страницы, которая привела пользователя на текущую страницу (только при наличии опции loopProtection).
  • $url — URL целевой страницы может быть в любом виде: в параметрическом или человекопонятном, в абсолютном или относительно главной страницы (строка).
  • $options — массив опций. Ниже приведены опции по умолчанию: 
    $options = [
    'exit'=>false, # Сразу прекратить выполнение скрипта и перенаправить.
    
    'status'=>301, # Код статуса перенаправления (трехзначное число, начинающееся с цифры 3), 
    # по умолчанию 301 (Moved Permanently), то есть, перемещено навсегда.
    
    'replacements'=>[], # Регулярные замены в $url. 
    # Структура массива: [$pattern1 => $replacement1, ...] 
  
    'loop-protection'=>false, # Защита от циклической переадресации
    # Пример: 
    # if (!Url::redirect($href, ['loop-protection'=>true,'exit'=>true]) foo();
    # Если при перенаправлении произойдет зацикливание, будет выполнена функция foo().

    'puny-encode'=>false, # Конвертировать доменное имя в punycode.
    # По состоянию на ноябрь 2015 года, для современных браузеров
    # кодирование URL производить не нужно, кроме Mozilla Firefox.
];
    Короткая форма записи для булевых опций

    Для булевых опций можно применять короткую форму записи. Подробности см. в описании метода Arr::formatOptions(), который и применен внутри описываемого метода.

    • Булевы опции допустимо записывать как неассоциативный массив:
      $options = ['exit', 'puny-encode'];

    • Более того, если опция только одна, допустимо записывать ее в виде строки:
      $options = 'exit';

Список всех кодов для опции status:
300: Multiple Choices (множество выборов)
301: Moved Permanently (перемещено навсегда)
302: Moved Temporarily (перемещено временно, устарело, используй 303 или 307)
302: Found (найдено, устарело, используй 303 или 307)
303: See Other (смотреть другое, использовать вместо 302)
304: Not Modified (не изменялось)
305: Use Proxy (использовать прокси)
306: зарезервировано, код использовался только в ранних спецификациях
307: Temporary Redirect (временное перенаправление, использовать вместо 302)

Пример шаблона для перенаправления

redirect.tpl 
<?php

# Режим посетителя, но не во время назначения шаблона
if (empty($edit) && !in_array(Blox::getScriptName(), ['change','check'])) {
    if ($dat[1]) 
        Url::redirect($dat[1],'exit'); }
# В режиме редактирования
else {
    echo $dat['edit'];
    echo '
    Блок для перенаправления на страницу: <a href='$dat[1]' target='_blank'>$dat[1]</a><br>
    В режиме посетителя эта страница открываться не будет, и перенаправление произойдет
    автоматически.';
}
?>

redirect.tdd 
<?php
    $titles[1] = 'URL страницы (например: http://site.ru/)';
    $types[1] = 'varchar(255)';
    $params['description'] = 'Шаблон для перенаправления на другую страницу. 
    Для внутренних страниц желательно использовать относительные 
    параметрические ссылки (например: ?page=22&block=33&part=4).';
?>

Url::redirectToReferrer($options=[])

Перенаправление обратно на предыдущую страницу. Описание параметра $options см. выше в Url::redirect().

Если в URL есть параметр pagehref, он кодируется заново, так как в $_SERVER['HTTP_REFERER'] этот параметр идет в раскодированном виде.