Класс CURLRequest

Класс CURLRequest — это лёгкий HTTP-клиент, основанный на cURL, который позволяет взаимодействовать с другими веб-сайтами и серверами. Он может использоваться для получения содержимого результата поиска Google, извлечения веб-страницы или изображения, а также для взаимодействия с API и многим другим.

• Настройка для CURLRequest
  • Параметры совместного использования
• Загрузка библиотеки
• Работа с библиотекой
  • Отправка запросов
  • Использование ответов
• Параметры запроса
  • allow_redirects
  • auth
  • body
  • cert
  • connect_timeout
  • cookie
  • debug
  • delay
  • form_params
  • headers
  • http_errors
  • json
  • multipart
  • query
  • timeout
  • user_agent
  • verify
  • version

Этот класс моделируется по библиотеке Guzzle HTTP Client, так как она является одной из наиболее широко используемых библиотек. В возможных случаях синтаксис сохранён для того, чтобы, если вашему приложению требуется что-то немного более мощное, чем предлагает эта библиотека, вам нужно будет изменить очень мало, чтобы перейти к использованию Guzzle.

Настройка для CURLRequest

Параметры совместного использования

По историческим причинам по умолчанию CURLRequest разделяет все параметры между запросами. Если вы отправляете более одного запроса с экземпляром класса, это поведение может привести к ошибочному запросу с ненужными заголовками.

Вы можете изменить поведение, изменив значение следующего параметра конфигурации в файле app/Config/CURLRequest.php на false.

public $shareOptions = false;

Загрузка библиотеки

Библиотеку можно загрузить вручную или через класс Services.

Для загрузки с помощью класса Services вызовите метод curlrequest().

$client = \Config\Services::curlrequest();

Вы можете передать массив с параметрами по умолчанию в качестве первого параметра для изменения обработки запроса cURL. Параметры описаны позже в этом документе:

$options = [
    'baseURI' => 'http://example.com/api/v1/',
    'timeout'  => 3,
];
$client = \Config\Services::curlrequest($options);

При ручном создании класса вам нужно передать несколько зависимостей. Первый параметр — экземпляр класса Config\App. Второй параметр — экземпляр URI. Третий параметр — объект Response. Четвертый параметр — необязательный массив $options.

$client = new \CodeIgniter\HTTP\CURLRequest(
    new \Config\App(),
    new \CodeIgniter\HTTP\URI(),
    new \CodeIgniter\HTTP\Response(new \Config\App()),
    $options
);

Работа с библиотекой

Работа с запросами cURL сводится к созданию объекта запроса и получению объекта Response. Он предназначен для обработки связи. После этого у вас есть полный контроль над тем, как обрабатывается информация.

Отправка запросов

Большинство взаимодействий осуществляется через метод request(), который отправляет запрос и возвращает вам экземпляр Response. Он принимает HTTP-метод, URL и массив параметров.

$client = \Config\Services::curlrequest();

$response = $client->request('GET', 'https://api.github.com/user', [
    'auth' => ['user', 'pass'],
]);

Поскольку ответ является экземпляром CodeIgniter\HTTP\Response, у вас доступна вся обычная информация:

echo $response->getStatusCode();
echo $response->getBody();
echo $response->getHeader('Content-Type');
$language = $response->negotiateLanguage(['en', 'fr']);

Хотя метод request() является наиболее гибким, вы также можете использовать следующие сокращённые методы. Каждый из них принимает URL в качестве первого параметра и массив параметров во втором.

$client->get('http://example.com');
$client->delete('http://example.com');
$client->head('http://example.com');
$client->options('http://example.com');
$client->patch('http://example.com');
$client->put('http://example.com');
$client->post('http://example.com');

Базовый URL

Базовый URL может быть установлен как один из параметров при создании экземпляра класса. Это позволяет установить базовый URL и затем отправлять все запросы с этим клиентом, используя относительные URL. Это особенно полезно при работе с API:

$client = \Config\Services::curlrequest([
    'baseURI' => 'https://example.com/api/v1/',
]);

// GET http:example.com/api/v1/photos
$client->get('photos');

// GET http:example.com/api/v1/photos/13
$client->delete('photos/13');

Когда относительный URL предоставляется методу request() или любому из сокращённых методов, он будет объединён с baseURI в соответствии с правилами, описанными в RFC 3986, разделе 5.2. Чтобы сэкономить ваше время, вот некоторые примеры того, как выполняются объединения.

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

