🚦 Routing

Introduction

Le routage est un élément essentiel dans le développement d'une application web. Il permet de relier une URL à une action spécifique dans le contrôleur de l'application. Dans BowPHP, le système de routage est directement intégré à l'instance de l'application, via la variable superglobale $app.

Les routes de l'application se définissent dans le fichier app.php, qui se trouve dans le dossier routes de votre projet.

Mappage d'URL

Le système de routage de BowPHP permet de faire correspondre une URL à un contrôleur ou une action. Cela se fait en associant une URL à une méthode HTTP (GET, POST, PUT, DELETE, etc.) et en définissant l'action à exécuter lorsqu'une requête correspond à cette route.

Structure du Routage

Le routage dans BowPHP s'écrit ainsi :

$app->[method](url, action);

• method : Le verbe HTTP (GET, POST, PUT, DELETE, OPTIONS, PATCH), toujours écrit en minuscule.
• url : L'URL à matcher.
• action : L'action à exécuter. Cela peut être une closure (fonction anonyme), un tableau de closures, ou le nom d'un contrôleur.

Exemple de Routage

Avec une Closure :

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

Qu'est-ce qu'une closure ? Une closure est une fonction anonyme qui peut être définie à la volée et utilisée dans le routage de BowPHP. Pour plus d'infos, consultez la documentation sur les closures.

Avec un tableau de fonctions (callables) :

$callables = [];

$callables[] = function () {
    echo 'Hello World';
    return true; // Retourne true pour exécuter la fonction suivante
};

$callables[] = function () {
    echo 'Bien merci';
};

$app->get('/', $callables);

Attention : La première fonction doit retourner true pour permettre à la suivante de s'exécuter. Si elle retourne false, l'exécution des fonctions suivantes s'arrêtera.

Avec un contrôleur :

$app->get('/', 'UserController::action');

Avec un contrôleur et un middleware :

$app->get('/', ['middleware' => 'ip', 'controller' => 'UserController::action']);

Utilisation d'un contrôleur avec la méthode __invoke :

Si le contrôleur implémente la méthode magique __invoke, vous pouvez l'utiliser directement comme une fonction :

$app->get('/', UserController::class);

Liste des Méthodes de Mappage

Voici les principales méthodes de routage dans BowPHP :

$app->get($url, $action);
$app->post($url, $action);
$app->put($url, $action);
$app->delete($url, $action);
$app->option($url, $action);
$app->patch($url, $action);

Exemples de Routage avec différentes Méthodes HTTP

• GET : Pour récupérer des données

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

• POST : Pour envoyer des données au serveur

$app->post('/', function () {
    return 'Data posted';
});

• PUT : Pour mettre à jour des ressources existantes

$app->put('/', function () {
    return 'Resource updated';
});

• DELETE : Pour supprimer une ressource

$app->delete('/', function () {
    return 'Resource deleted';
});

• PATCH : Pour appliquer des modifications partielles à une ressource

$app->patch('/', function () {
    return 'Partial update applied';
});

• OPTIONS : Pour récupérer les options disponibles pour une ressource

$app->options('/', function () {
    return 'Options retrieved';
});

remarque

Note importante : Les navigateurs ne supportent pas les méthodes DELETE, PUT et PATCH nativement. Pour contourner cette limitation, vous pouvez ajouter un champ caché dans vos formulaires HTML :

<input type="hidden" name="_method" value="DELETE">

Ceci va permettre à BowPHP de comprendre que vous voulez contacter la route associée à la methode DELETE

Mappage Multiple

match: Mappage avec plusieurs Méthodes HTTP

Si vous souhaitez faire correspondre plusieurs méthodes HTTP (comme GET et POST) à une même URL, vous pouvez utiliser la méthode match :

$app->match(['GET', 'POST'], '/users', function () {
    // Code ici
});

Vous pouvez également traiter les différents types de requêtes dans une seule action :

use Bow\Http\Request;

$app->match(['GET', 'POST'], '/users', function (Request $request) {
    if ($request->isPost()) {
        // Traitement pour la requête POST
    } else {
        // Traitement pour la requête GET
    }
});

any: Mappage avec n'importe quelle Méthode HTTP

Si vous souhaitez que n'importe quelle méthode HTTP corresponde à une URL, vous pouvez utiliser any :

$app->any('/', function () {
    // Code ici
});

Groupes de Routes avec prefix

Lorsque vous avez plusieurs routes qui partagent un préfixe similaire (par exemple, /users, /users/:id, /users/:id/delete), vous pouvez utiliser la méthode prefix pour organiser votre code de manière plus propre.

