waNet

Отправка запросов к удалённым ресурсам

Содержание...

Класс предназначен для удобного выполнения запросов — с помощью расширения curl, а также функций file_get_contents и fsockopen. Класс автоматически использует тот из доступных методов (транспортов) отправки запросов — расширение либо одну из перечисленных функций, — который доступен на сервере, выполняет проверку на наличие ошибок при получении ответа, а также возвращает содержимое ответа, раскодированное в соответствии с указанным форматом.

Если вы считаете, что классу не хватает какой-либо объективно необходимой функциональности, оформляйте свои предложения в виде pull request в GitHub-репозитории фреймворка.

Порядок использования класса:

  1. Создать экземпляр класса, передав в него массив необходимых параметров.
  2. Если необходимо, вызвать «подготовительные» методы: cookies и userAgent.
  3. Для выполнения запроса вызвать метод query, который вернет содержимое ответа.
  4. Если необходимо, вызвать методы, возвращающие дополнительную информацию об ответе на запрос: getResponse и getResponseHeader.

Методы

  • cookies

    Устанавливает путь по умолчанию к файлу, содержащему cookies.

  • getResponse

    Возвращает содержимое последнего полученного ответа на запрос.

  • getResponseHeader

    Возвращает содержимое заголовков последнего полученного ответа.

  • query

    Выполняет запрос к указанному ресурсу.

  • multiQuery

    Параллельно выполняет несколько curl-запросов с функциями-обработчиками.

  • userAgent

    Устанавливает либо возвращает значение, которое будет использовано для заголовка "User-Agent".

public function __construct ($options, $custom_headers = array())

Параметры

  • $options

    Массив параметров для подключения к удаленному ресурсу. Допустимые ключи массива:

    • format: формат ожидаемого ответа: waNet::FORMAT_JSON (JSON), waNet::FORMAT_XML (XML) либо waNet::FORMAT_RAW (простой, не требующий стандартной обработки)
    • charset: кодировка отправляемого запроса; значение по умолчанию: 'utf-8'
    • authorization: флаг, обозначающий необходимость авторизации с использованием заголовка Authorization
    • login: имя пользователя для авторизации
    • password: пароль для авторизации
    • md5: флаг, обозначающий необходимость указания содержимого запроса, обработанного функциями md5 и base64_encode, в заголовке Content-MD5.
    • priority: массив со списком доступных способов отправки запроса (транспортов), определяющий также порядок их применения до обнаружения первого доступного на сервере; приоритет доступных транспортов по умолчанию:
      • 'curl' (расширение curl)
      • 'fopen' (функция file_get_contents())
      • 'socket' (функция fsockopen())
    • timeout: таймаут в секундах, в течение которого разрешено продолжать выполнение запроса
    • verify: путь к файлу сертификата для подтверждения достоверности запроса (для транспортов 'curl' и 'fopen')
    • ssl: массив параметров для подключения через 'curl' с использованием SSL-сертификата:
      • 'key' — значение для параметра CURLOPT_SSLKEY
      • 'cert' — значение для параметра CURLOPT_SSLCERT
      • 'password' — значение для параметра CURLOPT_SSLCERTPASSWD
    • proxy_host: хост прокси-сервера для отправки запросов с использованием транспортов 'curl' или 'fopen'
    • proxy_port: порт прокси-сервера
    • proxy_user: имя пользователя для авторизации на прокси
    • proxy_password: пароль для авторизации на прокси
    • log: путь к альтернативному файлу для сохранения логов в директории wa-log/; по умолчанию логи сохраняются в файл waNet.error.log
  • $custom_headers

    Ассоциативный массив дополнительных заголовков для выполнения запроса к удаленному ресурсу.

Пример

$options = array(
    'format'        => waNet::FORMAT_JSON
    'timeout'       => 10,
    'authorization' => true,
    'login'         => $login,
    'password'      => $password,
);
$net = new waNet($options);

public function cookies ($path)

Устанавливает путь по умолчанию к файлу, содержащему cookies, для использования в качестве параметра CURLOPT_COOKIEFILE при подключении через curl. Это значение по умолчанию используется, только если в параметрах подключения через curl не указан иной путь к файлу cookies.

Параметры

  • $path

    Путь к файлу cookies.

Пример

$net = new waNet($options);
$net->cookies($path);

public function getResponse ($raw = false)

Возвращает содержимое последнего полученного ответа на запрос.

Параметры

  • $raw

    Флаг, требующий возврата исходного (оригинального) либо раскодированного содержимого ответа на запрос. По умолчанию возвращается раскодированное содержимое. Формат раскодируемого значения должен совпадать со значением элемента 'format', переданного в конструктор класса.