Каждый вызов request() возвращает объект Response, который содержит много полезной информации и несколько полезных методов. Наиболее часто используемые методы позволяют определить сам ответ.

Вы можете получить код состояния и фразу причины ответа:

$code   = $response->getStatusCode(); // 200
$reason = $response->getReason(); // OK

Вы можете получить заголовки из ответа:

// Get a header line
echo $response->getHeaderLine('Content-Type');

// Get all headers
foreach ($response->getHeaders() as $name => $value) {
    echo $name .': '. $response->getHeaderLine($name) ."\n";
}

Тело можно получить с помощью метода getBody().

$body = $response->getBody();

Тело — это исходное тело, предоставленное удалённым сервером. Если тип содержимого требует форматирования, вам нужно будет убедиться, что ваш скрипт это обрабатывает:

if (strpos($response->getHeader('content-type'), 'application/json') !== false) {
    $body = json_decode($body);
}

Параметры запроса

В этом разделе описаны все доступные параметры, которые можно передать в конструктор, метод request() или любой из сокращённых методов.

allow_redirects

По умолчанию cURL следует за всеми заголовками «Location:», отправляемыми удалёнными серверами. Параметр allow_redirects позволяет изменить это поведение.

Если вы установите его в false, то перенаправления вообще не будут следовать:

$client->request('GET', 'http://example.com', ['allow_redirects' => false]);

Установив его в true, вы примените настройки по умолчанию к запросу:

$client->request('GET', 'http://example.com', ['allow_redirects' => true]);

// Sets the following defaults:
'max'       => 5, // Maximum number of redirects to follow before stopping
'strict'    => true, // Ensure POST requests stay POST requests through redirects
'protocols' => ['http', 'https'] // Restrict redirects to one or more protocols

Вы можете передать массив в качестве значения параметра allow_redirects для указания новых настроек вместо значений по умолчанию:

$client->request('GET', 'http://example.com', ['allow_redirects' => [
    'max'       => 10,
    'protocols' => ['https'] // Force HTTPS domains only.
]]);

auth

Позволяет предоставить данные авторизации для HTTP Basic и Digest авторизации. Ваш скрипт, возможно, должен будет выполнить дополнительные действия для поддержки аутентификации Digest — это просто передаёт имя пользователя и пароль. Значение должно быть массивом, где первый элемент — имя пользователя, а второй — пароль. Третий параметр должен указывать тип используемой аутентификации, либо basic или digest:

$client->request('GET', 'http://example.com', ['auth' => ['username', 'password', 'digest']]);

body

Существует два способа установить тело запроса для типов запросов, которые их поддерживают, таких как PUT или POST. Первый способ — использовать метод setBody().

$client->setBody($body) ->request('put', 'http://example.com');

Второй способ — передать параметр body. Это сделано для сохранения совместимости с API Guzzle и работает точно так же, как предыдущий пример. Значение должно быть строкой:

$client->request('put', 'http://example.com', ['body' => $body]);

cert

Чтобы указать расположение PEM-сертификата клиента, передайте строку с полным путём к файлу в качестве параметра cert. Если требуется пароль, установите значение в массив с первым элементом, как путь к сертификату, и вторым — пароль:

