WP_HTTP_Response Class

Last updated: March 4, 2026

Core class used to prepare HTTP responses.

File: wp-includes/class-wp-http-response.php
Since: 4.4.0

Overview

WP_HTTP_Response is a simple container class for HTTP response data. It’s primarily used in the REST API for building responses before they’re sent to the client. This is distinct from the response arrays returned by wp_remote_*() functions.

Class Definition

php
#[AllowDynamicProperties]
class WP_HTTP_Response {
    public $data;
    public $headers;
    public $status;
}

Properties

PropertyTypeDescription
$datamixedResponse data (body content)
$headersarrayHTTP headers as key-value pairs
$statusintHTTP status code

Constructor

php
public function __construct( mixed $data = null, int $status = 200, array $headers = array() )

Parameters:

ParameterTypeDefaultDescription
$datamixednullResponse body data
$statusint200HTTP status code
$headersarray[]HTTP headers

Example:

php
// Basic response
$response = new WP_HTTP_Response( 'Hello World' );

// With status code
$response = new WP_HTTP_Response( null, 204 );

// With headers
$response = new WP_HTTP_Response( 
    [ 'message' => 'Created' ], 
    201, 
    [ 'Location' => '/resource/123' ]
);

Methods

get_headers()

Retrieves headers associated with the response.

php
public function get_headers(): array

Example:

php
$response = new WP_HTTP_Response( $data, 200, [
    'Content-Type'  => 'application/json',
    'Cache-Control' => 'max-age=3600',
] );

$headers = $response->get_headers();
// [ 'Content-Type' => 'application/json', 'Cache-Control' => 'max-age=3600' ]

set_headers()

Sets all header values (replaces existing).

php
public function set_headers( array $headers ): void

Example:

php
$response->set_headers( [
    'Content-Type'     => 'text/html',
    'X-Custom-Header'  => 'value',
] );

Sets a single HTTP header.

php
public function header( string $key, string $value, bool $replace = true ): void

Parameters:

ParameterTypeDefaultDescription
$keystring–Header name
$valuestring–Header value
$replacebooltrueReplace existing header of same name

Example:

php
$response = new WP_HTTP_Response();

// Set header (replaces if exists)
$response->header( 'Content-Type', 'application/json' );

// Append to existing header
$response->header( 'Vary', 'Accept', false );
$response->header( 'Vary', 'Accept-Encoding', false );
// Result: 'Vary: Accept, Accept-Encoding'

get_status()

Retrieves the HTTP status code.

php
public function get_status(): int

Example:

php
$response = new WP_HTTP_Response( $data, 404 );
echo $response->get_status();  // 404

set_status()

Sets the HTTP status code.

php
public function set_status( int $code ): void

Example:

php
$response = new WP_HTTP_Response();
$response->set_status( 201 );

get_data()

Retrieves the response data.

php
public function get_data(): mixed

Example:

php
$response = new WP_HTTP_Response( [ 'id' => 123, 'name' => 'Test' ] );
$data = $response->get_data();
// [ 'id' => 123, 'name' => 'Test' ]

set_data()

Sets the response data.

php
public function set_data( mixed $data ): void

Example:

php
$response = new WP_HTTP_Response();
$response->set_data( [
    'success' => true,
    'items'   => [ 1, 2, 3 ],
] );

jsonSerialize()

Retrieves response data for JSON serialization.

php
public function jsonSerialize(): mixed

By default, returns the same as get_data(). Override in subclasses for custom JSON handling.

Example:

php
$response = new WP_HTTP_Response( [ 'key' => 'value' ] );
echo json_encode( $response );  // '{"key":"value"}'

Usage Examples

Basic REST API Response

php
function my_rest_endpoint( WP_REST_Request $request ) {
    $data = get_some_data();
    
    return new WP_HTTP_Response( $data, 200, [
        'X-Custom-Header' => 'value',
    ] );
}

Building Response with Fluent Interface

