Skip to main content
Version: 4.x

HTTP Response

Introduction​

All routes and controllers 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 complete HTTP response.

Sending a response​

A string​

An HTTP response can be a string.

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

A Collection and 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 it directly to JSON.

use App\Models\User;

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

Modifying the response​

Modifying the error code​

It is very important to add error codes to your HTTP response if you are developing a RESTFUL API. The status method allows you to 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.

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

Adding an HTTP header​

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

$response->addHeader('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 in 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​

$response->json($data, $code, $headers);
ParameterTypeDescription
$dataArray, stdClass, Iterable, JsonSerializableThe data to serialize
$codeIntThe HTTP status code
$headersArrayThe headers to add to the response

JSON sending example​

Example:

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

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

With the HELPER:

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

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

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

Sending a response from views​

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

Prototype of the render method​

$response->render($name, $data, $code, $headers);

| Parameter | Type | Description | |----------|------| | $name | String - The name of a view to render | | $data | Array - The data to send to the view | | $code | Int - The HTTP status code | | $headers | Array - The headers to add to the response |

View sending example​

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, or you may build applications where you have to authenticate before downloading files, like Dropbox. Bow offers a simple API via the Bow\Http\Response class to download a file with the download method.

Prototype of the download method​

$response->download($file, $filename = null, $headers, $disposition = 'attachment');
ParameterTypeDescription
$fileStringThe absolute path of the file
$filenameStringThe new file name; defaults to null
$headersArrayThe headers to add to the response
$dispositionStringIndicates whether the content should be displayed inline in the browser, i.e. as a web page, or as an attachment that is downloaded and saved locally.

More information about the Content-Disposition header.

Download example​

Example:

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

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

Redirection​

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

Redirection with to​

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

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

Prototype of to​

ParameterTypeDescription
$pathStringThe redirection URL
return redirect()->to('/users');

Redirection with back​

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

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

Prototype of back​

ParameterType
$status_codeInt - The HTTP code of the response; defaults to 302
return redirect()->back();

Redirection with information​

You can also perform a redirection 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.