Download the PHP package mithridatem/router without Composer

# Mithridatem Router

Mithridatem Router est une bibliotheque PHP oriente PSR-4 qui fournit un mecanisme de routage HTTP minimaliste, testable et independant de tout framework.

Caracteristiques clefs

• API fluide pour declarer des routes GET, POST ou multi-methodes avec segments dynamiques {id} et wildcards /*.
• Resolution de controlleurs parametres via references (Route::controller) compatible avec un conteneur de dependances.
• Controle d'acces branchable grace a l'interface GrantCheckerInterface (implementations AllowAllGrantChecker, ArrayGrantChecker ; le routeur utilise ArrayGrantChecker([]) par defaut).
• Contexte de requete abstrait (RequestContextInterface) pour isoler les superglobales PHP et faciliter les tests.
• Base path configurable (Router::setBasePath) pour les applications hebergees derriere un prefixe.
• Exceptions explicites (RouteNotFoundException, UnauthorizedException, RouterException) pour une gestion d'erreur claire.

Installation

En developpement local sur ce depot, pensez a executer composer dump-autoload apres toute modification de namespace.

Premiers pas

Par defaut dispatch() detecte la requete courante via Http\Request::fromGlobals(). Les anciens contextes restent acceptes. Pour des tests unitaires, injectez votre propre contexte :

Requete HTTP et injection dans les actions

L'objet Http\Request donne acces aux parametres d'URL, aux champs de formulaire, aux en-tetes et au corps brut. Il implemente RequestInterface, qui etend le contrat RequestContextInterface existant.

La requete est injectee par son type, quelle que soit sa position dans la signature. Les parametres de route restent transmis par nom. Ce mecanisme fonctionne aussi avec les methodes annotees #[Route] et les resolvers de controleurs existants. query('page', '1') lit les donnees d'URL ; post('title') lit celles du formulaire. Le JSON se lit via getContent() puis se decode explicitement.

Un ancien contexte minimal reste compatible avec les actions existantes. Une action demandant RequestInterface necessite un contexte compatible, sinon une RouterException est levee.

Voir le guide des requetes HTTP, les exemples executables avec Attributes.

Fichiers envoyes par formulaire

Request implemente aussi FileRequestInterface, qui etend RequestInterface sans la modifier. Les implementations personnalisees existantes restent compatibles.

files('attachments') gere les fichiers multiples et les champs imbriques. UploadedFile::moveTo($destination) encapsule move_uploaded_file() ; le nom d'origine et le chemin temporaire restent consultables apres le deplacement. La superglobale $_FILES reste intacte et utilisable avec l'ancienne methode.

Voir le guide des uploads et l'exemple avec formulaire.

Controlleurs et resolution

Lorsque vos handlers resident dans des classes, utilisez Route::controller() et laissez le routeur resoudre la methode correspondante :

Par defaut, DefaultControllerResolver instancie la classe sans dependances. Pour deleguer la resolution a un conteneur, fournissez votre propre implementation de ControllerResolverInterface :

Routage par Attributes et decouverte automatique

Depuis PHP 8.1, vous pouvez declarer les routes directement sur les methodes des controleurs avec l'Attribute #[Route]. La decouverte automatique permet de charger tous les controleurs du repertoire src/Controller/ (y compris ses sous-repertoires) sans les enregistrer individuellement.

1. Configurer l'autoload PSR-4 de votre application

Dans le composer.json du projet utilisant la librairie :

Apres une modification de l'autoload :

Arborescence d'exemple :

2. Declarer les routes dans les controleurs

Fichier src/Controller/HomeController.php :

Fichier src/Controller/Admin/DashboardController.php :

L'Attribute accepte aussi plusieurs methodes HTTP : #[Route(path: '/endpoint', method: ['GET', 'POST'])].

3. Charger automatiquement les routes

Dans public/index.php :

Le dossier doit correspondre au namespace PSR-4. Par exemple, src/Controller/Admin/DashboardController.php doit declarer namespace App\Controller\Admin;.

Le chargement utilise l'autoload Composer et n'inclut pas directement les fichiers trouves. Les classes non autoloadables sont ignorees. Les classes abstraites (par exemple AbstractController) et les autres classes non instanciables sont egalement ignorees lors de la decouverte du repertoire. Les controleurs concrets peuvent donc heriter d'une base abstraite dans ce meme dossier. Leurs methodes publiques heritees portant #[Route] restent chargees. L'enregistrement explicite d'une classe non instanciable via loadController() ou loadControllers() continue de lever une exception.

4. Autorisations et compatibilite

Les routes contenant grants sont refusees par defaut en l'absence de droits configures. Pour cet exemple :

Vous pouvez toujours melanger decouverte automatique et declaration manuelle :

5. Injection de dependances dans un controleur

La decouverte automatique enregistre les routes, mais elle ne construit pas les controleurs avec leurs dependances. Le resolver par defaut appelle new Controller() ; pour injecter des services, il faut fournir un ControllerResolverInterface personnalise.

Cet exemple utilise un registre d'instances, sans dependre d'un framework ou d'un conteneur externe.

Service : src/Service/ProductService.php

Controleur : src/Controller/ProductController.php

Resolver : src/Routing/InstanceControllerResolver.php

Point d'entree : public/index.php

La route GET /products/42 renvoie Produit #42. La declaration #[Route] est toujours decouverte automatiquement ; seule la creation de l'instance du controleur est explicite. Les autres controleurs decouverts doivent aussi etre enregistres dans ce resolver, sous peine d'erreur lors du dispatch. Pour une application plus importante, remplacez le registre par un resolver deleguant a un conteneur PSR-11.

Consultez egalement le guide detaille : Decouverte automatique des controleurs.

Gestion des autorisations

Associez des droits a une route en fournissant un tableau de "grants" :

Si l'utilisateur courant ne possede aucun des droits requis, une UnauthorizedException est levee. Branchez votre propre verificateur via GrantCheckerInterface pour relier vos mecanismes d'authentification.

Base path et sous-repertoires

Hebergez votre application derriere un prefixe sans re-ecrire vos routes :

Toutes les correspondances s'effectuent alors relativement a ce prefixe.

Gestion des erreurs

• Route introuvable : RouteNotFoundException.
• Acces refuse : UnauthorizedException.
• Erreur de resolution : RouterException.

Capturez ces exceptions et adaptez la reponse HTTP de votre application.

Tests et exemples

Un exemple minimal est disponible dans examples/basic.php. Des doubles de tests se trouvent dans tests/Support pour simuler le contexte HTTP et les controlleurs.

Aller plus loin

• Documentation d'architecture : docs/architecture.md.
• Guide de migration : docs/migration.md.
• Processus de contribution : CONTRIBUTING.md et SECURITY.md.