Routage dans Bow Framework

Introduction

À propos du routage

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 Bow Framework, le système de routage est intégré à l'instance de l'application et exposé dans vos fichiers de routes via la variable $router.

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 Bow Framework 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 Bow Framework s'écrit ainsi :

$router->[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 :

$router->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 Bow Framework. Pour plus d'informations, 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';
};

$router->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 :

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

Avec un contrôleur et un middleware :

$router->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 :

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

Liste des Méthodes de Mappage

Voici les principales méthodes de routage dans Bow Framework :

$router->get($url, $action);
$router->post($url, $action);
$router->put($url, $action);
$router->delete($url, $action);
$router->options($url, $action);
$router->patch($url, $action);
$router->match(['GET', 'POST'], $url, $action);
$router->any($url, $action);

Exemples de Routage avec différentes Méthodes HTTP

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

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

• POST : Pour envoyer des données au serveur

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

• PUT : Pour mettre à jour des ressources existantes

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

• DELETE : Pour supprimer une ressource

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

• PATCH : Pour appliquer des modifications partielles à une ressource

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

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

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

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 à Bow Framework de comprendre que vous voulez contacter la route associée à la méthode DELETE.

Mappage Multiple

match - Mappage avec plusieurs Méthodes HTTP

Méthode match

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

$router->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;

$router->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 :

$router->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.

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

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

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

Limitation importante

Évitez d'imbriquer des groupes prefix : le préfixe courant est réinitialisé après l'exécution du callback.

Contraintes de Sous-domaine

Bow Framework permet de restreindre des routes à un domaine ou sous-domaine spécifique.

Contrainte sur une route individuelle avec withDomain

Utilisez la méthode withDomain chaînée sur l'objet Route :

$router->get('/dashboard', function () {
  return 'Admin Dashboard';
})->withDomain('admin.example.com');

Contrainte sur un groupe de routes avec $router->domain

Fonctionnalité en développement

La méthode $router->domain() est prévue pour appliquer une contrainte de domaine à un groupe de routes, mais son implémentation est actuellement incomplète dans le framework. Utilisez withDomain() sur chaque route individuelle en attendant.

// Syntaxe prévue (non fonctionnelle actuellement)
$router->domain('api.example.com', function () use ($router) {
  $router->get('/users', 'ApiController::users');
  $router->get('/posts', 'ApiController::posts');
});

Sous-domaine statique

$router->get('/dashboard', function () {
  return 'Admin Dashboard';
})->withDomain('admin.example.com');

Sous-domaine dynamique avec paramètre

Vous pouvez capturer une partie du sous-domaine comme paramètre en utilisant la notation :param ou <param> :

$router->get('/dashboard', function ($tenant) {
  return "Dashboard pour le tenant : $tenant";
})->withDomain(':tenant.example.com');

Le paramètre $tenant sera automatiquement injecté dans votre action avec la valeur extraite du sous-domaine.

Utilisation d'un wildcard

Pour accepter n'importe quel sous-domaine, utilisez * :

$router->get('/', function () {
  return 'Bienvenue';
})->withDomain('*.example.com');

Cas d'utilisation

Les contraintes de sous-domaine sont particulièrement utiles pour :

• Les applications multi-tenant (client1.app.com, client2.app.com)
• Séparer les interfaces admin et publique (admin.site.com vs www.site.com)
• Les API versionnées (v1.api.example.com, v2.api.example.com)

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.

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

Vous pouvez aussi utiliser des paramètres optionnels :

$router->get('/users/:id?', function ($id = null) {
  return $id;
});

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 :

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

Exemple avec plusieurs variables :

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

Validation des variables

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.

$router->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 :

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

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

Composition d'Actions

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

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

Utilisation de la méthode route

La méthode route dans Bow Framework 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

$router->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, Closure, Array	Action à exécuter
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

Important

La méthode route() retourne void et ne permet pas de chaîner ->name() directement. Pour nommer une route, utilisez les méthodes HTTP (get, post, etc.) puis ->name(...).

Exemple d'utilisation de route avec une closure

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

Exemple d'utilisation de route avec un contrôleur

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

En savoir plus

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

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

En savoir plus

Pour en savoir plus sur les middlewares, consultez la section Middlewares.

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

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

Avantage de la méthode route

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.