$client->request('get', '/', ['cert' => ['/path/getServer.pem', 'password']);

connect_timeout

По умолчанию CodeIgniter не накладывает ограничений на попытки cURL подключиться к веб-сайту. Если вам нужно изменить это значение, вы можете сделать это, передав количество времени в секундах с помощью параметра connect_timeout. Вы можете передать 0, чтобы ждать неопределённое время:

$response->request('GET', 'http://example.com', ['connect_timeout' => 0]);

cookie

Это указывает имя файла, который cURL должен использовать для чтения значений cookie и сохранения значений cookie. Это делается с помощью параметров CURL_COOKIEJAR и CURL_COOKIEFILE. Пример:

$response->request('GET', 'http://example.com', ['cookie' => WRITEPATH . 'CookieSaver.txt']);

debug

При передаче значения debug и установке его в значение true, это позволит включить дополнительную отладку, выводящую информацию в STDERR во время выполнения скрипта. Это делается путем передачи CURLOPT_VERBOSE и вывода результата. Таким образом, при запуске встроенного сервера через spark serve, вы увидите вывод в консоли. В противном случае, вывод будет записан в журнал ошибок сервера.

Вы можете передать имя файла в качестве значения для debug, чтобы вывод записывался в файл:

$response->request('GET', 'http://example.com', ['debug' => '/usr/local/curl_log.txt']);

delay

Позволяет приостановить выполнение на заданное количество миллисекунд перед отправкой запроса:

// Delay for 2 seconds
$response->request('GET', 'http://example.com', ['delay' => 2000]);

form_params

Вы можете отправить данные формы в запросе POST с типом контента application/x-www-form-urlencoded, передав ассоциативный массив в опцию form_params. Это установит заголовок Content-Type в значение application/x-www-form-urlencoded, если он ещё не установлен:

$client->request('POST', '/post', [
    'form_params' => [
        'foo' => 'bar',
        'baz' => ['hi', 'there'],
    ],
]);

headers

Хотя вы можете установить любые необходимые для запроса заголовки, используя метод setHeader(), вы также можете передать ассоциативный массив заголовков в качестве опции. Каждый ключ — это имя заголовка, а каждое значение — строка или массив строк, представляющие значения поля заголовка:

$client->request('get', '/', [
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept'     => 'application/json',
        'X-Foo'      => ['Bar', 'Baz'],
    ],
]);

Если заголовки переданы в конструктор, они рассматриваются как значения по умолчанию, которые будут переопределены более поздними массивами заголовков или вызовами метода setHeader().

http_errors

По умолчанию, CURLRequest завершится ошибкой, если возвращённый код HTTP больше или равен 400. Вы можете установить http_errors в false, чтобы вернуть содержимое вместо этого:

$client->request('GET', '/status/500');
// Will fail verbosely

$res = $client->request('GET', '/status/500', ['http_errors' => false]);
echo $res->getStatusCode();
// 500

json

Опция json используется для удобной загрузки данных в формате JSON в качестве тела запроса. Добавляется заголовок Content-Type со значением application/json, перезаписывая любой ранее установленный заголовок Content-Type. Данные, предоставляемые в этой опции, могут быть любым значением, которое принимает json_encode().

$response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

multipart

Когда вам нужно отправить файлы и другие данные через запрос POST, вы можете использовать опцию multipart, вместе с классом CURLFile. Значения должны быть ассоциативным массивом данных POST для отправки. Для более безопасного использования устаревший метод отправки файлов путём добавления имени файла с префиксом @ был отключён. Все файлы, которые вы хотите отправить, должны быть переданы как экземпляры CURLFile.

$post_data = [
    'foo'      => 'bar',
    'userfile' => new \CURLFile('/path/to/file.txt'),
];

query

Вы можете передать данные для отправки в качестве переменных строки запроса, передав ассоциативный массив в качестве опции query:

// Send a GET request to /get?foo=bar
$client->request('GET', '/get', ['query' => ['foo' => 'bar']]);

timeout

По умолчанию, функции cURL могут выполняться неограниченное время. Вы можете изменить это с помощью опции timeout. Значение должно быть количеством секунд, в течение которых функции должны выполняться. Используйте 0 для неограниченного ожидания:

$response->request('GET', 'http://example.com', ['timeout' => 5]);

user-agent

Позволяет указать User Agent для запросов:

$response->request('GET', 'http://example.com', ['user_agent' => 'CodeIgniter Framework v4']);

verify

Эта опция описывает поведение проверки SSL-сертификата. Если опция verify имеет значение true, это включает проверку SSL-сертификата и использует стандартный набор CA-сертификатов, предоставляемый операционной системой. Если установлено значение false, это отключит проверку сертификата (это небезопасно и позволяет атаки типа "человек посередине"). Вы можете установить строку, содержащую путь к набору CA-сертификатов, чтобы включить проверку с настроенным сертификатом. Значение по умолчанию — true:

// Use the system's CA bundle (this is the default setting)
$client->request('GET', '/', ['verify' => true]);

// Use a custom SSL certificate on disk.
$client->request('GET', '/', ['verify' => '/path/to/cert.pem']);

// Disable validation entirely. (Insecure!)
$client->request('GET', '/', ['verify' => false]);

version

Для установки используемого HTTP-протокола вы можете передать строку или число с номером версии (обычно 1.0 или 1.1, 2.0 в настоящее время не поддерживается):

// Force HTTP/1.0
$client->request('GET', '/', ['version' => 1.0]);