Skip to content

Latest commit

 

History

History
181 lines (101 loc) · 5.45 KB

hooks.md

File metadata and controls

181 lines (101 loc) · 5.45 KB
Raw

Hooking system

Requests has a hook system that you can use to manipulate parts of the request process along with internal transport hooks.

Check out the [API documentation for WpOrg\Requests\Hooks][requests_hooks] for more information on how to use the hook system.

[requests_hooks]: {{ '/api-2.x/classes/WpOrg-Requests-Hooks.html' | prepend: site.baseurl }}

Available Hooks

  • requests.before_request

    Alter the request before it is sent to the transport.

    Parameters: string &$url, array &$headers, array|null &$data, string &$type, array &$options

  • request.progress

    Run events based on how much body data has been received up to this point for the current request.

    Parameters: string $data, int $response_bytes, int|bool $response_byte_limit

  • requests.before_parse

    Alter the raw HTTP response before parsing.

    Parameters: string &$response, string $url, array $headers, array|null $data, string $type, array $options

  • requests.before_redirect_check

    Alter the response object before a potential redirect is detected and acted on.

    Parameters: WpOrg\Requests\Response &$return, array $req_headers, array $req_data, array $options

  • requests.before_redirect

    Alter the request arguments before a redirect is acted upon.

    Parameters: string &$location, array &$req_headers, array &$req_data, array &$options, WpOrg\Requests\Response $return

  • requests.after_request

    Alter the response object before it is returned to the user.

    Parameters: WpOrg\Requests\Response &$return, array &$req_headers, array &$req_data, array &$options

  • multiple.request.complete

    Alter the response for an individual request in a multi-request.

    Parameters: WpOrg\Requests\Response &$response, string|int $id

    Do not register this hook directly. To use this hook, pass a callback via $options['complete'] when calling WpOrg\Requests\Requests\request_multiple().

  • curl.before_request

    Set cURL options before the transport sets any (note that Requests may override these).

    Parameters: cURL resource|CurlHandle &$handle

  • curl.before_send

    Set cURL options just before the request is actually sent via curl_exec().

    Parameters: cURL resource|CurlHandle &$handle

  • curl.after_send

    Run events after sending the request, but before interpreting the response.

    Parameters: -

  • curl.after_request

    Alter the raw HTTP response before returning for parsing.

    Parameters: string &$headers, [array &$info]

    The optional $info parameter contains the associated array as defined in the return value for curl_getinfo().

This optional parameter will be present when a blocking request was made ($options['blocking' = true) and will not be present when a non-blocking request was made ($options['blocking' = false). The callback signature needs to be adapted accordingly.

  • curl.before_multi_add

    Set cURL options before adding the request to a cURL multi handle.

    Parameters: cURL resource|CurlHandle &$subhandle

  • curl.before_multi_exec

    Set cURL options before executing a cURL multi handle request.

    Parameters: cURL resource|CurlMultiHandle &$multihandle

  • curl.after_multi_exec

    Run events before a cURL multi handle is closed.

    Parameters: cURL resource|CurlMultiHandle &$multihandle

  • fsockopen.before_request

    Run events before the transport does anything.

  • fsockopen.remote_socket

    Alter the remote socket.

    Parameters: string &$remote_socket

  • fsockopen.remote_host_path

    Alter the remote host path.

    Parameters: string &$path, string $url

  • fsockopen.after_headers

    Add extra headers before the body begins (i.e. before \r\n\r\n).

    Parameters: string &$out

  • fsockopen.before_send

    Add body data before sending the request.

    Parameters: string &$out

  • fsockopen.after_send

    Run events after writing the data to the socket.

    Parameters: string $out

  • fsockopen.after_request

    Alter the raw HTTP response before returning for parsing.

    Parameters: string &$headers, [array &$info]

    The optional $info parameter contains the associated array as defined in the return value for stream_get_meta_data().

This optional parameter will be present when a blocking request was made ($options['blocking' = true) and will not be present when a non-blocking request was made ($options['blocking' = false). The callback signature needs to be adapted accordingly.

Registering Hooks

Note: if you're doing this in an authentication handler, see the Custom Authentication guide instead.

In order to register your own hooks, you need to instantiate WpOrg\Requests\Hooks and pass the object in via the 'hooks' option.

$hooks = new \WpOrg\Requests\Hooks();
$hooks->register('requests.after_request', 'mycallback');

$request = \WpOrg\Requests\Requests::get('https://httpbin.org/get', array(), array('hooks' => $hooks));

Previous: Requests through proxy

Next: Upgrading to Requests 2.0