Framework W :: Documentation

Light & powerful PHP framework

Les routes

À quoi servent les routes ?

Les routes permettent d'associer simplement des URL virtuelles à des pages spécifiques de votre site. Plus précisémment, elles vous permettent d'exécuter une méthode de contrôleur que vous avez choisie, en fonction d'un masque d'URL.

Par exemple, vous pouvez décider d'associer l'URL http://www.domain.com/services/ à la méthode de contrôleur services(), et l'URL http://www.domain.com/a-propos/ à la méthode about().

Comment créer une nouvelle route ?

Toutes les routes doivent être définie dans le fichier app/routes.php, dans le tableau $w_routes.

Chacune des routes, ou association entre une URL et une méthode de contrôleur, est définie par un tableau associatif de 4 éléments ayant ce format :

[
	"GET", 				//la ou les méthodes HTTP de la requête
	"/services/",		//le masque d'URL à associer 
	"Default#services",	//le nom du contrôleur et le nom de la méthode à appeler
	"default_services"	//le nom de cette route-ci
]

Cette route sera donc sélectionnée par le routeur si les conditions suivantes sont remplies :

  • La requête est réalisée précisémment à l'URL http://www.domain.com/services/
  • La requête est réalisée en GET (et non en POST par exemple)

Si cette route est sélectionnée, la méthode services() du \Controller\DefaultController sera exécutée.

Voyons chacun des ces éléments de définition de routes plus en détails.

Élément #1 : les méthodes HTTP

Le premier élément d'un tableau de route est la méthode HTTP requise afin que la route soit sélectionnée. Il est possible de spécifier plusieurs méthodes en les séparant par une barre verticale.

Ainsi, la route

["POST", "/contact/", "Default#contact", "default_contact"],
sera sélectionnée que si la requête est réalisée en POST.

Pour que cette même route soit sélectionnée en GET et/ou en POST, comme par exemple si vous souhaitez afficher et traiter le formulaire dans la même méthode, utilisez la barre verticale :

["GET|POST", "/contact/", "Default#contact", "default_contact"],

Élément #2: le masque d'URL

Le masque d'URL indique à quoi doit ressembler l'URL afin que cette route soit choisie.

Le masque est donc une simple chaîne, commençant toujours par un /, et dont le chemin est relatif au nom de domaine, ou au dossier `public/` si vous accédez à votre application dans un sous-dossier.

Ainsi, si votre site est accessible à http://localhost/projet/public/, vos masques d'URL seront interprétés relativement au dernier /.

Vous pouvez sans problème ajouter des sous-dossiers virtuels dans vos URLs. En fait, vous pouvez utiliser n'importe quel caractère d'URL valide :

$w_routes = [
	["GET", "/services/", "Default#services", "default_service"],
	["GET", "/services/vente/", "Default#vente", "default_vente"],
	["GET", "/services/location-et-services/", "Default#location", "default_location"],
]

Notez que le / final n'est pas obligatoire, mais qu'il devra être présent dans vos URLs si vous l'avez indiqué dans vos routes.

Élément #3 : la méthode du contrôleur associée

La méthode de contrôleur qui sera appelée est définie sous la forme nomDuControleur#nomDeLaMethode, soit le nom du contrôlleur (sans son suffixe Controller), suivi d'un dièze comme séparateur, suivi du nom de la méthode à exécuter. Ainsi, si l'on souhaite appeler la méthode login du \Controller\UserController, nous utiliserons User#login.

Élément #4 : le nom de la route

Le dernier élément de la définition d'une route est son nom. Le nom d'une route est utile pour y faire référence, par exemple lorsque l'on souhaite générer l'URL associée à cette route, ou si l'on souhaite faire une redirection vers une route spécifique.

Vous pouvez nommer vos routes comme bon vous semble, mais chaque route doit avoir un nom unique. Une technique efficace est donc de nommer les routes sous la forme nomducontroleur_nomdelamethode

Par convention, le nom des routes est écrit en minuscules et les mots sont séparés par des underscores.

Les paramètres dynamiques

Il est possible de définir des portions d'URLs dynamiques dans vos masques (éléments #2).

