HTTP Responses

Introduction

Every route and controller must return a response to be sent back to the user. Bow provides several different ways to return responses.

The most basic response is returning a string from a route or a 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 building a REST API. The status method lets you do that.

use App\Models\User;

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

For more information on HTTP codes, see this link.

Tip: 204 vs 200

If, in your API, the request was processed successfully and you have no information to return, it is better 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 that.

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

You can add several headers at the same time:

$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
]);

Automatic header

Bow adds the Content-Type HTTP header set to application/json directly, 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 that require authentication before downloading files (Dropbox-style). Bow offers 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 proposed for the download (defaults to the file's basename)
$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 key 'disposition' 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 redirect to other resources, and this is in fact an HTTP response. The to and back methods (the latter, as its name suggests, lets you go back) of the Bow\Http\Redirect class.

Redirecting with to

Redirecting 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');

Redirecting with back

Redirecting 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 (default 302)

return redirect()->back();

Redirecting with information

You can also redirect along 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.