Le contrôleur frontal (Front Controller)
Zend_Controller
Programmer's Reference Guide

L'objet Requête

Introduction

L'objet requête est un objet simple de valeur qui est passé entre Zend_Controller_Front et le routeur, le distributeur, et les classes de contrôleur. Il empaquette les noms du module demandé, du contrôleur, de l'action, et des paramètres facultatifs, aussi bien que le reste de l'environnement de requête, que ce soit le HTTP, du CLI, ou de PHP-GTK.

  • Le nom de module est accessible par getModuleName() et setModuleName().

  • Le nom de contrôleur est accessible par getControllerName() et setControllerName().

  • Le nom de l'action à appeler dans le contrôleur est accessible par getActionName() et setActionName().

  • Les paramètres accessibles par l'action sont dans un tableau associatif de paires clés et valeurs qui sont récupérables par getParams() et modifiables par setParams(), ou individuellement par getParam() et setParam().

En fonction du type de requête, il peut y avoir plus de méthodes disponibles. La requête par défaut utilisée, Zend_Controller_Request_Http, par exemple, a des méthodes pour rechercher l'URI de la requête, l'information sur le chemin, les paramètres $_GET et $_POST, etc.

L'objet requête est passé au contrôleur frontal, ou si aucun n'est fourni, il est instancié au début du processus de distribution, avant que le routage ne se produise. Il est passé à travers chaque objet dans la chaîne de distribution.

De plus, l'objet requête est particulièrement utile pour les tests. Le développeur peut simuler l'environnement de requête, y compris le module, le contrôleur, l'action, les paramètres, l'URI, etc., et passe l'objet requête au contrôleur frontal pour tester une application. Une fois appairés avec l'objet réponse, les tests unitaires élaboré et précis d'application MVC deviennent possible.

Les requêtes HTTP

Accéder aux données de la requête

Zend_Controller_Request_Http encapsule l'accès aux valeurs appropriées telles que le nom de la clé et la valeur pour les variables contrôleur d'action et routeur , et tous les paramètres additionnels analysés à partir de l'URI. Il permet en plus l'accès aux valeurs contenues dans les superglobales en tant que membres publics, et contrôle l'URL de base et l'URI courants de la requête. Des valeurs superglobales ne peuvent pas être placées dans un objet requête, au lieu de cela utilisez les méthodes setParam() et getParam() pour régler ou pour récupérer des paramètres d'utilisateur.

Note: Données superglobales
 En accédant à des données superglobales par Zend_Controller_Request_Http en tant que propriétés publiques de membre, il est nécessaire de maintenir dans l'esprit que le nom de propriété (clé du tableau des superglobales) est assorti à une superglobale dans un ordre spécifique de priorité : 1. GET, 2. POST, 3. COOKIE, 4. SERVER, 5. ENV.

Des superglobales spécifiques peuvent être accédées en utilisant une méthode publique comme alternative. Par exemple, la valeur directe $_POST['user'] peut être accédée en appelant getPost('user') sur l'objet de requête. Ceci inclue getQuery() pour rechercher des éléments $$_GET, et getHeader() pour récupérer les en-têtes de la requête.

Note: Données GET et POST
 Soyez prudent en accédant à des données de l'objet de requête car il n'est pas du tout filtré. Le routeur et le distributeur valident et filtrent les données pour leur usage, mais laissent les données intactes dans l'objet de requête.

Note: Récupérer les données POST brutes
 A partir de la version 1.5.0, vous pouvez aussi les données POST brutes avec la méthode getRawBody(). La méthode retourne FALSE si aucune donnée n'a été envoyé, et le corps complet du POST sinon.
Ceci est principalement utile pour accepter le contenu lors du développement des applications MVC de type REST.

Vous pouvez également placer des paramètres d'utilisateur dans l'objet de requête en utilisant setParam() et récupérer ces derniers en utilisant plus tard getParam(). Le routeur se sert de cette fonctionnalité pour faire correspondre des paramètres de l'URI de la requête dans l'objet requête.

