# 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/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/getParam pour régler ou pour récupérer des paramètres d'utilisateur.

#### 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.

#### 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.

#### 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.

#### 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'))`.

#### 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 :

    $request = new Zend_Controller_Request_Apache404();
    $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`.

#### 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 :

    /**
     * Distribue la requête avec une base d'URL réglé
     * avec Zend_Controller_Front.
     */
    $router     = new Zend_Controller_Router_Rewrite();
    $controller = Zend_Controller_Front::getInstance();
    $controller->setControllerDirectory('./application/controllers')
               ->setRouter($router)
               ->setBaseUrl('/projects/myapp'); // affecte la base d'url
    $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/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 :

    abstract class Zend_Controller_Request_Abstract
    {
        /**
         * @return string
         */
        public function getControllerName();

        /**
         * @param string $value
         * @return self
         */
        public function setControllerName($value);

        /**
         * @return string
         */
        public function getActionName();

        /**
         * @param string $value
         * @return self
         */
        public function setActionName($value);

        /**
         * @return string
         */
        public function getControllerKey();

        /**
         * @param string $key
         * @return self
         */
        public function setControllerKey($key);

        /**
         * @return string
         */
        public function getActionKey();

        /**
         * @param string $key
         * @return self
         */
        public function setActionKey($key);

        /**
         * @param string $key
         * @return mixed
         */
        public function getParam($key);

        /**
         * @param string $key
         * @param mixed $value
         * @return self
         */
        public function setParam($key, $value);

        /**
         * @return array
         */
         public function getParams();

        /**
         * @param array $array
         * @return self
         */
        public function setParams(array $array);

        /**
         * @param boolean $flag
         * @return self
         */
        public function setDispatched($flag = true);

        /**
         * @return boolean
         */
        public function isDispatched();
    }

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.