Réponses HTTP

Introduction

Toutes les routes et contrôleurs doivent retourner une réponse à renvoyer à l'utilisateur. Bow fournit plusieurs façons différentes de renvoyer des réponses.

La réponse la plus élémentaire est le retour d'une chaîne depuis une route ou un contrôleur. Bow convertira automatiquement la chaîne en une réponse HTTP complète.

Envoyer une réponse

Une chaîne de caractères

Une réponse HTTP peut être une chaîne de caractères.

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

Une collection, un tableau ou un objet

Une réponse HTTP peut être une instance de 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'];
});

Un modèle BARRY

La réponse HTTP peut être un Model ou une Collection de modèles. Bow les convertit directement en JSON.

use App\Models\User;

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

Modification de la réponse

Modification du code de statut

Code de statut HTTP

Il est très important d'ajouter les codes de statut appropriés à votre réponse HTTP si vous développez une API REST. La méthode status vous permet de le faire.

use App\Models\User;

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

Pour plus d'information sur les codes HTTP, consultez ce lien.

Astuce 204 vs 200

Si dans votre API, la requête a été traitée avec succès et que vous n'avez pas d'information à renvoyer, il est préférable de retourner un 204 plutôt qu'un 200.

Ajouter un en-tête HTTP

Souvent, vous serez amené à ajouter d'autres en-têtes HTTP à votre réponse HTTP. Les méthodes withHeader et withHeaders vous permettent de le faire.

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

Vous pouvez ajouter plusieurs en-têtes en même temps :

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

Envoyer un JSON

Dans les applications REST (API REST/RESTful), les informations sont généralement retournées en JSON. Pour envoyer une information JSON au client, vous pouvez utiliser le helper json ou la méthode json sur l'instance de Bow\Http\Response.

Prototype de la méthode json

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

Paramètre	Type	Description
$data	mixed (array, stdClass, Iterable, JsonSerializable...)	Les données à sérialiser
$code	int	Le code de statut HTTP (défaut 200)
$headers	array	Les en-têtes à ajouter à la réponse

Exemple d'envoi de JSON

Exemple :

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

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

Avec le HELPER response_json :

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

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

Automatisation de l'en-tête

Bow ajoute directement l'en-tête HTTP Content-Type à application/json, donc plus besoin de l'ajouter manuellement dans le $headers.

Envoyer une réponse depuis les vues

Souvent, vous pouvez utiliser une instance de Bow\Http\Response pour faire le rendu de vue via la méthode render.

Prototype de la méthode render

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

Paramètre	Type	Description
$template	string	Le nom de la vue à rendre
$data	array	Les données à envoyer à la vue
$code	int	Le code de statut HTTP (défaut 200)
$headers	array	Les en-têtes à ajouter à la réponse

Exemple d'envoi de vue

Exemple :

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

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

Télécharger un fichier

Souvent, vous serez amené à mettre en place des systèmes de téléchargement de fichiers zip ou images. Vous allez aussi faire des applications avec lesquelles il faut s'authentifier avant de télécharger des fichiers (type Dropbox). Bow offre une API simple via la classe Bow\Http\Response pour télécharger un fichier avec la méthode download.

Prototype de la méthode download

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

Paramètre	Type	Description
$file	string	Le chemin absolu du fichier
$filename	?string	Le nom proposé au téléchargement (par défaut le basename du fichier)
$headers	array	En-têtes supplémentaires à ajouter à la réponse

Content-Disposition

Pour afficher le fichier en ligne dans le navigateur au lieu de le télécharger, passez la clé spéciale 'disposition' dans $headers :

return $response->download($file, 'image.png', [
  'disposition' => 'inline',   // ou 'attachment' (défaut)
]);

Plus d'informations sur l'en-tête Content-Disposition.

Exemple de téléchargement

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

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

Vous pouvez aussi utiliser le helper response_download($file, $filename, $headers).

Redirection

Vous serez certainement amené à faire des redirections vers d'autres ressources, et cela constitue en réalité une réponse HTTP. Les méthodes to et back (qui, comme son nom l'indique, permet de revenir en arrière) de la classe Bow\Http\Redirect.

Redirection avec to

La redirection avec to permet de renvoyer l'utilisateur sur une autre la page.

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

Prototype de to

Paramètre	Type	Description
$path	String	L'URL de rédirection

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

Redirection avec back

La redirection avec back permet de renvoyer l'utilisateur sur la page précédente.

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

Prototype de back

Paramètre	Type	Description
$status_code	Int	Le code HTTP de la réponse (par défaut égal à 302)

return redirect()->back();

Redirection avec des informations

Vous pouvez aussi faire la redirection avec les informations envoyées par l'utilisateur avec les méthodes withInput et withFlash comme ceci :

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

Avec un message flash

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

Notez que vous pouvez donner un tableau de valeur à withInput qui sera une collection d'information à envoyer à utilisateur.

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou directement sur le github.