Note: getParam() retrouve plus que les paramètres d'utilisateur
 Afin d'effectuer une partie de son travail, getParam() recherche réellement dans plusieurs sources. Dans l'ordre de priorité, ceux-ci incluent : l'ensemble de paramètres d'utilisateur réglés par l'intermédiaire de setParam(), les paramètres GET, et finalement les paramètres POST. Faites attention à ceci lorsque vous récupérez des données par l'intermédiaire de cette méthode.
Si vous souhaitez rechercher seulement dans les valeurs que vous avez paramétrées avec setParam(), utilisez getUserParam().
De plus, à partir de la version 1.5.0, vous pouvez verrouiller les sources de paramètres à utiliser. setParamSources() vous permet de spécifier un tableau vide ou un tableau contenant une ou plusieurs des valeurs "_GET" ou "_POST" indiquant quelle source de paramètres est autorisée (par défaut les deux sont autorisées) ; si vous souhaitez restreindre l'accès seulement à "_GET", spécifiez setParamSources(array('_GET')).

Note: Caprices d'Apache
 Si vous utilisez le gestionnaire 404 d'Apache pour passer les requêtes entrantes au contrôleur frontal, ou si vous utilisez le drapeau PT avec les règles de ré-écriture, $_SERVER['REDIRECT_URL'] contient l'URI dont vous avez besoin, pas $_SERVER['REQUEST_URI']. Si vous employez une telle installation et obtenez un routage invalide, vous devriez employer la classe Zend_Controller_Request_Apache404 au lieu de la classe HTTP par défaut pour votre objet de requête :

  1. $request = new Zend_Controller_Request_Apache404();
  2. $front->setRequest($request);
Cette classe étend la classe Zend_Controller_Request_Http et modifie simplement la recherche automatique de l'URI de la requête. Elle peut être employée comme un remplacement "drop-in".

Base de l'URL et sous-dossiers

Zend_Controller_Request_Http permet à Zend_Controller_Router_Rewrite d'être employé dans des sous-répertoires. Zend_Controller_Request_Http essayera de détecter automatiquement votre base d'URL et de la régler en conséquence.

Par exemple, si vous maintenez votre index.php dans un sous-répertoire du serveur Web appelé /projects/myapp/index.php, la base d'URL (rewrite base) devrait être réglé à /projects/myapp. Cette chaîne sera alors dépouillée du début du chemin avant de calculer tous les routes correspondantes. Ceci libère de la nécessité de l'ajouter au début de n'importe laquelle de vos routes. Une route 'user/:username' correspondra à des URI comme http://localhost/projects/myapp/user/martel et http://example.com/user/martel.

Note: La détection d'URL est sensible à la casse
 La détection automatique d'URL de base est sensible à la casse, ainsi assurez vous que votre URL correspond à un nom de sous-répertoire dans le système de fichiers (même sur les machines Windows). S'il n'y en a pas, une exception sera levée.

Si la base de l'URL est détectée de manière inexacte vous pouvez la surcharger avec votre propre chemin de base grâce à la méthode setBaseUrl() soit de la classe de Zend_Controller_Request_Http, soit de la classe de Zend_Controller_Front. La méthode la plus facile est de la régler dans Zend_Controller_Front, qui le transmets dans l'objet de requête. Exemple d'utilisation pour régler une base d'URL personnalisée :

  1. /**
  2. * Distribue la requête avec une base d'URL réglé
  3. * avec Zend_Controller_Front.
  4. */
  5. $router     = new Zend_Controller_Router_Rewrite();
  6. $controller = Zend_Controller_Front::getInstance();
  7. $controller->setControllerDirectory('./application/controllers')
  8.            ->setRouter($router)
  9.            ->setBaseUrl('/projects/myapp'); // affecte la base d'url
  10. $response   = $controller->dispatch();

Déterminer le type de la requête

