mmaurice / qurl
Simple QueryURL library (based on cURL)
Requires
- php: >=5.6
This package is auto-updated.
Last update: 2025-02-22 17:02:10 UTC
README
Класс библиотеки QueryURL представляет собой простой интерфейс для работы с cURL-библиотекой.
Установка
Установка производится через Composer:
composer require mmaurice/qurl
Примеры кода
Создание объекта
Для создания объекта нет нужды передавать какие-либо параметры в конструктор. Тогда будет создан базовый клиент.
use \mmaurice\qurl\Client; $client = new Client;
Задание параметров cURL
При создании клиента можно передавать в конструктор параметры cURL:
use \mmaurice\qurl\Client; $client = new Client([ CURLOPT_FOLLOWLOCATION => true, CURLOPT_SSL_VERIFYPEER => false, CURLOPT_RETURNTRANSFER => true, ]);
Так же параметры можно задавать методом setOption
. В таком случае, первым аргументом будет выступать константа параметра cURL, а вторым аргументом - его значение:
$client ->setOption(CURLOPT_FOLLOWLOCATION, true) ->setOption(CURLOPT_SSL_VERIFYPEER, false) ->setOption(CURLOPT_RETURNTRANSFER, true);
В случае необходимости задания массива параметров, можно воспользоваться методом setOptions
, который принимает массив значений, состоящий из констант параметров cURL в качестве ключей, и значений параметров в качестве значений массива:
$client->setOptions([ CURLOPT_FOLLOWLOCATION => true, CURLOPT_SSL_VERIFYPEER => false, CURLOPT_RETURNTRANSFER => true, ]);
Более подробно о параметрах cURL можно ознакомиться в соответствующем разделе документации.
Создание объекта запроса
Для начала конфигурирования запроса, необходимо воспользоваться методом request
, который имеет набор методов для настройки запроса:
$request = $client->request(); // Instance of \mmaurice\qurl\Request
Задание заголовков
Заголовки можно задать при помощи метода setHeader
. В таком случае, первым аргументом будет выступать имя заголовка, а вторым аргументом - его значение:
$request->setHeader('Accept-Encoding', 'gzip, deflate, br');
В случае необходимости задания массива заголовков, можно воспользоваться методом setHeaders
, который принимает массив значений, состоящий из имён заголовков в качестве ключей, и значений заголовков в качестве значений массива:
$request->setHeaders([ 'Accept-Language' => 'ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7', 'Cache-Control' => 'max-age=0', 'Connection' => 'keep-alive', ]);
Задание тела запроса
Тело запроса можно задать при помощи метода setBodyFields
. В качестве аргументов, метод принимает ассоциативный массив значений, которые далее будут сформированы в тело запроса. Например:
$request->setBodyFields([ 'foo' => 'bar', 'baz' => 'boo', ]);
В случае необходимости дополнить существующий массив параметров, можно воспользоваться методом setBodyField
. В таком случае, первым аргументом будет выступать ключ параметра, а вторым аргументом - его значение:
$request->setBodyField('foo', 'bar');
Хочется дополнительно отметить, что эта операция дополнит существующий набор параметров переданными.
Кроме этого, можно указать, как именно необходимо закодировать тело запроса, а именно - json, url-encoded строка и массив:
// Закодировать тело запроса в формате JSON // Будет автоматически установлен заголовок "Content-Type: application/json" $request->setBodyJson(); // Закодировать тело запроса в формате url-encoded строки // Будет автоматически установлен заголовок "Content-Type: application/x-www-form-urlencoded" $request->setBodyUrlEncode(); // Закодировать тело запроса в формате массива // Будет автоматически установлен заголовок "Content-Type: multipart/form-data" $request->setBodyMultipartFormData();
Прочие параметры запроса
Объект Request поддерживает настройку некоторых ключевых параметров запроса, а именно:
// Задать номер порта (CURLOPT_PORT), на который будет отправлен запрос $request->setPort(80); // Задать таймаут (CURLOPT_TIMEOUT) $request->setTimeout(5); // Задать таймаут соединения (CURLOPT_CONNECTTIMEOUT) $request->setTimeout(2); // Задать таймаут соединения (CURLOPT_USERAGENT) $request->setUserAgent('Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.13) Gecko/20080311 Firefox/2.0.0.13'); // Разрешить следовать редиректам (CURLOPT_FOLLOWLOCATION), а так же ограничить их количество (CURLOPT_MAXREDIRS) $request->setFollowLocation(true, 5);
Прочие параметры cURL можно задачть в настройках клиента.
Отправка запроса
Для отправки обыкновенного GET-запроса, необходимо воспользоваться методом get
, первым аргументом которого будет URL, на который отправляется запрос, вторым аргументом можно так же передавать тело запроса в виде массива параметров, а третьим аргументом можно передать массив заголовков. Тело запроса и заголовки можно не передавать, если они уже были переданы отдельными методами, или если запрос не подразумевает их передачу. В качестве результата запроса будет создан объект Response:
$response = $request->get($url, $body = [], $headers = []); // Instance of \mmaurice\qurl\Response
Запрос будет иметь следующий вид:
$response = $request->get('https://api.ipify.org/?format=json');
Важно отметить, что $url
можно задать и в виде массива, первым аргументом которого будет путь, а вторым аргументом - массив GET-параметров:
$response = $request->get([ 'https://api.ipify.org/', [ 'format' => 'json', ], ]);
Помимо этого, существует возможность отправить запросы методом post
, put
, head
, delete
, connect
, options
, path
, trace
, search
. Пример соответствующих методов выглядят следующим образом:
$response = $request->post($url, $body = [], $headers = []); $response = $request->put($url, $body = [], $headers = []); $response = $request->head($url, $body = [], $headers = []); $response = $request->delete($url, $body = [], $headers = []); $response = $request->connect($url, $body = [], $headers = []); $response = $request->options($url, $body = [], $headers = []); $response = $request->path($url, $body = [], $headers = []); $response = $request->trace($url, $body = [], $headers = []); $response = $request->search($url, $body = [], $headers = []);
Набор аргументов для этих методов идентичен набору аргументов для метода get
- в качестве первого аргумента передаётся URL запроса, а в качестве второго аргумента - массив полей тела запроса, а третьего аргумента - массив заголовков.
Все выше описанные методы являюся обёртками для основного метода запроса query
. Можно воспользоваться им напрямую, для создания любого типа запроса. Например:
use \mmaurice\qurl\Request; $response = $request->query(Request::GET, [ 'https://api.ipify.org/', [ 'format' => 'json', ], ]);
В качестве первого аргумента передаётся значение типа запроса. Все типы запросов перечислены в виде констант класса \mmaurice\qurl\Request
, а именно:
\mmaurice\qurl\Request::GET
\mmaurice\qurl\Request::POST
\mmaurice\qurl\Request::PUT
\mmaurice\qurl\Request::HEAD
\mmaurice\qurl\Request::DELETE
\mmaurice\qurl\Request::CONNECT
\mmaurice\qurl\Request::OPTIONS
\mmaurice\qurl\Request::PATH
\mmaurice\qurl\Request::TRACE
\mmaurice\qurl\Request::SEARCH
Получение результата
Одним из преимуществ данной библиотеки является возможность простым образом получить данные о сформированном запросе и полученном ответе. Можно получить следующие данные:
//Запрашиваемый URL $response->getRequestUrl(); //Заголовки запроса $response->getRequestHeader(); //Заголовки запроса без предварительной обработки $response->getRawRequestHeader(); //Тело запроса $response->getRequestBody(); //Тело запроса без предварительной обработки $response->getRawRequestBody(); //Заголовки ответа сервера $response->getResponseHeader(); //Заголовки ответа сервера без предварительной обработки $response->getRawResponseHeader(); //Тело ответа сервера $response->getResponseBody(); //Тело ответа сервера без предварительной обработки $response->getRawResponseBody(); //Ссылка перенаправления сервера (если передал) $response->getResponseRedirect(); //IP-адрес ответившего сервера $response->getResponseIp(); //Порт ответившего сервера $response->getResponsePort(); //Тип контента ответа $response->getResponseContentType(); //Код ответа сервера $response->getResponseCode(); //Сообщение сервера $response->getResponseMessage(); //Полное сообщение сервера $response->getResponseRawMessage();
Более наглядные примеры работы с библиотекой находятся в каталоге /examples
проекта.