$app->prefix('/users', function () use ($app) {
    $app->get('/', function () {
        // Code pour récupérer tous les utilisateurs
    });

    $app->get('/:id', function ($id) {
        // Code pour récupérer un utilisateur par ID
    });

    $app->get('/:id/delete', function ($id) {
        // Code pour supprimer un utilisateur
    });
});

danger

Note : La méthode prefix ne peut pas être imbriquée dans d'autres groupes de routes.

Personnalisation des Routes

BowPHP permet de personnaliser vos routes de plusieurs façons, notamment :

• Capturer des variables dans l'URL
• Ajouter des critères de validation sur les variables capturées
• Nommer les routes pour une gestion plus facile
• Associer des middlewares à des routes spécifiques
• Combiner différentes actions (middleware, contrôleur)

Capturer des Variables dans l'URL

Pour capturer des variables dans l'URL, utilisez la notation :variable_name. Ces variables seront ensuite passées à l'action correspondante.

$app->get('/:name', function ($name) {
    return 'Bonjour ' . $name;
});

Ajouter des Critères de Validation sur les Variables

Lorsque vous capturez des variables, vous pouvez les valider à l'aide de la méthode where pour garantir que les données sont bien conformes à une certaine règle.

Exemple avec une seule variable :

$app->get('/:name', function ($name) {
    return 'Bonjour ' . $name;
})->where('name', '[a-z]+');

Exemple avec plusieurs variables :

$app->get('/:name/:lastname/:number', function ($name, $lastname, $number) {
    return sprintf('Bonjour %s %s, votre numéro est %s', $name, $lastname, $number);
})->where([
    'name' => '[a-z]+',
    'lastname' => '[a-z]+',
    'number' => '\d+'
]);

Note : La méthode where permet de définir des règles de validation pour chaque variable capturée dans l'URL.

Nommer les Routes

Pour faciliter la gestion des routes dans les grandes applications, vous pouvez leur attribuer des noms. Cela permet de référencer facilement une route dans votre code.

$app->get('/:name', function ($name) {
    return 'Bonjour ' . $name;
})->name('greeting');

Utilisation des Middlewares

Un middleware est une fonction ou un ensemble de fonctions qui interviennent entre la requête et l'action à exécuter. Vous pouvez associer un ou plusieurs middlewares à une route.

Exemple d'association de middleware :

$app->get('/:name', ['middleware' => 'auth', function ($name) {
    return 'Bonjour ' . $name;
}]);

// Ou avec la méthode `middleware()` :
$app->get('/:name', function ($name) {
    return 'Bonjour ' . $name;
})->middleware('auth');

Composition d'Actions

BowPHP permet également de combiner un contrôleur et un middleware pour une route spécifique. Voici un exemple :

$app->get('/:name', [
    'middleware' => 'auth',
    'controller' => 'UserController::show'
]);

Utilisation de la méthode route

La méthode route dans BowPHP permet de définir une route de manière plus simple et flexible. Elle accepte un tableau de paramètres, ce qui vous permet de personnaliser la route de façon plus détaillée.

Prototype de la méthode route

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'handler'
]);

Liste des options disponibles dans route

Paramètre	Type	Description
path	String	Le chemin de l'URL à matcher
method	String, Array	Méthode HTTP (GET, POST, PUT, DELETE, OPTIONS, PATCH)
handler	String, Array	Action à exécuter (peut être une closure, un contrôleur, etc.)
middleware	String, Array	Middleware(s) à appliquer avant d'exécuter l'action
where	String, Array	Contrainte(s) appliquée(s) sur les variables dans l'URL
name	String, Array	Nom de la route pour une gestion facile

Exemple d'utilisation de route avec une closure

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => function () {
    return "Hello, Bow";
  }
]);

Exemple d'utilisation de route avec un contrôleur

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'HomeController::action'
]);

Note : Pour plus d'informations sur les contrôleurs, consultez la section Contrôleurs.

Exemple d'utilisation de route avec un contrôleur et un middleware

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'HomeController::show',
  'middleware' => ['auth']
]);

Note : Pour en savoir plus sur les middlewares, consultez la section Middleware.

Exemple d'utilisation de route avec un contrôleur, un middleware et une restriction

$app->route([
  'path' => '/:name',
  'method' => "GET",
  'handler' => 'HomeController::show',
  'middleware' => ['auth'],
  'where' => ['name' => '[a-z]+']
]);

Cette méthode est particulièrement utile lorsque vous avez besoin d'une syntaxe plus concise et que vous souhaitez avoir plus de contrôle sur les paramètres de votre route.

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.