Par exemple, au lieu d'avoir des URLs de type http://www.domain.com/biens-en-vente/?id=456, vous pourrez facilement avoir des URLs plus esthétiques, de type http://www.domain.com/biens-en-vente/456/. Pour définir cette route :

["GET", "/biens-en-vente/[:id]/", "Default#sellListing", "sell_listing"],

Dans cette route, [:id] est un paramètre d'URL dynamique. Le routeur considérera l'URL comme correspondant au masque d'URL si elle est de la forme /biens-en-vente/nimporte-quoi-ici/.

Vous pouvez également définir plusieurs paramètres dynamiques. Vous devez simplement vous assurer que chacun possèdent un nom différent des autres, dans la même URL :

["GET", "/biens-en-vente/[:country]/[:city]/[:id]/", "Default#sellListing", "sell_listing"],

AltoRouteur permet également de spécifier une expression rationnelle à laquelle doit correspondre le paramètre dynamique pour être valide. Ainsi, si le paramètre dynamique de l'URL ne correspond pas à l'expression rationnelle spécifier dans la définition de route, la route ne sera pas exécutée. AltoRouter vous fournit en plus quelques raccourcis pour des expressions rationnelles courantes. N'hésitez pas à vous référer à la documentation d'AltoRouter pour plus de détails, mais voici les expressions les plus utiles :

[i:id] //un nombre entier, nommé 'id'
[i:postId] //un nombre entier, nommé postId
[a:country] //une chaîne alphanumérique, nommé country
[:slug] //n'importe quels caractères, nommé slug
[create|edit:action] //les chaînes 'create' ou 'edit', nommé action
[@[0-9]{4}:year] //un entier de 4 chiffres, nommé year (expression rationnelle perso, commence par un @)

Notez que le nom des paramètres dynamiques est utile pour générer des URLs ou rediriger vers une route spécifique comprenant des paramètres. Voir les sections ci-dessous.

Récupérer la valeur des paramètres dynamiques dans le contrôleur

Si vous avez choisi de définir une route avec des paramètres dynamiques, il est certain que vous souhaiterez en récupérer la valeur dans votre contrôleur. Par exemple, vous souhaiterez être en mesure de récupérer l'article dont l'identifiant figure dans l'URL. Afin de rendre cette opération courante très simple, le routeur appelle vos méthodes de contrôleurs en vous passant les paramètres dynamiques en argument de votre méthode. Par exemple, pour cette route :

["GET", "/biens-en-vente/[a:country]/[:city]/[i:id]/", "Default#sellListing", "sell_listing"],

vous recevrez les 3 paramètres directement en argument de la méthode sellListing :

/* app/Controller/DefaultController.php */

//..

public function sellListing($country, $city, $id)
{
	//récupérer en bdd le bien dont l'identifiant est $id...
	//...
}

Générer des URLs, créer des liens et rediriger

Depuis le contrôleur

Dans un contrôleur, quelques méthodes peuvent vous être utiles pour réaliser des redirections ou pour générer des URLs :

/* app/Controller/DefaultController.php */

//...
class DefaultController extends \W\Controller\Controller
{
	public function test()
	{
		//du code...

		//une redirection vers l'accueil
		$this->redirectToRoute('default_home');
	}

	public function exemple()
	{
		//du code...

		//une redirection vers une route définie avec des paramètres dynamiques
		//il faut en effet spécifier la valeur des paramètres afin que le routeur puisse générer l'URL
		$this->redirectToRoute('default_details', ['id' => 35]);
	}

	public function yo()
	{
		//du code...

		//redirection vers un site externe
		$this->redirect('http://lesjoiesducode.com');
	}

	public function sendEmail()
	{
		//récupère uniquement l'URL associée à une route
		$url = $this->generateUrl('nom_de_la_route', ['slug' => 'un-slug-4949']);
	}
}

Depuis les vues

À partir d'un fichier de vue, vous pouvez (devriez) appeler la méthode $this->url() pour générer une URL associée à une route :

/* app/Views/default/home.php */
<?php //... ?>

<a href="<?=$this->url('contact');?>">Contact</a> | 
<a href="<?=$this->url('article_details', ['id' => $data['id']]);?>">Détails de l'article</a>