Пример

$options['format'] = waNet::FORMAT_JSON;
$net = new waNet($options);
$decoded_response = $net->query($url);
$raw_response = $net->getResponse(true);

public function getResponseHeader ($header = null)

Возвращает содержимое заголовков последнего полученного ответа.

Параметры

  • $header

    Имя заголовка, содержимое которого нужно получить. Если не указано, метод вернет содержимое всех полученных заголовков.

Пример

$net = new waNet($options);
$response = $net->query($url);
$response_headers = $net->getResponseHeader();

public function query ($url, $content = [], $method = self::METHOD_GET, $callback = null)

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

Выполнение метода может привести к возникновению исключения, поэтому его вызов необходимо обернуть в блок try...catch для самостоятельной обработки ошибок. Код ошибки в этом случае соответствует коду ответа HTTP.

Параметры

  • $url

    URL отправки запроса

  • $content

    Содержимое запроса

  • $method

    Метод отправки запроса:

    • waNet::METHOD_GET — GET
    • waNet::METHOD_POST — POST (для транспортов 'curl' и 'fopen')
    • waNet::METHOD_PUT — PUT (для транспортов 'curl' и 'fopen')
    • waNet::METHOD_PATCH — PATCH (для транспортов 'curl' и 'fopen')
    • waNet::METHOD_DELETE — DELETE (для транспорта 'curl')
  • $callback

    Значение типа callable, которое должно быть запущено после завершения выполнения запроса. Поддерживается только для отправки запросов с использованием транспорта curl.

Пример

$net = new waNet($options);
$response = $net->query($url, $content, waNet::METHOD_POST, ['myClass', 'some_callback_method']);

public function multiQuery ($namespace = null, $options = [])

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

С другими транспортами отправки запросов, кроме curl, метод не работает.

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

  1. Вызвать метод с произвольным непустым значением параметра $namespace — для инициализации данных.
  2. Вызвать несколько раз метод query() со значением параметра $callback типа callable.
  3. Ещё раз вызвать метод multiQuery() с тем же значением параметра $namespace. В результате этого вызова будут одновременно запущены все запросы через curl, инициированные в шаге 2, для которых при вызове метода query() для параметра $callback был указано значение типа callable. Если значение $callback указано не было, то запросы выполняются не параллельно, а последовательно — сразу же при вызове метода query() в предыдущем шаге 2, не дожидаясь данного шага 3.

Параметры

  • $namespace

    Произвольное текстовое обозначение для группы curl-запросов, которые нужно выполнить параллельно. Если при втором вызове метода multiQuery() значение этого параметра не указано, то по умолчанию будет использовано значение, которое было указано при первом вызове метода.

  • $options

    Массив параметров выполнения запросов через curl, которые должны применяться вместо значений, указанных в параметре $options при создании экземпляра класса, который используется для многократного вызова метода query() перед вторым вызовом метода multiQuery(). Значение параметра $options нужно указывать при первом вызове multiQuery().

Пример

waNet::multiQuery(
    'my_query',
    [
        'timeout' => 10,
    ]
);

$net = new waNet([
    'priority' => [
        'curl',
    ],
    // это значение не сработает, потому что оно переопределено при первом вызове multiQuery()
    'timeout' => 20,
]);

// эти запросы выполнятся одновременно — при втором вызове метода multiQuery()
// после их завершения будут по очереди выполнены обработчики, указанные в 4-м параметре при вызове метода query()
$response1 = $net->query($url1, $content1, waNet::METHOD_POST, ['myClass', 'some_callback_method']);
$response2 = $net->query($url2, $content2, waNet::METHOD_POST, ['myClass', 'another_callback_method']);
$response3 = $net->query($url3, $content3, waNet::METHOD_POST, ['myClass', 'extra_callback_method']);

// эти запросы выполнятся сразу же — не дожидаясь второго вызова multiQuery()
// потому что в 4-м параметре $callback не указан обработчик
$response4 = $net->query($url4, $content4, waNet::METHOD_POST);
$response5 = $net->query($url5, $content5, waNet::METHOD_POST);

waNet::multiQuery('my_query');

public function userAgent ($user_agent = null)

Устанавливает либо возвращает значение, которое будет использовано для заголовка "User-Agent".

Параметры

  • $user_agent

    Новое значение, которое нужно установить для заголовка "User-Agent". Если не указано, то метод только вернет текущее значение. По умолчанию используется значение вида "Webasyst-Framework/[номер версии Webasyst]".

Пример

$net = new waNet($options);
$net->userAgent($custom_user_agent);
$response = $net->query($url);