Класс предназначен для удобного выполнения запросов — с помощью расширения curl, а также функций file_get_contents
и fsockopen
. Класс автоматически использует тот из доступных методов (транспортов) отправки запросов — расширение либо одну из перечисленных функций, — который доступен на сервере, выполняет проверку на наличие ошибок при получении ответа, а также возвращает содержимое ответа, раскодированное в соответствии с указанным форматом.
Если вы считаете, что классу не хватает какой-либо объективно необходимой функциональности, оформляйте свои предложения в виде pull request в GitHub-репозитории фреймворка.
Порядок использования класса:
- Создать экземпляр класса, передав в него массив необходимых параметров.
- Если необходимо, вызвать «подготовительные» методы:
cookies
иuserAgent
. - Для выполнения запроса вызвать метод
query
, который вернет содержимое ответа. - Если необходимо, вызвать методы, возвращающие дополнительную информацию об ответе на запрос:
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
- format: формат ожидаемого ответа:
-
$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
— GETwaNet::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);