Response #

The response object is an abstraction of your Leaf application’s HTTP response that is returned to the HTTP client.

Using the Response object #

Leaf offers a couple of ways to use the response object in your application.

Response on the Leaf Instance #

Since Response is already bound to the Leaf instance, you can do this:

$app = new Leaf\App;

$app->get("/text", function () use($app) {
  $app->response()->markup("This is text");
});

app()->get('/text', function () {
  app()->response()->markup('This is text');
});

Although we've added this, we don't want to force you to do stuff in only one way, so you can still use the v1.x method.

$app = new Leaf\App;
$response = new Leaf\Http\Response;

$app->post('/login', function () use($response) {
  // ...
  $response->json(['username' => $user]);
});

response()->json([
  'status' => 'success',
  'data' => 'Hello',
]);

An HTTP response has three primary properties:

• Status
• Header
• Body

The response object provides helper methods, described next, that help you interact with these HTTP response properties.

Method Chaining #

Method chaining allows you to be more expressive with your code and basically fit everything better. There's just a single rule you need to follow here: the method you want to output should be the last thing you call.

If you want to output some JSON with a header something, you should always set the header before calling the JSON method.

// ☑️ CORRECT
$app->response()->withHeader('something', 'value')->json('data');

// ❌ HEADER ERROR
$app->response()->json('data')->withHeader('something', 'value');

// ☑️ CORRECT
response()->withHeader('something', 'value')->json('data');

// ❌ HEADER ERROR
response()->json('data')->withHeader('something', 'value');

Response Methods #

This section covers all methods provided in the response object which allow you to output some kind of data.

plain #

This method allows you to output plain text as your response. It takes in 2 parameters:

• the data to output
• http status code with 200 default (optional)

$app->response()->plain('hello');

response()->plain('hello');

xml #

This method allows you to output xml as your response. It takes in 2 parameters:

• the data to output
• http status code with 200 default (optional)

$app->response()->xml(
  '<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1.0.0" />'
);

response()->xml(
  '<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1.0.0" />'
);

json #

This method allows you output json as a response.

It takes in 3 parameters:

• The data to output
• The https status code of the data, default 200 (optional)
• Option to show/hide the status code in response body, default false (optional)

$app->response()->json('Output', 200);

response()->json('Output', 200);

Output:

"Output"

Showing the code in body:

$app->response()->json('Output', 200, true);

response()->json('Output', 200, true);

Output:

{
  "data": "Output",
  "status": {
    "code": 200,
    "message": "OK"
  }
}

page #

This is a method that outputs an HTML/PHP file. This method can also be used to achieve server side routing, for example:

$app->get('/homepage', function () use($app) {
  $app->response()->page('link/to/home.html');
});

app()->get('/homepage', function () {
  response()->page('link/to/home.html');
});

With this, whenever the route /homepage is invoked, Leaf loads up home.html and outputs it to the user.

Note The page method has NOTHING to do with templating, it simply outputs an already defined web page.

For templating with Leaf, look here

Status Code:

It takes in a status code as the second parameter.

$app->response()->page('404.html', 404);

response()->page('404.html', 404);

markup #

This method outputs some HTML/PHP:

$app->get('/homepage', function () use($app) {
  $app->response()->markup('<h2>Hello</h2>');
});

app()->get('/homepage', function () {
  response()->markup('<h2>Hello</h2>');
});

You might be wondering why we don't just use

echo '<h1>hello</h1>';

The reason is, Leaf has default headers which set the content type to JSON, in order to correctly output HTML, you need to change this.... Leaf has taken care of this with a bunch of other things, all within markup and page.

You can also specify a status code:

$app->response()->markup('<h2>Hello</h2>', 201);

response()->markup('<h2>Hello</h2>', 201);

download #

In v3, you can send a response which will be downloaded on the client. Note that in this case, the response should be a valid file.

// using defaults
$app->response()->download('path/to/file.zip');

// syntax
$app->response()->download('path/to/file.zip', 'File name on client', 200);

// using defaults
response()->download('path/to/file.zip');

// syntax
response()->download('path/to/file.zip', 'File name on client', 200);

As shown above, it takes in 3 parameters:

• the file to send as response
• The name of the file to show to client (optional, defaults to original filename)
• Http status code (optional, defaults to 200)