getMethod() vous permet de déterminer le type de requête HTTP utiliser pour appeler la ressource courante. De plus, différentes méthodes existent pour récupérer sous la forme de booléen le type de requête réalisée :

  • isGet()

  • isPost()

  • isPut()

  • isDelete()

  • isHead()

  • isOptions()

La principale utilisation est lors de la création des architectures MVC de type REST.

Détecter les requêtes AJAX

Zend_Controller_Request_Http possède une méthode rudimentaire pour détecter les requêtes AJAX : isXmlHttpRequest(). Cette méthode parcourt les en-têtes de la requête HTTP à la recherche de X-Requested-With ayant la valeur "XMLHttpRequest" ; si celui-ci est trouvé, la méthode retourne TRUE.

Actuellement, on sait que cet en-tête est fourni par défaut par les bibliothèques JS suivantes :

  • Prototype et Scriptaculous (et les librairies dérivées de Prototype)

  • Yahoo! UI Library

  • jQuery

  • MochiKit

La plupart des librairies AJAX vous permettent d'envoyer vos propres en-têtes de requête HTTP ; si votre librairie n'envoie pas cet en-tête, ajoutez le simplement afin d'être sûr que la méthode isXmlHttpRequest() fonctionne dans votre cas.

Sous-classer l'objet Requête

La classe de requête de base utilisée pour tous les objets de requête est la classe abstraite Zend_Controller_Request_Abstract. Au minimum, elle définit les méthodes suivantes :

  1. abstract class Zend_Controller_Request_Abstract
  2. {
  3.     /**
  4.      * @return string
  5.      */
  6.     public function getControllerName();
  7.  
  8.     /**
  9.      * @param string $value
  10.      * @return self
  11.      */
  12.     public function setControllerName($value);
  13.  
  14.     /**
  15.      * @return string
  16.      */
  17.     public function getActionName();
  18.  
  19.     /**
  20.      * @param string $value
  21.      * @return self
  22.      */
  23.     public function setActionName($value);
  24.  
  25.     /**
  26.      * @return string
  27.      */
  28.     public function getControllerKey();
  29.  
  30.     /**
  31.      * @param string $key
  32.      * @return self
  33.      */
  34.     public function setControllerKey($key);
  35.  
  36.     /**
  37.      * @return string
  38.      */
  39.     public function getActionKey();
  40.  
  41.     /**
  42.      * @param string $key
  43.      * @return self
  44.      */
  45.     public function setActionKey($key);
  46.  
  47.     /**
  48.      * @param string $key
  49.      * @return mixed
  50.      */
  51.     public function getParam($key);
  52.  
  53.     /**
  54.      * @param string $key
  55.      * @param mixed $value
  56.      * @return self
  57.      */
  58.     public function setParam($key, $value);
  59.  
  60.     /**
  61.      * @return array
  62.      */
  63.      public function getParams();
  64.  
  65.     /**
  66.      * @param array $array
  67.      * @return self
  68.      */
  69.     public function setParams(array $array);
  70.  
  71.     /**
  72.      * @param boolean $flag
  73.      * @return self
  74.      */
  75.     public function setDispatched($flag = true);
  76.  
  77.     /**
  78.      * @return boolean
  79.      */
  80.     public function isDispatched();
  81. }

L'objet de requête est un conteneur pour l'environnement de la requête. La chaîne de contrôleur doit seulement savoir régler et récupérer le contrôleur, l'action, les paramètres facultatifs, et le statut distribué. Par défaut, la demande recherchera ses propres paramètres en utilisant les clés de contrôleur ou d'action afin de déterminer le contrôleur et l'action.

Étendez cette classe, ou une de ses dérivés, quand vous avez besoin de la classe de requête pour interagir avec un environnement spécifique afin de récupérer des données pour les utiliser dans les tâches ci-dessus. Les exemples incluent l'environnement HTTP, un environnement CLI, ou un environnement PHP-GTK.

Le contrôleur frontal (Front Controller)
Zend_Controller
Programmer's Reference Guide