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
andgetResponseHeader
.
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), 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 = [], $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
: GETwaNet::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:
- Call the method with an arbitrary non-empty value of the $namespace parameter. This is required for data initialization.
- Make several calls of the query() method with a
callable
type value passed to the $callback parameter. - 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 acallable
type value passed as the $callback parameter for thequery()
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 thequery()
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 thequery()
method before the second call ofmultiQuery()
. 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);