Фреймворк Invision Community предоставляет мощный вспомогательный класс для работы с URL-адресами, включая парсинг адресов и создание запросов (так же чтение ответов) URL-адресов. Программное обеспечение автоматически использует cURL, если доступно, и обратно возвращается к стандартным сокетам (это поведение также может быть переопределено константами, если среда хочет принудительно использовать cURL или сокеты).
Работа с URL-адресами
Класс \IPS\Http\Url используется для работы с URL-адресами, а два вспомогательных метода образуют основной интерфейс для создания объекта URL с этим классом:
- internal(): Используйте этот метод при создании внутреннего URL-адреса, например URL-адрес форума или темы. Этот метод автоматически создаёт дружественные URL-адреса, если необходимо.
- external(): Передайте полный URL-адрес этому методу для создания объекта URL-адреса из строки URL-адреса.
// Создание URL-адреса на тему с ID = 1
$url = \IPS\Http\Url::internal( 'app=forums&module=forums&controller=topic&id=1', 'front', 'forums_topic', array( 'topic-friendly-slug' ) );
$url = \IPS\Http\Url::external( 'https://www.google.com' );
// Создание объекта URL для стандартной строки URL
Внутренний метод принимает следующие параметры:
- Строка запроса URL-адреса.
- 'база' ('front' или 'admin', в зависимости от того, является ли URL-адрес на страницу админцентра или нет).
- SEO шаблон, если применимо.
- Массив SEO слагов, если шаблон их вызывает.
- Константу PROTOCOL_* из класса \IPS\Http\Url для переопределения должен ли быть сгенерирован http или https URL-адрес. Вы можете опустить этот параметр и позволить программному обеспечению правильно определить протокол, который будет использоваться автоматически.
Внешний метод просто принимает строку URL-адреса.
Если вы не уверены, что объект URL, который вы создаете, является внутренним или внешним, вы можете альтернативно использовать метод createFromString() (передавая полный URL-адрес так же, как и с помощью метода external()), однако обратите внимание, что этот метод является ресурсоёмким по производительности и предпочтительны непосредственно методы internal() и external(). Первым параметром для этого метода является URL-адрес, второй параметр - логический флаг, указывающий, может ли URL-адрес являться дружественным внутренним URL-адресом, а третий и последний параметр - логическим флагом, указывающим, хотите ли вы автоматически кодировать любые недопустимые компоненты вместо того, чтобы бросать ошибку (по умолчанию FALSE - установите значение TRUE, если URL-адрес предоставлен пользователем и не должен выдавать ошибку).
Вы можете внести корректировки в URL-адрес после создания объекта URL-адреса, вызвав различные методы.
- setScheme(): Вы можете передать схему в (то есть http или https), или передать в NULL для использования относительной схемы (то есть без схемы вовсе).
- setHost(): Принимает полное имя хоста.
- setPath(): Принимает полный допустимый путь.
- setQueryString(): Принимает ключ строки запроса в качестве первого параметра и его значение как второй параметр ИЛИ массив пар ключ => значение в качестве первого параметра.
- setFragment(): Принимает фрагмент.
- stripQueryString(): Принимает ключ строки запроса или массив ключей скроки запроса и удаляет эти параметры строки запроса (если есть) из URL-адреса.
Когда вы хотите вывести URL-адрес, вы можете использовать объект \IPS\Http\Url как строку:
print (string) $urlObject;
Класс имеет несколько дополнительных свойств и методов, на которые вы, возможно, захотите ссылаться или вызывать, описанные ниже:
- isInternal: свойство указывает, является ли URL-адрес внутренним или нет.
- isFriendly: свойство указывает, является ли URL-адрес дружественным (внутренним) URL-адресом или нет.
- queryString: свойство является массивом ключ => значение параметров строки запроса в URL-адресе.
- hiddenQueryString: свойство является массивом ключ => значение параметров строки запроса, которые были бы, если URL-адрес не был дружественным URL-адресом. Например, если вы создаете внутренний дружественный объект URL, это свойство будет содержать связанные параметры строки запроса, которые не отображаются (поскольку используется дружественный URL-адрес).
- csrf(): Вызовите этот метод, чтобы добавить ключ CSRF текущего пользователя в URL-адрес как аргумент строки запроса. Затем это будет проверено контроллерами для предотвращения атак типа CSRF. Если у вас есть запрос на изменение состояния, который не использует класс \IPS\Helpers\Form, обычно должны проверять ключ CSRF.
- (static) seoTitle(): Вы можете вызвать этот метод, чтобы создать допустимый дружественный URL слаг. Обычно это используется, когда контент уже добавлен и URL слаг сохранён для следующего обращения, однако вы можете также вызывать этот метод «на лету», если это необходимо.
Создание запросов
Создав объект класса \IPS\Http\Url, вы можете делать запросы к нему. Для этого вызывается метод request().
/**
* Make a HTTP Request
*
* @param int|null $timeout Timeout
* @param string $httpVersion HTTP Version
* @param bool|int $followRedirects Automatically follow redirects? If a number is provided, will follow up to that number of redirects
* @return \IPS\Http\Request
*/
public function request( $timeout=null, $httpVersion=null, $followRedirects=5 )
Он возвращает объект \IPS\Http\Request. Ниже приведены некоторые методы, которые вы можете вызвать перед выполнением запроса:
- login(): Принимает имя пользователя в качестве первого параметра и пароль в качестве второго параметра и выполняет основной запрос авторизации по URL.
- setHeaders(): Принимает массив пар ключ => значение заголовков, которые должны быть включены в запрос.
- sslCheck(): Принимает логическое значение true или false как единственный параметр, сигнализирующий, должны ли проверяться SSL сертификаты или нет. В большинстве случаев это должно быть оставлено по умолчанию (true), если только вы не знаете, что SSL URL-адрес, к которому вы делаете запрос, имеет недопустимый сертификат.
- forceTls(): Обязать TLS для запроса. Это прежде всего используется с некоторыми платежными шлюзами, которые обеспечивают выполнение запросов TLS.
Впоследствии вы можете сделать запрос. Для этого вы вызываете метод запроса, который хотите выполнить (например для выполнения GET запроса, нужно вызвать метод get(), для PUT запроса соответственно put()), передавая любые параметры, которые должны быть включены в запрос (для запросов POST и PUT).
$request = \IPS\Http\Url::external( "http://someurl.com" )->request()->get();
Это возвращает объект \IPS\Http\Response, который вы можете теперь проверять и манипулировать по мере необходимости. Во-первых, есть несколько полезных свойств, которые вам могут потребоваться:
- httpResponseVersion: Версия протокола HTTP запроса (1.0 или 1.1, обычно).
- httpResponseCode: Код ответа HTTP. Возможно, вам потребуется проверить, что после запроса был возвращен действительный код ответа (т.е. 200).
- httpResponseText: Это текст ответа HTTP. Например, для запроса 200 это будет "ОК".
- httpHeaders: Массив, содержащий все HTTP заголовки ответа в виде пар ключ => значение.
- cookies: Массив всех заголовков Set-Cookie в виде пар ключ => значение.
- content: Тело ответа.
Отправка ответа в виде строки возвращает свойство содержимого, указанное выше.
В классе \IPS\Http\Response есть несколько методов, которые можно использовать, чтобы упростить работу с некоторыми распространенными ответами.
- decodeJson(): Вызов этого метода запустит ответ через json_decode перед его возвратом. Если ответ не в формате JSON, будет выброшено исключение RuntimeException.
- decodeXml(): Вызов этого метода спарсит ответ как XML, если ответ не в формате XML, будет выброшено исключение RuntimeException.
Кроме того, стоит отметить, что если запрос по какой-либо причине даёт сбой (например, тайм-аут подключения к удалённому серверу), выбрасывается исключение \IPS\Http\Request\Exception. С этой целью вы должны оборачивать запросы в блоки try/catch.
// Create a URL object
$url = \IPS\Http\Url::external( "http://someurl.com" )->setQueryString( 'key', 'value' );
// Построение и декодирование с помощью JSON
try
{
$response = $url->request()->get()->decodeJson();
}
catch( \IPS\Http\Request\Exception $e )
{
die( "There was a problem fetching the request" );
}
catch( \RuntimeException $e )
{
die( "The response was not valid JSON" );
}
var_dump( $response );
exit;