$app->response()->download('item.jpg', 'Profile Pic', 200);

// to skip setting a name
$app->response()->download('item.jpg', null, 201);

// PHP 8
$app->response()->download(
  file: 'item.jpg',
  code: 201
);

response()->download('item.jpg', 'Profile Pic', 200);

// to skip setting a name
response()->download('item.jpg', null, 201);

// PHP 8
response()->download(
  file: 'item.jpg',
  code: 201
);

noContent #

The HTTP 204 No Content success status response code indicates that a request has succeeded, but that the client doesn't need to navigate away from its current page. This method allows you to quickly create a 204 response.

$app->response()->noContent();

response()->noContent();

redirect #

This feature just simply allows you to send a redirect response which redirects to a different route.

$userHasAuth = true;

if ($userHasAuth) {
  return $app->response()->redirect('/home');
}

$userHasAuth = true;

if ($userHasAuth) {
  return response()->redirect('/home');
}

You can also specify a status code:

$app->response()->redirect('/home', 307);

response()->redirect('/home', 307);

exit #

This is a new method which allows you to output some data and close your app right after. This means that it acts as a sort of early-return for your app, so right after outputting some data, it quits and makes sure that no other code is executed from your app until the next request comes through.

It takes in 2 parameters: the data to output and the http status code (default: 500).

$app->response()->exit('This will be output as markup');

// code below won't run

response()->exit('This will be output as markup');

// code below won't run

You can also output JSON.

$app->response()->exit(['data' => 'This will be output as JSON'], 500);

response()->exit(['data' => 'This will be output as JSON'], 500);

Headers #

Headers are a way for your server to send additional information along with your request. This information can be anything from the type of content you're sending back, to the status code of your response, to the type of server you're using.

Leaf allows you to set headers for your response directly from the response object using the withHeader() method. It takes in 4 parameters:

• The header name or an array of headers (key-value pairs)
• The header value if header key is a string
• A boolean on whether to replace the header if it's already set
• An Http status code to associate to header.

$app
  ->response()
  ->withHeader('something', 'something')
  ->withHeader('somethingAgain', 'something', true, 200)
  ->withHeader(['somethingElse' => 'another']);

response()
  ->withHeader('something', 'something')
  ->withHeader('somethingAgain', 'something', true, 200)
  ->withHeader(['somethingElse' => 'another']);

Cookies #

Cookies are small pieces of data that are stored on the client's computer by the web browser while browsing a website. Cookies were designed to be a reliable mechanism for websites to remember stateful information or to record the user's browsing activity.

Leaf allows you to set cookies for your response using the withCookie() method. It takes in 3 parameters:

• The name of the cookie
• The value of cookie
• When the cookie expires. Default: 7 days

$app->response()->withCookie("name", "Michael", "1 day")->json('...');

response()
  ->withCookie("name", "Michael", "1 day")
  ->json('...');

withoutCookie() #

This method allows you to remove existing cookies from your response. So you're basically returning a response without selected cookies.

$app->response()->withoutCookie("name")->json('...');

// cookie array
$app->response()->withoutCookie(["name", "something"])->json('...');

response()->withoutCookie("name")->json('...');

// cookie array
response()->withoutCookie(["name", "something"])->json('...');

Flash messaging #

Flash messages are a way to keep a message around for a single request. They're helpful for displaying status messages like "Item deleted successfully" or "Your changes have been saved."

Leaf allows you to set flash messages for your response using the withFlash() method. It takes in 2 parameters:

• The name of the flash message
• The value of the flash message

$app->response()->withFlash('message', 'something')->redirect('/somewhere');

response()->withFlash('message', 'something')->redirect('/somewhere');

Status #

The HTTP response returned to the client will have a status code indicating the response’s type (e.g. 200 OK, 400 Bad Request, or 500 Server Error). You can use the Leaf application’s response object to set the HTTP response’s status like this:

$app->response()->status(400)->json(['message' => 'home']);

response()->status(400)->json(['message' => 'home']);

Or with a native PHP response:

$app->response()->status(400);

echo 'This is the main output';

response()->status(400);

echo 'This is the main output';

You only need to set the response object’s status if you intend to return an HTTP response that does not have a 200 OK status.