Основы библиотеки cURL PHP

Введение

cURL — библиотека с открытым исходным кодом, используемая для отправки HTTP-запросов с различных языков программирования, включая C, PHP и другие.

cURL также является программой командной строки, позволяющая взаимодействовать с множеством различных серверов.
Libcurl — это библиотека API для передачи, которую разработчики могут встроить в свои программы; cURL действует как автономная обёртка для библиотеки libcurl. Для libcurl имеются модули интеграции для работы с более чем 30 языками программирования.

cURL работает по множеству различных протоколов с синтаксисом URL. В данной статье рассмотрена работа библиотеки по протоколу HTTP/HTTPS.

Содержание:

• Настройка параметров сеанса

• Простой GET-запрос

• Простой POST-запрос

• Обработка исключений/ошибок

• Пример POST-запроса с телом формате JSON, обработкой исключений, и обработкой ответа от сервера

• Проверка SSL-сертификата

• Аутентификация на сервере

Модуль PHP cURL обычно включён по умолчанию. Если это не так, то в файле php.ini уберите точку с запятой (;) у строки extension=php_curl.dll.

Настройка параметров сеанса

Для установки параметра сеанса cURL используется функция curl_setopt.

<?php
  curl_setopt(CurlHandle $handle, int $option, mixed $value): bool

• handle — дескриптор  cURL, полученный из curl_init().

• option — параметр сеанса в виде CURLOPT_XXX.

• value — значение параметра option.

Функция возвращает true в случае успешного выполнения или false в случае возникновения ошибки.

Сразу несколько параметров сеанса можно установить с помощью функции curl_setopt_array.

<?php
  curl_setopt_array(CurlHandle $handle, array $options): bool

options — ассоциативный массив, определяющий устанавливаемые параметры и их значения. Ключи должны быть корректными константами для функции curl_setopt() или их целочисленными эквивалентами.
Функция возвращает true, если все параметры были успешно установлены. Если не удалось успешно установить какой-либо параметр, немедленно возвращается значение false, все последующие параметры игнорируются.

Роль параметров сеанса играют предопределённые константы. Рассмотрим основные из них.

CURLOPT_URL — параметр, который задает адрес ресурса, с которым вы хотите взаимодействовать или с которого хотите получить данные. Параметр является обязательным и должен быть установлен перед вызовом curl_exec().

CURLOPT_RETURNTRANSFER — константа, устанавливающая значение дескриптора cURL так, чтобы ответ от сервера возвращался в виде строкового значения вместо отправки непосредственно в поток вывода.
При установке CURLOPT_RETURNTRANSFER в значение true или 1, константа сообщает cURL вернуть ответ из HTTP-запроса в виде строки, которую затем можно сохранить в переменной или обработать по мере необходимости. Если этот параметр не задан или имеет значение false, ответ на HTTP-запрос будет отправлен непосредственно в поток вывода (например, в окно браузера или файл, установленный параметром CURLOPT_FILE).

CURLOPT_HEADER — параметр, который указывает, следует ли включать заголовок в ответ (true — для включения).Заголовок содержит информацию об ответе, такую как код состояния HTTP, тип содержимого и др.
Для получения информации об ответе также можно использовать функцию curl_getinfo()(будет рассмотрена позже в статье).

CURLOPT_HTTPHEADER — параметр cURL, который задает HTTP-заголовки, отправляемые вместе с запросом. Параметр принимает массив строк. Каждая строка должна содержать имя заголовка и его значение, разделенные двоеточием.

CURLOPT_POST — константа, указывающая, следует ли отправлять запрос методом POST. По умолчанию cURL отправляет GET-запросы. Если CURLOPT_POST установлен в значении 1 или true, то будет отправлен POST-запрос.

CURLOPT_POSTFIELDS — это параметр cURL, используемый для установки тела POST-запроса. Формат данных зависит от типа, указанного в заголовке Content-Type.

Простой GET-запрос

<?php
    // Инициализация сеанса cURL
    $ch = curl_init();
    // Установка URL
    curl_setopt($ch, CURLOPT_URL, "example.com");
    // Установка CURLOPT_RETURNTRANSFER (вернуть ответ в виде строки)
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    // Выполнение запроса cURL
	//$output содержит полученную строку
    $output = curl_exec($ch);
    // закрытие сеанса curl для освобождения системных ресурсов
    curl_close($ch);      
?>

Простой POST-запрос

Чтобы сделать POST-запрос, нужно установить параметры CURLOPT_POST и CURLOPT_POSTFIELDS.

<?php
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "http://www.example.com/api/resource");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, "name=value");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $output = curl_exec($ch);
    curl_close($ch);
    echo $output;
?>

Существует несколько форматов тела запроса:

1) Формат JSON

<?php
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json');
    curl_setopt($ch, CURLOPT_POSTFIELDS,"{key1:value1,key2:value2}");
?>

2) Строка запроса HTTP

<?php
    curl_setopt($ch, CURLOPT_POSTFIELDS,"key1=value1&key2=value2");
?>

3) Формат массива POST

