waNet

Sending network requests

Contents...

This class is useful for convenient sending of network requests using the curl extension, and via file_get_contents and fsockopen functions. This class automatically uses the first of the sending methods (transports) available on the server, verifies the received response, and returns its contents, decoded to the specified format.

How to use:

  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 and 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.

  • multiQuery

    Runs several curl requests in parallel with subsequent execution of callback functions.

  • 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 = [], $method = self::METHOD_GET, $callback = null)

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_PATCH: PATCH (for transports 'curl' and 'fopen')
    • waNet::METHOD_DELETE: DELETE (for 'curl' transport)
  • $callback

    Value of the callable type, which must be called upon the request completion. Supported only for requests sent by the curl transport.

Example

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

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

Runs several curl requests in parallel with subsequent execution of callback functions. This allows your product to save the time required to make several simultaneous requests.

This method does not work with other transports except for curl.

How to use this method:

  1. Call the method with an arbitrary non-empty value of the $namespace parameter. This is required for data initialization.
  2. Make several calls of the query() method with a callable type value passed to the $callback parameter.
  3. Once again call the multiQuery() method with the same value of the $namespace parameter. This will simultaneously run all curl requests initialized in step 2, which have a callable type value passed as the $callback parameter for the query() method. If no correct value was passed as the $callback parameter then curl requests are performed sequentially rather than in parallel — immediately upon each call of the query() in the previous step 2, without waiting for this step 3.

Parameters

  • $namespace

    An arbitrary text name for a group of curl requests that must be run in parallel. If no value is specified during the second call of the multiQuery() method then the value passed during its first call is used by default.

  • $options

    Array of parameters used for curl requests which must be applied instead of those specified in the $options parameter when a class instance is created for multiple calls of the query() method before the second call of multiQuery(). A value of the $options parameter, if necessary, must be passed during the first call of this method.

Example

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

$net = new waNet([
    'priority' => [
        'curl',
    ],
    // this value will not be used because it is has been overridden during the 1st call of multiQuery()
    'timeout' => 20,
]);

// these requests will be executed simultaneously, during the 2nd call of multiQuery()
// upon their completion, callback functions passed as the 4th parameter for query() method calls will be executed
$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']);

// these requests will be executed sequentially at once, without waiting for the 2nd call of multiQuery()
// because no callbacks are passed for the 4th $callback parameter
$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)

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