This class is useful for convenient sending of network requests using curl
extension, and via file_get_contents
and fsockopen
functions. The class automatically uses the first of the sending methods (transports) available on the server, verifies the received response, and returns its contents, unpacked to the required format, if necessary.
How to use waNet
class:
- Create a class instance by passing an array of initializing parameters to the constructor.
- If necessary, call "preparation" methods:
cookies
anduserAgent
. - To actually send a request, call method
query
, which will return the response contents. - If necessary, additionally call other methods returning more information about the received response:
getResponse
иgetResponseHeader
.
Methods
-
cookies
Sets the default path to a cookies file.
-
getResponse
Returns the contents of the last received response.
-
getResponseHeader
Returns the contents of the last received response headers.
-
query
Sends a request to specified URI.
-
userAgent
Sets a new or returns the current value of the "
User-Agent
" header.
public function __construct ($options)
Parameters
-
$options
Array of parameters used for connecting to a remote resource. Accepted array keys:
- format: format of the expected response:
waNet::FORMAT_JSON
(JSON),waNet::FORMAT_XML
(XML), orwaNet::FORMAT_RAW
(simple response contents requiring no additional formatting) - charset: the charset used in the request to be sent; defaults to
'utf-8'
- authorization: flag requiring authorization using
Authorization
header - login: user name for authorization
- password: password for authorization
- md5: flag requiring to specify the request contents, encoded with PHP functions
md5
andbase64_encode
, in theContent-MD5
header - priority: array of explicitly specified request sending methods (transports) and their detection order, which must be used, in the specified order, to select the first transport available on the server only from the specified list; if not specified, the following transport list and their priority is used by default:
'curl'
(curl
extension)'fopen'
(file_get_contents()
function)'socket'
(fsockopen()
function)
- timeout: timeout in seconds during which it is allowed to continue the sending of a request
- verify: path to a certificate file for request authentication (supported by transports
'curl'
and'fopen'
) - ssl:array of parameters used for connections via
'curl'
using an SSL certificate:'key'
: value for parameterCURLOPT_SSLKEY
'cert'
: value for parameterCURLOPT_SSLCERT
'password'
: value for parameterCURLOPT_SSLCERTPASSWD
- proxy_host: proxy host for sending requests via
'curl'
or'fopen'
transports - proxy_port: proxy port
- proxy_user: user name for proxy authorization
- proxy_password: password for proxy authorization
- log: alternative path error log file in
wa-log/
directory; default path iswaNet.error.log
- format: format of the expected response:
-
$custom_headers
Associative array of custom headers to be used for sending a request to a remote resource.
Example
$options = array( 'format' => waNet::FORMAT_JSON 'timeout' => 10, 'authorization' => true, 'login' => $login, 'password' => $password, ); $net = new waNet($options);
public function cookies ($path)
Sets the path to a file with cookies
values for using as the CURLOPT_COOKIEFILE
parameter value when connecting via curl
. This default value is used, only if no other path to a cookies
file is explicitly specified in curl
connection parameters.
Parameters
-
$path
Path to a cookies file.
Example
$net = new waNet($options); $net->cookies($path);
public function getResponse ($raw = false)
Returns the contents of the last received response.
Parameters
-
$raw
Flag requiring to return either raw (original) or formatted response contents. By default, formatted response contents are returned. The format used for response formatting must be the same as the value of the
'format'
parameter passed to the class constructor.
Example
$options['format'] = waNet::FORMAT_JSON; $net = new waNet($options); $decoded_response = $net->query($url); $raw_response = $net->getResponse(true);
public function getResponseHeader ($header = null)
Returns the contents of the last received response headers.
Parameters
-
$header
name of header whose contents must be returned. If not specified, all received headers' contents are returned.
Example
$net = new waNet($options); $response = $net->query($url); $response_headers = $net->getResponseHeader();
public function query ($url, $content = array(), $method = self::METHOD_GET)
Sends a request to a remote resource and returns response contents formatted according to the specified format name.
Execution of this method may cause an exception; therefore, it must be used inside a try...catch
block for correct error handling. Error codes in this case correspond to common HTTP server response codes.
Parameters
-
$url
Request URL
-
$content
Request contents
-
$method
Sending method:
waNet::METHOD_GET
: GETwaNet::METHOD_POST
: POST (for transports'curl'
and'fopen'
)waNet::METHOD_PUT
: PUT (for transports'curl'
and'fopen'
)waNet::METHOD_DELETE
: DELETE (for'curl'
transport)
Example
$net = new waNet($options); $response = $net->query($url, $content, waNet::METHOD_POST);
public function userAgent ($user_agent = null)
Sets a new or returns the current value of the "User-Agent
" header.
Parameters
-
$user_agent
New value to be set for "
User-Agent
" header. If not specified, method returns current header value. If not explicitly changed, default header value is"Webasyst-Framework/[Webasyst version]"
.
Example
$net = new waNet($options); $net->userAgent($custom_user_agent); $response = $net->query($url);