Загрузка Kit UrlParser - Загрузка исходного кода Kit UrlParser

Kit UrlParser

Другие категории

Version 2.2.0

Скачать

Анализатор URL-адресов RFC 3986

UrlParser — это PHP-библиотека, которая предоставляет анализатор URL-адресов, соответствующий RFC 3986, и компонент URI, совместимый с PSR-7. Цель этой библиотеки — предоставить синтаксический анализатор, который точно реализует спецификацию RFC, в отличие от встроенной функции parse_url() , которая несколько отличается от спецификации.

Эта библиотека преследует две основные цели. Первым предоставляет информацию из проанализированных URL-адресов. Для этого библиотека реализует стандартный интерфейс обработки URI из PSR-7, а также предоставляет дополнительные методы, которые упрощают извлечение часто используемой информации из URL-адресов. Вторая цель — также разрешить модификацию указанных URL-адресов с использованием интерфейса стандарта PSR-7 в дополнение к нескольким дополнительным методам, которые упрощают некоторые задачи.

Хотя эта библиотека в основном предназначена для анализа URL-адресов, анализ просто основан на общем синтаксисе URI. Таким образом, эту библиотеку можно использовать для проверки и анализа любых других типов URI на основе общего синтаксиса. Библиотека не выполняет никакой проверки URL-адресов, специфичной для схемы.

В дополнение к режиму, совместимому с RFC 3986 по умолчанию, библиотека также предлагает параметры, которые позволяют анализировать URL-адреса, содержащие символы UTF-8 в различных компонентах URL-адреса, одновременно преобразуя их в соответствующие форматы с процентной кодировкой и IDN ascii.

Документация по API доступна по адресу: http://kit.riimu.net/api/urlparser/.

Требования

Минимальная поддерживаемая версия PHP — 5.6.
Библиотека зависит от следующих внешних библиотек PHP:
- psr/http-сообщение ( ^1.0 )
Библиотека зависит от следующих расширений PHP
- intl (требуется только поддержка IDN)

Установка

Установка с помощью Composer

Самый простой способ установить эту библиотеку — использовать Composer для обработки ваших зависимостей. Чтобы установить эту библиотеку через Composer, просто выполните следующие два шага:

Получите composer.phar , запустив установку Composer из командной строки в корне вашего проекта.
После запуска сценария установки файл composer.phar должен находиться в корне вашего проекта, и вы можете выполнить следующую команду:
```
 php composer.phar require "riimu/kit-urlparser:^2.1"
```

После установки этой библиотеки через Composer вы можете загрузить ее, включив vendor/autoload.php , созданный Composer во время установки.

Добавление библиотеки в качестве зависимости

Если вы уже знакомы с тем, как использовать Composer, вы также можете добавить библиотеку в качестве зависимости, добавив в свой проект следующий файл composer.json и выполнив команду composer install :

{
    "require" : {
        "riimu/kit-urlparser" : " ^2.1 "
    }
}

Ручная установка

Если вы не хотите использовать Composer для загрузки библиотеки, вы также можете загрузить библиотеку вручную, загрузив последнюю версию и распаковав папку src в свой проект. Затем вы можете включить предоставленный файл src/autoload.php для загрузки классов библиотеки.

Обратите внимание, что использование Composer также автоматически загрузит другие необходимые библиотеки PHP. Если вы устанавливаете эту библиотеку вручную, вам также необходимо будет сделать доступными другие необходимые библиотеки.

Использование

Использовать эту библиотеку относительно просто. Библиотека предоставляет класс анализа URL-адресов UriParser и класс объекта неизменяемого значения Uri , который представляет URL-адрес. Чтобы проанализировать URL-адрес, вы можете просто предоставить URL-адрес в виде строки методу parse() в UriParser , который возвращает экземпляр Uri , созданный на основе проанализированного URL-адреса.

Например:

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ uri = $ parser -> parse ( ' http://www.example.com ' );

