waNet

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

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

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

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

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

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

Методы

  • cookies

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

  • getResponse

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

  • getResponseHeader

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

  • query

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

  • 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 = array(), $method = self::METHOD_GET)

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

Выполнение метода может привести к возникновению исключения, поэтому его вызов необходимо обернуть в блок 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_DELETE — DELETE (для транспорта 'curl')

Пример

$net = new waNet($options);
$response = $net->query($url, $content, waNet::METHOD_POST);

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);