php
function create_resource( $data ) {
    $response = new WP_HTTP_Response();
    
    $response->set_status( 201 );
    $response->set_data( [ 'id' => 123, 'created' => true ] );
    $response->header( 'Location', '/resource/123' );
    $response->header( 'Content-Type', 'application/json' );
    
    return $response;
}

Error Response

php
function handle_error( $error_code, $message ) {
    return new WP_HTTP_Response( 
        [
            'code'    => $error_code,
            'message' => $message,
        ], 
        400,
        [ 'Content-Type' => 'application/json' ]
    );
}

Conditional Response

php
function get_resource( $id ) {
    $resource = find_resource( $id );
    
    if ( ! $resource ) {
        return new WP_HTTP_Response( 
            [ 'error' => 'Not found' ], 
            404 
        );
    }
    
    return new WP_HTTP_Response( $resource, 200 );
}

Caching Headers

php
function cacheable_response( $data ) {
    $response = new WP_HTTP_Response( $data );
    
    $response->header( 'Cache-Control', 'public, max-age=3600' );
    $response->header( 'ETag', md5( serialize( $data ) ) );
    $response->header( 'Last-Modified', gmdate( 'D, d M Y H:i:s' ) . ' GMT' );
    
    return $response;
}

Streaming Response

php
function download_file( $file_path ) {
    $response = new WP_HTTP_Response();
    
    $response->set_data( file_get_contents( $file_path ) );
    $response->set_status( 200 );
    $response->header( 'Content-Type', 'application/octet-stream' );
    $response->header( 'Content-Disposition', 'attachment; filename="' . basename( $file_path ) . '"' );
    $response->header( 'Content-Length', filesize( $file_path ) );
    
    return $response;
}

Extending the Class

php
class My_JSON_Response extends WP_HTTP_Response {
    public function __construct( $data = null, $status = 200 ) {
        parent::__construct( $data, $status, [
            'Content-Type' => 'application/json; charset=utf-8',
        ] );
    }
    
    public function jsonSerialize() {
        return [
            'success' => $this->status >= 200 && $this->status < 300,
            'data'    => $this->data,
        ];
    }
}

// Usage
$response = new My_JSON_Response( [ 'id' => 123 ], 200 );
echo json_encode( $response );
// '{"success":true,"data":{"id":123}}'

Relationship to Other Classes

WP_HTTP_Requests_Response

WP_HTTP_Requests_Response extends WP_HTTP_Response and wraps the Requests library’s response object. It’s used internally by WP_Http::request().

WP_HTTP_Response (base class)
    └── WP_HTTP_Requests_Response (wraps RequestsResponse)

WP_REST_Response

In the REST API, WP_REST_Response extends WP_HTTP_Response with additional features:

WP_HTTP_Response
    └── WP_REST_Response (adds links, matched_route, etc.)

Common Status Codes

CodeMeaningUse Case
200OKSuccessful GET, PUT, PATCH
201CreatedSuccessful POST that creates resource
204No ContentSuccessful DELETE
301Moved PermanentlyPermanent redirect
302FoundTemporary redirect
304Not ModifiedCache validation (If-None-Match)
400Bad RequestInvalid input
401UnauthorizedAuthentication required
403ForbiddenPermission denied
404Not FoundResource doesn’t exist
405Method Not AllowedWrong HTTP method
409ConflictResource conflict
422Unprocessable EntityValidation error
429Too Many RequestsRate limited
500Internal Server ErrorServer error
503Service UnavailableMaintenance/overload

More in Http

WP_Http Class

Core class used for managing HTTP transports and making HTTP requests. File: wp-includes/class-wp-http.php Since: 2.7.0…

WordPress HTTP API Functions

Request Functions wp_remote_request() Performs an HTTP request and returns its response. wp_remote_request( string $url, array…

WordPress HTTP API Hooks

This document covers all filters and actions available in the WordPress HTTP API. Request Filters…

All WordPress Core Docs View all Http
View on GitHub