HTTP Responses

Introduction

All routes and controllers must return a response to send back to the user. Bow provides several different ways to return responses.

The most basic response is returning a string from a route or controller. Bow will automatically convert the string into a full HTTP response.

Sending a response

A string

An HTTP response can be a string.

$app->get('/', function () {
  return "Hello, world";
});

A collection, an array, or an object

An HTTP response can be an instance of Bow\Support\Collection.

$app->get('/array', function () {
  return [10, 2, 12, 'name' => 'Dakia'];
});

$app->get('/collection', function () {
  return collect([10, 2, 12]);
});

$app->get('/object', function () {
  return (object) ['name' => 'Dakia'];
});

A BARRY model

The HTTP response can be a Model or a Collection of models. Bow converts them directly to JSON.

use App\Models\User;

$app->get('/', function () {
  $model = User::where('id', 1)->first();
  
  return $model;
});

Modifying the response

Modifying the status code

HTTP status code

It is very important to add the appropriate status codes to your HTTP response if you are developing a REST API. The status method lets you do this.

use App\Models\User;

$app->get('/', function () {
  $response = response();
  
  return $response->status(400);
});

For more information about HTTP codes, check out this link.

Tip: 204 vs 200

If, in your API, the request was processed successfully and you have no information to return, it is preferable to return a 204 rather than a 200.

Adding an HTTP header

You will often need to add other HTTP headers to your HTTP response. The withHeader and withHeaders methods let you do this.

$response->withHeader('Content-Type', 'application/json');

You can add several headers at once:

$response->withHeaders([
  'Content-Type' => 'application/json',
  'X-Proto-Value' => 1
]);

Sending JSON

In REST applications (REST/RESTful APIs), information is generally returned as JSON. To send JSON information to the client, you can use the json helper or the json method on the Bow\Http\Response instance.

Prototype of the json method

json(mixed $data, int $code = 200, array $headers = []): string

Parameter	Type	Description
$data	mixed (array, stdClass, Iterable, JsonSerializable...)	The data to serialize
$code	int	The HTTP status code (default 200)
$headers	array	The headers to add to the response

Example of sending JSON

Example:

$data = ['message' => 'Hello, World'];

return $response->json($data, $code = 200, [
  'X-Proto-Value' => 1 // Just a test
]);

With the response_json HELPER:

$data = ['message' => 'Hello, World'];

return response_json($data, 200, [
  'X-Proto-Value' => 1 // Just a test
]);

Header automation

Bow automatically adds the Content-Type HTTP header set to application/json, so there is no longer any need to add it manually in $headers.

Sending a response from views

You can often use a Bow\Http\Response instance to render a view via the render method.

Prototype of the render method

render(string $template, array $data = [], int $code = 200, array $headers = []): string

Parameter	Type	Description
$template	string	The name of the view to render
$data	array	The data to send to the view
$code	int	The HTTP status code (default 200)
$headers	array	The headers to add to the response

Example of sending a view

Example:

$users = User::where('id', '!=', 2)->get();

return $response->render('users', ['users' => $users], 200, [
  'X-Proto-Value' => 1 // Just a test
]);

Downloading a file

You will often need to set up systems for downloading zip files or images. You will also build applications where users must authenticate before downloading files (Dropbox-style). Bow provides a simple API via the Bow\Http\Response class to download a file with the download method.

Prototype of the download method

download(string $file, ?string $filename = null, array $headers = []): string

Parameter	Type	Description
$file	string	The absolute path of the file
$filename	?string	The name suggested for the download (defaults to the basename of the file)
$headers	array	Additional headers to add to the response

Content-Disposition

To display the file inline in the browser instead of downloading it, pass the special 'disposition' key in $headers:

return $response->download($file, 'image.png', [
  'disposition' => 'inline',   // or 'attachment' (default)
]);

More information about the Content-Disposition header.

Download example

$file = '/path/to/file.png';

return $response->download($file, 'image.png');

You can also use the response_download($file, $filename, $headers) helper.

Redirection

You will certainly need to perform redirections to other resources, and this is in fact an HTTP response. The to and back methods (which, as its name suggests, allows you to go back) of the Bow\Http\Redirect class.

Redirection with to

Redirection with to lets you send the user to another page.

return redirect()->to($path);

Prototype of to

Parameter	Type	Description
$path	String	The redirection URL

return redirect()->to('/users');

Redirection with back

Redirection with back lets you send the user back to the previous page.

return redirect()->back($status_code);

Prototype of back

Parameter	Type	Description
$status_code	Int	The HTTP code of the response (defaults to 302)

return redirect()->back();

Redirection with information

You can also perform the redirection together with the information sent by the user, using the withInput and withFlash methods like this:

 return redirect()->back()->withInput();
 // Or
 return redirect()->to("/home")->withInput();

With a flash message

 return redirect()->back()->withFlash('success', 'Papac');

Note that you can pass an array of values to withInput, which will be a collection of information to send to the user.

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.