Responses

Since Monarch is designed around returning either HTML or JSON responses, it's important to understand how responses are generated and what you can do with them.

HTML Responses

HTML responses are automatically generated by rendering the appropriate route file. The resulting HTML is added to the Monarch\HTTP\Response object and sent to the client. It is not sent immediately to allow for additional headers to be added, or any modifications that middleware might make. This helps avoid headers already sent errors.

The response object is a singleton, so you can access it from anywhere in your application.

$response = \Monarch\HTTP\Response::instance();

Or you can you use the response() helper function. This is functionally the same as the above code, and returns the singleton instance of the response object.

$response = response();

Setting the response body

If you need to manually set the response body, you can do so by calling the withBody method on the response object. This is most frequently used within the middleware.

\Monarch\HTTP\Response::instance()->withBody('Hello, World!');

Getting the response body

You can retrieve the body of the response by calling the body method.

$body = \Monarch\HTTP\Response::instance()->body();

Headers

Headers can be added to the response by calling the withHeader method on the response object. This method takes a Monarch\HTTP\Header object as its only argument.

use Monarch\HTTP\Header;

response()->withHeader(new Header('Content-Type', 'text/html'));

If you add the same header multiple times you will get multiple headers with the same name. If you want to replace a header with the same name, you can use the replaceHeader method.

use Monarch\HTTP\Header;

response()->replaceHeader(new Header('Content-Type', 'text/html'));

It will located the header with the same name and replace it with the new header.

Forgetting Headers

If you need to remove a header from the response, you can use the forgetHeader method. It takes the header name as the only argument. If multiple headers with the same name exist, they will all be removed.

response()->forgetHeader('Content-Type');

Getting Headers

You can retrieve all headers by calling the headers method. This will return an array of Monarch\HTTP\Header objects.

$headers = response()->headers();

Cookies

Cookies can be added to the response by calling the withCookie method on the response object. This method takes a Monarch\HTTP\Cookie object as its only argument.

use Monarch\HTTP\Cookie;

response()->withCookie(new Cookie(
    name: 'name',
    value: 'value',
    expires: time() + 3600,
    path: '/',
    domain: 'example.com',
    secure: true,
    httpOnly: true
));

If you add the same cookie multiple times it will overwrite the previous cookie with the same name.

Forgetting Cookies

If you need to remove a cookie from the response, you can use the forgetCookie method. It takes the cookie name as the only argument.

response()->forgetCookie('name');

Out of Bound Swaps

Out of Bound swaps are an HTMX feature that allows you to "piggyback" one or more additional responses on the main response. This is useful for updating multiple parts of the page with a single response.

For example, if you had a div in the HTML already on the client's browser, it must have an id attribute.

<div id="alerts"></div>

In your response, you might need to send back an alert message to display in the div. You can do this by adding an hx-swap-oob attribute to the div in your response. This element must also have a matching id attribute to the div on the client.

<div id="alerts" hx-swap-oob="true">
    <p>Alert message here</p>
</div>

While you can handle that yourself within the route or control file, the Request object allows you to add out of bound swaps to the response from anywhere in your application. This could be useful for adding alerts or notifications from custom code or middleware.

You can add an out of bound swap to the response by calling the withSwap method on the response object. This method takes the id of the element to swap and the value to swap it with.

Note

The value must be a string of HTML.

Info

While not necessary, the id typically matches the id of the element on the client. It is only used as a reference to be able to remove the swap if needed.

use Monarch\HTTP\OOBSwap;

$alerts =<<<HTML
<div id="alerts" hx-swap-oob="true">
    <p>Alert message here</p>
</div>
HTML;

response()->withSwap(
    id: 'alerts',
    value: $alerts,
);

The swaps are stored in the response object and are sent to the client when the response is sent. If a closing </body> tag is found in the response body, the swaps are inserted before it. If not, they are appended to the end of the response body.

Forgetting Swaps

If you need to remove a swap from the response, you can use the forgetSwap method. It takes the id of the swap as the only argument.

response()->forgetSwap('alerts');