Responses

1. # Getting Started
2. # Response Instance
3. # Make Response
4. # Set Message
5. # Success
6. # Error
7. # Warning
8. # Set Message Type
9. # Getters
10. # Flash Next
11. # Flash Now
12. # Set Flash
13. # Exit Any
14. # Exit JSON
15. # Exit Message
16. # Exit Not Found
17. # Exit Server Error
18. # Abort
19. # With Old Fields
20. # Errors
21. # Get Return
22. # Set Status
23. # Bad
24. # Unauthorized
25. # Forbidden
26. # Set Header
27. # Set Content-Type Header
28. # Sends
29. # Get Headers
30. # Set TypeRocket Redirect
31. # With Redirect Message
32. # With Redirect Errors
33. # With Redirect Data
34. # Disable Page Cache

#Getting Started

The TypeRocket response system can be used to manage the server's response to client-side requests. The response system should be used within the context of a controller or middleware for the best results.

If you use the response system outside of a controller, keep in mind some methods like abort() will need to be handled by your own try/catch statements.

Also, when dealing with responses, you may want to set a status code. https://httpstatuses.com/ is an excellent resource for the different status code numbers.

#Response Instance

The Response object has several methods for working with the HTTP response.

You can use the tr_response() method to access the application's primary response instance.

$response = tr_response();

#Make Response

In some rare cases, you may want to create your response instance.

$response = new \TypeRocket\Http\Response();

#Set Message

To set the REST API response message use the setMessage() method. The message is also used if the response object is the return value of a controller.

$response->setMessage('Hello world!');

The response will look like this is the REST API is used, or you return the response as the value from a controller.

{
"message": "Hello world!",
"messageType": "success",
"redirect": false,
"status": null,
"flash": true,
"blockFlash": false,
"errors": [],
"data": []
}

You can also set the message type at the same time. There are three valid message types: success, error, and warning.

$response->setMessage('Message', 'success');
$response->setMessage('Message', 'error');
$response->setMessage('Message', 'warning');

The request types will set the color of the alert in the WordPress admin is the REST API is used.

Also, there are three shorthand methods for setting the message type. These shortcuts also allow you to optionally set the status code.

#Success

$response->success('Message', 201);

#Error

$response->error('Message', 422);

#Warning

$response->warning('Message', 200);

#Set Message Type

You can also set the message type manually. When setting the message type this way, the error code will be set to match message type if it has not been set already; thus, setting the type to error will default the status code to 422.

$response->setMessageType('error');

#Getters

You can get the message type and message as follows.

$message = $response->getMessage();
$type = $response->getMessageType();

#Flash Next

To flash a message on the next request in the admin, use the flashNext() method. This is useful when a controller or page redirects.

$response->flashNext('Message');

#Flash Now

To flash a message on the current request in the admin, use the flashNow() method.

$response->flashNow('Message');

#Set Flash

Set if the flash message should be shown on the front end.

$response->setFlash(true);

#Exit Any

To exit right away on any request, REST API or normal request, use the exitAny() method.

$response->exitAny( 404 );

#Exit JSON

To exit right away during a JSON API request, use the exitAny() method.

$response->exitJson( 500 );

#Exit Message

To exit right away during a normal request, use the exitMessage() method.

$response->exitMessage( 500 );

#Exit Not Found

To exit with 404.

$response->exitNotFound();

#Exit Server Error

To exit with a server error.

$response->exitServerError();

#Abort

Unlike the exit methods of the response class, the abort() method throws an exception. When the exception is caught by the kernel, a response is automatically generated.

The abort response can be either a WordPress template 404 or any other error code template. Or, the response will send a JSON string is the requester wants JSON.

$response->abort(500);

If the error code sent is not a valid HTTP status code and error screen will be displayed instead.

Using abort allows you to provide WordPress templates beyond 404.php. This means you can have a 500.php error code in your theme as well if an abort is used.

#With Old Fields

To respond with fields, use the withOldFields() method.

$response->withOldFields( ['field_name' => 'The field value'] );

#Errors

$response->setErrors(['my_key' => 'My value.']);
$response->setError('my_key', 'My value.');
$response->hasErrors();
$response->getErrors();

#Get Return

This returns a reference to the return value from your controller.

$response->getReturn();

#Set Status

To set the status code pass any value HTTP status code into the setStatus() method.

$response->setStatus(404);

There are also quick status setters for specific statuses: bad, unauthorized, forbidden. Also, these methods set the response message making it easy to provide a JSON response.

#Bad

Sets the status code to 400.

$response->bad($message);

#Unauthorized

Sets the status code to 401.

$response->unauthorized($message);

#Forbidden

Sets the status code to 403.

$response->forbidden($message);

#Set Header

Set any header.

$response->setHeader('Content-type', 'application/json');

#Set Content-Type Header

$response->send('json');
// Sets: Content-type: application/json

Shorthand options include:

• json
• json-ld
• xml
• html
• t-xml
• plain

#Sends

$bool = $response->sends('json');

Shorthand options include:

• json
• json-ld
• xml
• html
• t-xml
• plain
• image

#Get Headers

$response->getHeaders();

#Set TypeRocket Redirect

This method only applies to specific TypeRocket AJAX REST API requests.

$response->setRedirect( home_url() );

Also, you can use the canRedirect() method to set the redirect URL of the response JSON body to the URL of a redirect object. This happens if that redirect object is the return value of a controller. For example:

tr_response()->canRedirect();
return tr_redirect()->toUrl(home_url());  

#With Redirect Message

Send a request with a redirect message transient.

$response->withRedirectMessage();

You can then access the message using tr_redirect_message().

#With Redirect Errors

Send a request with redirect errors transient.

$response->withRedirectErrors();

You can then access the errors using tr_redirect_errors().

#With Redirect Data

Send a request with a redirect data transient.

$response->withRedirectData();

You can then access the data using tr_redirect_data().

#Disable Page Cache

$response->disablePageCache();