waNet

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:

1. Create a class instance by passing an array of initializing parameters to the constructor.
2. If necessary, call "preparation" methods: cookies and userAgent.
3. To actually send a request, call method query, which will return the response contents.
4. 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), or waNet::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 and base64_encode, in the Content-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 parameter CURLOPT_SSLKEY
    • 'cert': value for parameter CURLOPT_SSLCERT
    • 'password': value for parameter CURLOPT_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 is waNet.error.log
• $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: GET
  • waNet::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);