echo $ uri -> getHost (); // Outputs 'www.example.com'

В качестве альтернативы вы можете просто полностью пропустить использование UriParser и просто указать URL-адрес в качестве параметра конструктора для Uri :

 <?php

require ' vendor/autoload.php ' ;
$ uri = new  Riimu  Kit  UrlParser  Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com'

Основное различие между использованием метода parse() и конструктора заключается в том, что метод parse() вернет значение null , если предоставленный URL-адрес не является допустимым URL-адресом, а конструктор выдаст исключение InvalidArgumentException .

Чтобы получить различные типы информации из URL-адреса, класс Uri предоставляет в помощь различные методы. Вот простой пример с обзором различных доступных методов:

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ uri = $ parser -> parse ( ' http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form ' );

echo $ uri -> getScheme () . PHP_EOL ;         // outputs: http
echo $ uri -> getUsername () . PHP_EOL ;       // outputs: jane
echo $ uri -> getPassword () . PHP_EOL ;       // outputs: pass123
echo $ uri -> getHost () . PHP_EOL ;           // outputs: www.example.com
echo $ uri -> getTopLevelDomain () . PHP_EOL ; // outputs: com
echo $ uri -> getPort () . PHP_EOL ;           // outputs: 8080
echo $ uri -> getStandardPort () . PHP_EOL ;   // outputs: 80
echo $ uri -> getPath () . PHP_EOL ;           // outputs: /site/index.php
echo $ uri -> getPathExtension () . PHP_EOL ;  // outputs: php
echo $ uri -> getQuery () . PHP_EOL ;          // outputs: action=login&prev=index
echo $ uri -> getFragment () . PHP_EOL ;       // outputs: form

print_r ( $ uri -> getPathSegments ());    // [0 => 'site', 1 => 'index.php']
print_r ( $ uri -> getQueryParameters ()); // ['action' => 'login', 'prev' => 'index']

Компонент Uri также предоставляет различные методы изменения URL-адреса, что позволяет создавать новые URL-адреса из отдельных компонентов или изменять существующие. Обратите внимание, что компонент Uri является неизменяемым объектом значения, а это означает, что каждый из модифицирующих методов возвращает новый экземпляр Uri вместо изменения существующего. Вот простой пример создания URL-адреса из его компонентов:

 <?php

require ' vendor/autoload.php ' ;

$ uri = ( new  Riimu  Kit  UrlParser  Uri ())
    -> withScheme ( ' http ' )
    -> withUserInfo ( ' jane ' , ' pass123 ' )
    -> withHost ( ' www.example.com ' )
    -> withPort ( 8080 )
    -> withPath ( ' /site/index.php ' )
    -> withQueryParameters ([ ' action ' => ' login ' , ' prev ' => ' index ' ])
    -> withFragment ( ' form ' );

// Outputs: http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form
echo $ uri ;

Как видно из предыдущего примера, компонент Uri также предоставляет метод __toString() , который предоставляет URL-адрес в виде строки.

Получение информации

Вот список методов, которые компонент Uri предоставляет для получения информации из URL-адреса:

getScheme() возвращает схему из URL-адреса или пустую строку, если URL-адрес не имеет схемы.
getAuthority() возвращает компонент из URL-адреса, состоящий из имени пользователя, пароля, имени хоста и порта в формате user-info@hostname:port
getUserInfo() возвращает компонент из URL-адреса, который содержит имя пользователя и пароль, разделенные двоеточием.
getUsername() возвращает декодированное имя пользователя из URL-адреса или пустую строку, если в URL-адресе нет имени пользователя.
getPassword() возвращает декодированный пароль из URL-адреса или пустую строку, если в URL-адресе нет пароля.
getHost() возвращает имя хоста из URL-адреса или пустую строку, если URL-адрес не имеет хоста.
getIpAddress() возвращает IP-адрес хоста, если хост является IP-адресом. В противном случае этот метод вернет null . Если был указан адрес IPv6, адрес возвращается без фигурных скобок.
getTopLevelDomain() возвращает домен верхнего уровня с хоста. Если хост отсутствует или хост представляет собой IP-адрес, вместо него будет возвращена пустая строка.
getPort() возвращает порт из URL-адреса или значение null если в URL-адресе нет порта. Этот метод также вернет null , если порт является стандартным для текущей схемы (например, 80 для http).
getStandardPort() возвращает стандартный порт для текущей схемы. Если схема отсутствует или стандартный порт для схемы неизвестен, вместо этого будет возвращено значение null .
getPath() возвращает путь из URL-адреса или пустую строку, если URL-адрес не имеет пути.
getPathSegments() возвращает массив декодированных сегментов пути (т.е. путь, разделенный каждой косой чертой). Пустые сегменты пути отбрасываются и не включаются в возвращаемый массив.
getPathExtension() возвращает расширение файла из пути или пустую строку, если URL-адрес не имеет пути.
getQuery() возвращает строку запроса из URL-адреса или пустую строку, если URL-адрес не имеет строки запроса.
getQueryParameters() анализирует строку запроса из URL-адреса с помощью функции parse_str() и возвращает массив проанализированных значений.
getFragment() возвращает фрагмент URL-адреса или пустую строку, если URL-адрес не имеет фрагмента.
__toString() возвращает URL-адрес в виде строки.

Изменение URL-адреса

Компонент Uri предоставляет различные методы, которые можно использовать для изменения URL-адресов и создания новых. Обратите внимание: поскольку класс Uri является неизменяемым объектом значения, каждый метод возвращает новый экземпляр Uri а не изменяет существующий.

withScheme($scheme) возвращает новый экземпляр с заданной схемой. Пустую схему можно использовать для удаления схемы из URL-адреса. Обратите внимание, что любая предоставленная схема нормализована к нижнему регистру.
withUserInfo($user, $password = null) возвращает новый экземпляр с заданным именем пользователя и паролем. Обратите внимание, что пароль игнорируется, если не указано имя пользователя. Пустое имя пользователя можно использовать для удаления имени пользователя и пароля из URL-адреса. Любой символ, который нельзя вставить в URL-адрес сам по себе, будет закодирован в процентах.
withHost($host) возвращает новый экземпляр с данным хостом. Пустой хост можно использовать для удаления хоста из URL-адреса. Обратите внимание, что этот метод не принимает международные доменные имена. Обратите внимание, что этот метод также преобразует хост в нижний регистр.
withPort($port) возвращает новый экземпляр с заданным портом. null можно использовать для удаления порта из URL-адреса.
withPath($path) возвращает новый экземпляр с заданным путем. Пустой путь можно использовать для удаления пути из URL-адреса. Обратите внимание, что любой символ, который не является допустимым символом пути, будет в URL-адресе закодирован в процентах. Однако существующие символы с процентной кодировкой не будут подвергаться двойному кодированию.
withPathSegments(array $segments) возвращает новый экземпляр с путем, созданным из массива сегментов пути. Все недопустимые символы пути в сегментах будут закодированы в процентах, включая косую черту и существующие символы в процентной кодировке.
withQuery($query) возвращает новый экземпляр с заданной строкой запроса. Пустую строку запроса можно использовать для удаления пути из URL-адреса. Обратите внимание, что любой символ, который не является допустимым символом строки запроса, будет в URL-адресе закодирован в процентах. Однако существующие символы с процентной кодировкой не будут подвергаться двойному кодированию.
withQueryParameters(array $parameters) возвращает новый экземпляр со строкой запроса, созданной на основе предоставленных параметров с помощью функции http_build_query() . Все недопустимые символы строки запроса в параметрах будут закодированы в процентах, включая амперсанд, знак равенства и существующие символы в процентной кодировке.
withFragment($fragment) возвращает новый экземпляр с заданным фрагментом. Пустую строку можно использовать для удаления фрагмента из URL. Обратите внимание, что любой символ, который не является допустимым символом фрагмента, будет в URL-адресе закодирован в процентах. Однако существующие символы с процентной кодировкой не будут подвергаться двойному кодированию.

