Source: wp-includes/class-wp-http-requests-hooks.php
Since: 4.7.0
Extends: WpOrgRequestsHooks

Purpose

Bridge between the Requests library’s internal hook system and WordPress’s action/filter system. Every outbound HTTP request made through WP_Http::request() gets an instance of this class as $options['hooks'] (set at class-wp-http.php ~line 345: 'hooks' => new WP_HTTP_Requests_Hooks( $url, $parsed_args )).

When Requests dispatches internal hooks (e.g., request.progress, curl.before_send), they flow through this class’s dispatch() method, which:

1. Calls the parent WpOrgRequestsHooks::dispatch() (fires any directly-registered callbacks)
2. Maps specific hooks to WordPress back-compat actions
3. Fires a generic WordPress action "requests-{$hook}" for every hook

Class Definition

#[AllowDynamicProperties]
class WP_HTTP_Requests_Hooks extends WpOrgRequestsHooks

Properties

Constructor

public function __construct( string $url, array $request )

Stores the URL and request args for later use in dispatch(). Does not call parent::__construct() — the parent class (WpOrgRequestsHooks) has no constructor logic (it initializes $hooks = [] as a property default).

Methods

dispatch( $hook, $parameters = array() )

Returns: bool — True if hooks were run, false if nothing was hooked.

Flow:

1. parent::dispatch( $hook, $parameters ) — Fires any callbacks registered directly on this Hooks instance via $hooks->register(). This is how request.progress callbacks work — they’re registered directly on the hooks object, NOT through WordPress’s add_action().

2. Back-compat switch — Currently handles one case:

   • 'curl.before_send': Fires the WordPress action 'http_api_curl' with args [ &$curl_handle, $this->request, $this->url ]. This is documented in class-wp-http-curl.php (the deprecated transport).

3. Generic WordPress action — Fires do_action_ref_array( "requests-{$hook}", $parameters, $this->request, $this->url ) for every hook. The action name uses hyphens (not underscores), with a phpcs ignore comment for WordPress.NamingConventions.ValidHookName.UseUnderscores.

parent::dispatch( $hook, $parameters ) — Fires any callbacks registered directly on this Hooks instance via $hooks->register(). This is how request.progress callbacks work — they’re registered directly on the hooks object, NOT through WordPress’s add_action().

Available Hooks Dispatched Through This Class

Back-compat switch — Currently handles one case:

Streaming Significance

Generic WordPress action — Fires do_action_ref_array( "requests-{$hook}", $parameters, $this->request, $this->url ) for every hook. The action name uses hyphens (not underscores), with a phpcs ignore comment for WordPress.NamingConventions.ValidHookName.UseUnderscores.

• 'curl.before_send': Fires the WordPress action 'http_api_curl' with args [ &$curl_handle, $this->request, $this->url ]. This is documented in class-wp-http-curl.php (the deprecated transport).

Direct Registration vs WordPress Actions

parent::dispatch( $hook, $parameters ) — Fires any callbacks registered directly on this Hooks instance via $hooks->register(). This is how request.progress callbacks work — they’re registered directly on the hooks object, NOT through WordPress’s add_action().

1. Direct registration (recommended for streaming):

   php

   // Register directly on the hooks object
   $hooks = new WP_HTTP_Requests_Hooks( $url, $args );
   $hooks->register( 'request.progress', $callback );
   // Pass as $options['hooks']
   

2. WordPress action (less useful):

   php

   add_action( 'requests-request.progress', function( $data, $bytes, $limit ) {
       // This fires for ALL requests — no URL filtering possible
       // Parameters are NOT passed by reference in the WordPress action
   }, 10, 3 );
   

Back-compat switch — Currently handles one case:

Why This Class Matters for Streaming Architecture

Generic WordPress action — Fires do_action_ref_array( "requests-{$hook}", $parameters, $this->request, $this->url ) for every hook. The action name uses hyphens (not underscores), with a phpcs ignore comment for WordPress.NamingConventions.ValidHookName.UseUnderscores.

@since 4.7.0