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 中。

mmaurice / qurl

维护者

详情