UTF-8 и международные доменные имена

По умолчанию эта библиотека предоставляет анализатор, соответствующий RFC 3986. Спецификация RFC не разрешает использование символов UTF-8 в имени домена или любых других частях URL-адреса. Правильным представлением их в URL-адресе является использование стандарта IDN для доменных имен и процентного кодирования символов UTF-8 в других частях.

Однако, чтобы помочь вам справиться с символами в кодировке UTF-8, многие методы в компоненте Uri автоматически процентно кодируют любые символы, которые нельзя вставить в URL-адрес самостоятельно, включая символы UTF-8. Однако из-за сложностей метод withHost() не поддерживает символы в кодировке UTF-8.

По умолчанию анализатор также не анализирует URL-адреса, содержащие символы в кодировке UTF-8, поскольку это противоречило бы спецификации RFC. Однако синтаксический анализатор предоставляет два дополнительных режима анализа, которые позволяют использовать эти символы, когда это возможно.

Если вы хотите проанализировать URL-адреса, которые могут содержать символы UTF-8 в информации о пользователе (т. е. имени пользователя или пароле), пути, запросе или фрагментах URL-адреса, вы можете просто использовать режим анализа UTF-8. Например:

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ parser -> setMode ( Riimu  Kit  UrlParser UriParser:: MODE_UTF8 );

$ uri = $ parser -> parse ( ' http://www.example.com/föö/bär.html ' );
echo $ uri -> getPath (); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.html

Однако символы UTF-8 в доменном имени представляют собой немного более сложную проблему. Однако анализатор обеспечивает элементарную поддержку анализа этих доменных имен в режиме IDNA. Например:

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ parser -> setMode ( Riimu  Kit  UrlParser UriParser:: MODE_IDNA );

$ uri = $ parser -> parse ( ' http://www.fööbär.com ' );
echo $ uri -> getHost (); // Outputs: www.xn--fbr-rla2ga.com

Обратите внимание, что для использования этого режима анализа необходимо включить расширение PHP intl . Соответствующий режим анализа также может быть предоставлен конструктору компонента Uri с помощью второго параметра конструктора.

Хотя доступна поддержка анализа этих символов UTF-8, эта библиотека не предоставляет никаких методов для обратных операций, поскольку целью этой библиотеки является работа с URI, совместимыми с RFC 3986.

Нормализация URL-адресов

Поскольку спецификация RFC 3986 определяет некоторые URL-адреса как эквивалентные, несмотря на некоторые небольшие различия, эта библиотека выполняет минимальную нормализацию предоставленных значений. Вы можете столкнуться с этими случаями, например, при анализе URL-адресов, предоставленных пользователями. Наиболее заметные нормализации, с которыми вы можете столкнуться, следующие:

Компоненты scheme и host считаются нечувствительными к регистру. Таким образом, эти компоненты всегда будут нормализованы к нижнему регистру.
Номер порта не будет включен в строки, возвращаемые методами getAuthority() и __toString() если порт является стандартным портом для текущей схемы.
Процентные кодировки обрабатываются без учета регистра. Таким образом, эта библиотека преобразует шестнадцатеричные символы в верхний регистр.
Количество косых черт в начале пути в строке, возвращаемой __toString() может меняться в зависимости от того, имеет ли URL-адрес компонент authority или нет.
Процент закодированных символов в проанализированных и сгенерированных URI в компоненте userinfo может отличаться из-за того, что UriParser работает со спецификацией PSR-7, которая не предоставляет способа предоставления закодированного имени пользователя или пароля.