📦 Response

Introduction

À propos des réponses HTTP

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

$response->json($data, $code, $headers);

Paramètre	Type	Description
$data	Array, stdClass, Iterable, JsonSerializable	Les données à sérialiser
$code	Int	Le code du statut HTTP
$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

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

| Paramètre | Type | Description | |----------|------| | $name | String | Le nom d'une vue à rendre | | $data | Array | Les données à envoyer à la vue | | $code | Int | Le code du statut HTTP | | $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

$response->download($file, $filename = null, $headers, $disposition = 'attachment');

Paramètre	Type	Description
$file	String	Le chemin absolu du fichier
$filename	String	Le nom du fichier (par défaut null)
$headers	Array	Les en-têtes à ajouter à la réponse
$disposition	String	Indiquant si le contenu devrait être affiché en ligne dans le navigateur (page Web) ou en pièce jointe téléchargée et enregistrée localement

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

Exemple de téléchargement

Exemple :

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

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

Et vous pouvez utiliser le helper response_download.

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 sur directement sur le github.