<?php 
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: multipart/form-data');
    curl_setopt($ch, CURLOPT_POSTFIELDS, array("key1"=>"value1", "key2"=>"value2");
?>

Обработка исключений/ошибок

Обработка ошибок в ходе сеанса cURL осуществляется с помощью блока try-catch и функции curl_errno.

curl_errno — это функция, которая возвращает номер ошибки самой последней операции cURL. Она фиксирует ошибки, связанные с самими функциями curl, такие как проблемы с настройкой соединения, проблемы с отправкой или приемом данных, тайм-ауты или любая другая проблема, специфичная для библиотеки curl.

Другими словами, curl_error фиксирует ошибки, возникающие в библиотеке curl во время сеанса curl, и генерирует сообщения об этих ошибках.Сообщения содержат информацию о том, что пошло не так во время операции cURL, что может пригодиться во время отладки.

Важно проверять значение curl_error после операции cURL, чтобы убедиться, что операция завершена успешно, а также выявить и устранить любые ошибки, которые могли возникнуть.

Во время операции cURL могут возникнуть ошибки, которые не улавливаются curl_error. В основном, это ошибки на стороне сервера. Для обработки таких ошибок рекомендуется использовать блок try-catch.

Пример POST-запроса с телом формате JSON, обработкой исключений, и обработкой ответа от сервера

<?php
    // Определение параметров сеанса
    $CurlOptions = array(
        CURLOPT_URL 			 => 'http://domain-name/endpoint-path',
        CURLOPT_POST           => 1,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_HTTPHEADER     => array( 'Content-Type' => 'application/json' )
    );

    // в данном случае блок try нужен, чтобы также ловить явно вызываемые исключения
    try{
        
        // Сериализация тела запроса
        $data = array('field1' => 'value1', 'field2' => 'value2');
        $json_req = json_encode($data);
        // Установка тела запроса
        $CurlOptions[CURLOPT_POSTFIELDS] = $json_req;
        
        // Инициализация сеанса
        $ch = curl_init();    
        // установка параметров сеанса
        curl_setopt_array( $ch, $CurlOptions );
        // Выполнение запроса, в переменной хранится ответ от сервера
        $recieved_data = curl_exec( $ch );
        
        // Десериализация ответа в ассоциативный массив
        $data = json_decode( $recieved_data, true );
        
        // если в ходе сеанса произошла ошибка
        if (curl_errno($ch))
            // вызов исключения
            throw new Exception(curl_error($ch));
        
        //получение информацию о сеансе
        $info=curl_getinfo($ch);
        // если код HTTP-ответа не равен 200 (OK - запрос выполнен успешно)
        if ($info['http_code']!=200)
            // вызов исключения
            throw new Exception("Запрос не был успешен");
        
        // если ответ был десериализирован неправильно
        if ( $data === null or (!is_object($data) && !is_array($data))){
            // вызов исключения
            throw new Exception("Ошибка декодирования ответа");
        }
        // закрытие сеанса
        curl_close( $ch );
      
    }catch(Exception $e){
        // вывод ошибки
        print $e;
?>

В данном примере информация о последнем сеансе была получена с помощью функции curl_getinfo(). Функция возвращает массив информации о различных характеристиках сеанса, таких как код ответа HTTP, тип содержимого, общее время и т.д.

Проверка SSL-сертификата

Для проверки SSL-сертификата необходимо использовать константу CURLOPT_SSL_VERIFYPEER.

CURLOPT_SSL_VERIFYPEER — это константа, которая определяет, должен ли curl проверять подлинность SSL-сертификата. Если установлено значение true, curl проверяет SSL-сертификат, представленный удаленным сервером, и выдаёт ошибку, если это сертификат недействительный Если установлено значение false, curl не проверяет SSL-сертификат и разрешает подключение, даже если SSL-сертификат недействителен. Однако это может привести к уязвимостям в системе безопасности. По умолчанию установлено значение true.

Стоит отметить, что URL-адреса "http" не имеют SSL-сертификата для проверки, поэтому установка этой константы в значение true приведет к неудачному запросу к таким адресам.

Аутентификация на сервере

CURLOPT_HTTPAUTH — это константа, которая используется для установки типа HTTP-аутентификации, используемой для запроса.

<?php
    $CurlOptions = array(
      CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
      CURLOPT_USERPWD => "login:password");
?>

Константа принимает следующие значения:

• CURLAUTH_BASIC: Базовая аутентификация HTTP, которая отправляет имя пользователя и пароль по сети в виде обычного текста, легко перехватываемого другими.

• CURLAUTH_DIGEST: Аутентификация HTTP Digest, которая использует хэш-функцию для шифрования пароля перед отправкой его на сервер.

• CURLAUTH_GSSNEGOTIATE: HTTP GSS-Negotiate аутентификация, которая является способом обеспечения безопасной аутентификации с использованием Kerberos.

• CURLAUTH_NTLM: Аутентификация NTLM, которая представляет собой механизм запроса-ответа, используемый Windows. В данном случае используется концепция хэширования, аналогичная Digest, чтобы предотвратить перехват пароля.

• CURLAUTH_ANY: Сообщает cURL попробовать все поддерживаемые методы аутентификации. cURL автоматически выберет тот, который он сочтет наиболее безопасным.

• CURLAUTH_ANYSAFE: Работает аналогично CURLAUTH_ANY, но в этом случае cURL будет пробовать только безопасные методы (все методы кроме CURLAUTH_BASIC).

Значение по умолчанию: CURLAUTH_BASIC.

Значения могут быть объединены с помощью побитового ИЛИ. Например, CURLAUTH_BASIC | CURLAUTH_DIGEST. cURL выберет наиболее подходящий метод из представленных.

При использовании HTTPS все данные передаются в зашифрованном виде. При такой передаче CURLOPT_HTTPAUTH предоставляет дополнительные меры безопасности для обеспечения подлинности клиента и сервера и предотвращения несанкционированного доступа.

ИТОГ

cURL — удобная библиотека для передачи данных между клиентом и сервером. cURL позволяет взаимодействовать с множеством различных серверов по различным протоколам: http, https, ftp, gopher, telnet, dict, file и ldap.

Библиотека легка в использовании. cURL предоставляет инструменты для простых GET-запросов, но также имеет дополнительный функционал:

• работа с сертификатами HTTPS;

• загрузка файлов по протоколам HTTP и FTP (последнее можно сделать с помощью модуля FTP);

• использование прокси-серверы;

• cookies;

• аутентификация пользователей.