Responses

Introduction

Controllers return data; the router serializes it. Response builds the envelope both transports share:

use YourPlugin\Deps\BitApps\WPKit\Http\Response;

return Response::success($tag);
return Response::error('Tag not found');

The envelope

Every response is JSON with the same shape:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Tag saved",
  "data": { "id": 12, "title": "Leads" }
}

status is always success or error. message and code appear only when set. data carries the payload.

Success and error

Response::success($data);              // status success, HTTP 200
Response::success($data, 201);         // custom HTTP status

Response::error('Failed to save tag'); // status error, HTTP 400
Response::error($errors, 422);

Both take a string or any serializable value as the payload, and both return the instance so you can keep chaining.

Shaping the envelope

return Response::success($flow)
    ->message('Flow saved')
    ->code('FLOW_SAVED')
    ->httpStatus(201)
    ->headers(['X-Flow-Id' => $flow->id]);

Method	Sets
message($message)	Human-readable message field
code($code)	Machine-readable code field for the client to branch on
httpStatus($code)	HTTP status. Defaults to 200 for success, 400 for error
headers($headers)	Response headers, as a name => value array. Validated — see below
header($name, $value)	A single header

Read the current values back with getData(), getStatus(), getMessage(), getCode(), getHttpStatusCode() and getHeaders().

Headers are validated

Since 2.4.0 headers() requires an array and runs every entry through header(). An invalid header name, a value containing CR, LF or NUL, or a non-scalar value throws InvalidArgumentException instead of being stored silently. The whole set is validated before any of it replaces the existing headers, so a bad entry leaves the previous headers intact.

Returning bare values

A controller may return anything. Values that are not a Response are wrapped automatically:

public function index()
{
    return Tag::get(['id', 'title', 'status']);
}

becomes

{ "status": "success", "code": "SUCCESS", "data": [ ... ] }

A WP_Error is unwrapped into an error response, mapping its code, message and data:

return new WP_Error('invalid_flow', 'Flow not found', ['id' => $id]);

{ "status": "error", "code": "invalid_flow", "message": "Flow not found", "data": { "id": 42 } }

Transport differences

The same envelope is delivered two ways:

Transport	Delivery
AJAX	Headers are sent, then wp_send_json() with the HTTP status
REST	A WP_REST_Response carrying the data, status and headers

note

Anything a controller echoes or prints before returning is captured and attached to the envelope as an additional field, rather than corrupting the JSON. Treat it as a debugging aid: stray output means a stray var_dump().

Changed in wp-kit 2.4.0

Response still stores its state statically, so one request builds one response. What changed is that success() and error() now start from fresh metadata — a message, code or header set on an earlier response no longer leaks into the next one.

getCode() also returns null rather than '' when neither a code nor a status has been set.