Download the PHP package sqrt-pro/url without Composer

SQRT\URL

Терминология

Часть URL разделенная символом / называется аргумент. Например: /my/cool/page/. При этом важен порядок следования аргументов, т.к. адресация идет по номеру, начиная с 1. Т.е. после разбора примера выше, будет получен такой набор аргументов:

1 => 'my'
2 => 'cool'
3 => 'page'

Если нужно передать именованный параметр, он передается в виде "имя:значение", например: /id:12/height:yahoo/. При этом последовательность параметров не имеет значения. Аргументы и параметры можно комбинировать, но параметры всегда идут в конце URL. Например: /my/pretty/what:page/what:site/.

Если указывается несколько значений с одинаковым именем, они трактуются как массив. Например: /id:10/id:11/id:12/.

Кроме этого, можно использовать "имя файла", например /hello/world.txt. Оно связано с атрибутами, но не входит в их список.

Разбор URL

Всё начинается с создания объекта URL. Разбор адреса происходит при вызове parse(), в качестве аргументов можно передать строку (полный или абсолютный путь) или массив(будет обработан как набор параметров). Аналогично можно передавать параметры в конструктор, допускается указывать несколько объектов как аргументы.

Следующие вызовы идентичны по результату:

$u = new URL();
$u->parse('/my/page/id:12/hello:world/');
$u = new URL('/my/page/id:12/hello:world/'); 
$u = new URL('my/page', array('id'=>12, 'hello'=>'world'));
$u = new URL('my', 'page/id:12', array('hello'=>'world'));

Получение данных из адреса

Фильтрация входных данных

В большинство функций для получения данных из адреса передается параметр $filter - он позволяет проверять и фильтровать данные, получаемые из адреса. Фильтр может быть callable, regexp или массивом со списком допустимых значений. Если значения нет, или оно не проходит по фильтру возвращается $default.

Подробнее о фильтрации

Аргументы и параметры

После того, как адрес был разобран, объект URL предоставляет несколько способов доступа к аргументам и параметрам:

• hasArgument($num) - Проверка, есть ли аргумент;
• hasParameter($name) - Проверка, есть ли параметр;
• getArgument($num, $filter = null, $default = false) - Получить значение аргумента, если оно задано, иначе вернуть $default;
• getParameter($name, $filter = null, $default = false) - Получить значение параметра, если оно задано, иначе вернуть $default;
• getParameterAsArray($name, $filter = null, $default = array()) - Получить параметр как массив если значения заданы, иначе вернуть $default;
• getArguments() - Получить массив всех аргументов;
• getParameters() - Получить массив всех параметров.

Чтобы изменить аргументы или параметры, можно воспользоваться следующими возможностями:

• removeArguments(array $arguments = null) - Очистить аргументы. В $arguments можно сразу передать массив новых аргументов;
• removeParameters(array $parameters = null) - Очистить параметры. В $parameters можно сразу передать массив новых параметров;
• setArgument($num, $value = null) - Установка значения аргумента.
• setParameter($name, $value = null) - Установка значения параметра.
• addArgument($arg) - Добавление аргумента;
• addParameter($name, $parameter) - Добавление параметра;
• addArguments($mixed, $_) - Добавление аргументов. Может быть передано несколько аргументов сразу строкой или в массиве;
• addParameters($array, $_) - Добавление параметров. Может быть передано несколько массивов сразу;

Имя файла и расширение

Если указано имя файла, доступ к нему:

• getFileName($strict = false) - Получить имя файла. Если оно не было указано, берется значение последнего аргумента.
• getFileExtension($default = false) - Получить разрешение файла или $default если оно не указано.

Хост, схема и поддомены

Если при разборе адреса был указан абсолютный путь, объект URL содержит информацию о домене и схеме. Если адрес не был передан, по умолчанию задан домен http://localhost.

Доступ к данным:

• getHost() - домен. По-умолчанию "localhost";
• getScheme() - схема. По-умолчанию "http";
• hasSubDomain($level) - проверка, есть ли поддомен заданного уровня. Адресация справа, начиная с "1".
• getSubDomain($level, $filter = null, $default = false) - получить значение поддомена или $default если оно не задано.

Immutable-объект

Если на основе базового адреса нужно генерировать новые ссылки, не изменяя основной объект, можно воспользоваться классом URLImmutable - при вызове методов, изменяющих адрес возвращается новый объект, сохраняя оригинал неизменным.

Отображение URL

Объект URL имеет два варианта вывода адреса:

• asString($absolute = false) - возвращает строку с относительным или абсолютным адресом;
• asTag($value = null, $attr = null, $target = null, $absolute = false) - Генерация объекта HTML-ссылка. Подробнее об SQRT\Tag

Больше примеров использования в тестах /tests/unit/...