Accéder aux paramètres de la requête¶

CakeRequest propose plusieurs interfaces pour accéder aux paramètres de la requête. La première est par des tableaux indexés, la seconde est à travers $this->request->params, et la troisième est par des propriétés d’objets:

$this->request['controller'];
$this->request->controller;
$this->request->params['controller']

Tout ce qui est au-dessus retournera la même valeur. Plusieurs façons d’accéder aux paramètres ont été faites pour faciliter la migration des applications existantes. Tous les éléments de route Les Eléments de Route sont accessibles à travers cette interface.

En plus des éléments de routes Les Eléments de Route, vous avez souvent besoin d’accéder aux arguments passés Arguments Passés et aux paramètres nommés Paramètres Nommés. Ceux-ci sont aussi tous les deux disponibles dans l’objet request:

// Arguments passés
$this->request['pass'];
$this->request->pass;
$this->request->params['pass'];

// Paramètres nommés
$this->request['named'];
$this->request->named;
$this->request->params['named'];

Tous ceux-ci vous fourniront un accès aux arguments passés et aux paramètres nommés. Il y a de nombreux paramètres importants et utiles que CakePHP utilise en interne, ils sont aussi trouvables dans les paramètres de la requête:

• plugin Le plugin gérant la requête, va être nul quand il n’y a pas de plugins.

• controller Le controller gère la requête courante.

• action L’action gère la requête courante.

• prefix Le préfixe pour l’action courante. Voir Prefix de Routage pour plus d’informations.

• bare Présent quand la requête vient de requestAction() et inclut l’option bare. Les requêtes vides n’ont pas de layout de rendu.

• requested Présent et mis à true quand l’action vient de requestAction().

Accéder aux paramètres Querystring¶

Les paramètres Querystring peuvent être lus en utilisant CakeRequest::$query:

// l'URL est /posts/index?page=1&sort=title
$this->request->query['page'];

//  Vous pouvez aussi y accéder par un tableau
// accesseur BC, va être déprécié dans les versions futures
$this->request['url']['page'];

Vous pouvez soit directement accéder à la propriété $query, soit vous pouvez utiliser CakeRequest::query() pour lire l’URL requêtée sans erreur. Toute clé qui n’existe pas va retourner null:

$foo = $this->request->query('value_that_does_not_exist');
// $foo === null

Accéder aux données POST¶

Toutes les données POST peuvent être atteintes à travers CakeRequest::$data. N’importe quelle forme de tableau qui contient un préfixe data, va avoir sa donnée préfixée retirée. Par exemple:

// Un input avec un nom attribute égal à 'data[MyModel][title]'
// est accessible
$this->request->data['MyModel']['title'];

Vous pouvez soit accéder directement à la propriété $data, soit vous pouvez utiliser CakeRequest::data() pour lire le tableau de données sans erreurs. Toute clé n’existant pas va retourner null:

$foo = $this->request->data('Value.that.does.not.exist');
// $foo == null

Accéder aux données PUT ou POST¶

Quand vous construisez des services REST, vous acceptez souvent des données requêtées sur des requêtes PUT et DELETE. Depuis 2.2, toute donnée de corps de requête application/x-www-form-urlencoded va automatiquement être parsée et définie dans $this->data pour les requêtes PUT et DELETE. Si vous acceptez les données JSON ou XML, regardez ci-dessous comment vous pouvez accéder aux corps de ces requêtes.

Accéder aux données XML ou JSON¶

Les applications employant REST échangent souvent des données dans des organes post non encodées en URL. Vous pouvez lire les données entrantes dans n’importe quel format en utilisant CakeRequest::input(). En fournissant une fonction de décodage, vous pouvez recevoir le contenu dans un format déserializé:

// Obtenir les données encodées JSON soumises par une action PUT/POST
$data = $this->request->input('json_decode');

Puisque certaines méthodes de desérialization ont besoin de paramètres supplémentaires quand elles sont appelées, comme le paramètre de type tableau pour json_decode ou si vous voulez convertir les XML en objet DOMDocument, CakeRequest::input() supporte aussi le passement dans des paramètres supplémentaires:

// Obtenir les données encodées en Xml soumises avec une action PUT/POST
$data = $this->request->input('Xml::build', array('return' => 'domdocument'));

Accéder aux informations du chemin¶

CakeRequest fournit aussi des informations utiles sur les chemins dans votre application. CakeRequest::$base et CakeRequest::$webroot sont utiles pour générer des URLs, et déterminer si votre application est ou n’est pas dans un sous-dossier.

Inspecter la requête¶

Dans les anciennes versions, détecter les différentes conditions de la requête nécéssitait RequestHandlerComponent. Ces méthodes ont été déplacées dans CakeRequest, ce qui offre une nouvelle interface tout le long, compatible avec les utilisations anciennes:

$this->request->is('post');
$this->request->isPost(); // déprécié

Les deux méthodes appelées vont retourner la même valeur. Pour l’instant, les méthodes sont toujours disponibles dans RequestHandlerComponent, mais sont depréciées et seront retirées dans 3.0.0. Vous pouvez aussi facilement étendre les détecteurs de la requête qui sont disponibles, en utilisant CakeRequest::addDetector() pour créer de nouveaux types de détecteurs. Il y a quatre différents types de détecteurs que vous pouvez créer:

• Comparaison avec valeur d’environnement - Une comparaison de la valeur d’environnement, compare une valeur attrapée à partir de env() pour une valeur connue, la valeur d’environnement est vérifiée équitablement avec la valeur fournie.

• La comparaison de la valeur model - La comparaison de la valeur model vous autorise à comparer une valeur attrapée à partir de env() avec une expression régulière.

• Comparaison basée sur les options - La comparaison basée sur les options utilise une liste d’options pour créer une expression régulière. De tels appels pour ajouter un détecteur d’options déjà défini, va fusionner les options.

• Les détecteurs de Callback - Les détecteurs de Callback vous permettront de fournir un type “callback” pour gérer une vérification. Le callback va recevoir l’objet requête comme seul paramètre.

Quelques exemples seraient:

// Ajouter un détecteur d'environnement.
$this->request->addDetector(
    'post',
    array('env' => 'REQUEST_METHOD', 'value' => 'POST')
);

// Ajouter un détecteur de valeur model.
$this->request->addDetector(
    'iphone',
    array('env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i')
);

// Ajouter un détecteur d'options
$this->request->addDetector('internalIp', array(
    'env' => 'CLIENT_IP',
    'options' => array('192.168.0.101', '192.168.0.100')
));

// Ajouter un détecteur de callback. Peut soit être une fonction anonyme
// ou un callback régulier.
$this->request->addDetector(
    'awesome',
    array('callback' => function ($request) {
        return isset($request->awesome);
    })
);

CakeRequest inclut aussi des méthodes comme CakeRequest::domain(), CakeRequest::subdomains() et CakeRequest::host() qui facilitent la vie des applications avec sous-domaines.

Vous pouvez utiliser plusieurs détecteurs intégrés:

• is('get') Vérifie si la requête courante est un GET.

• is('put') Vérifie si la requête courante est un PUT.

• is('post') Vérifie si la requête courante est un POST.

• is('delete') Vérifie si la requête courante est un DELETE.

• is('head') Vérifie si la requête courante est un HEAD.

• is('options') Vérifie si la requête courante est OPTIONS.

• is('ajax') Vérifie si la requête courante vient d’un X-Requested-With = XMLHttpRequest.

• is('ssl') Vérifie si la requête courante est via SSL.

• is('flash') Vérifie si la requête courante a un User-Agent de Flash.

• is('mobile') Vérifie si la requête courante vient d’une liste courante de mobiles.

CakeRequest et RequestHandlerComponent¶

Puisque plusieurs des fonctionnalités offertes par CakeRequest étaient l’apanage de RequestHandlerComponent, une reflexion était nécessaire pour savoir si il était toujours nécessaire. Dans 2.0, RequestHandlerComponent agit comme un sugar daddy en fournissant une couche de facilité au-dessus de l’offre utilitaire de CakeRequest. RequestHandlerComponent permet par exemple de changer les layouts et vues basés sur les types de contenu ou ajax. Cette séparation des utilitaires entre les deux classes vous permet de plus facilement choisir ce dont vous avez besoin.

Interagir avec les autres aspects de la requête¶

Vous pouvez utiliser CakeRequest pour voir une quantité de choses sur la requête. Au-delà des détecteurs, vous pouvez également trouver d’autres informations sur les diverses propriétés et méthodes.

• $this->request->webroot contient le répertoire webroot.

• $this->request->base contient le chemin de base.

• $this->request->here contient l’adresse complète de la requête courante.

• $this->request->query contient les paramètres de la chaîne de requête.

API de CakeRequest¶

class CakeRequest¶

CakeRequest encapsule la gestion des paramètres de la requête, et son introspection.

CakeRequest::domain($tldLength = 1)¶

Retourne le nom de domaine sur lequel votre application tourne.

CakeRequest::subdomains($tldLength = 1)¶

Retourne un tableau avec le sous-domaine sur lequel votre application tourne.

CakeRequest::host()¶

Retourne l’hôte où votre application tourne.

CakeRequest::method()¶

Retourne la méthode HTTP où la requête a été faite.

CakeRequest::onlyAllow($methods)¶

Définit les méthodes HTTP autorisées, si elles ne correspondent pas, elle va lancer une MethodNotAllowedException. La réponse 405 va inclure l’en-tête Allow nécessaire avec les méthodes passées.

Nouveau dans la version 2.3.

Obsolète depuis la version 2.5: Utilisez CakeRequest::allowMethod() à la place.

CakeRequest::allowMethod($methods)¶

Définit les méthodes HTTP autorisées, si cela ne correspond pas, une exception MethodNotAllowedException sera lancée. La réponse 405 va inclure l’en-tête nécessaire Allow avec les méthodes passées.

Nouveau dans la version 2.5.

CakeRequest::referer($local = false)¶

Retourne l’adresse de référence de la requête.

CakeRequest::clientIp($safe = true)¶

Retourne l’adresse IP du visiteur courant.

CakeRequest::header($name)¶

Vous permet d’accéder à tout en-tête HTTP_* utilisé pour la requête:

$this->request->header('User-Agent');

Retournerait le user agent utilisé pour la requête.

CakeRequest::input($callback[, $options])¶

Récupère les données d’entrée pour une requête, et les passe optionnellement à travers une fonction qui décode. Utile lors des interactions avec une requête de contenu de corps XML ou JSON. Les paramètres supplémentaires pour la fonction décodant peuvent être passés comme des arguments de input():

$this->request->input('json_decode');

CakeRequest::data($name)¶

Fournit une notation en point pour accéder aux données requêtées. Permet la lecture et la modification des données requêtées, les appels peuvent aussi être chaînés ensemble:

// Modifier une donnée requêtée, ainsi vous pouvez pré-enregistrer certains champs.
$this->request->data('Post.title', 'New post')
    ->data('Comment.1.author', 'Mark');

// Vous pouvez aussi lire des données.
$value = $this->request->data('Post.title');

CakeRequest::query($name)¶

Fournit un accès aux données requêtées de l’URL avec notation en point:

// l\'URL est /posts/index?page=1&sort=title
$value = $this->request->query('page');

Nouveau dans la version 2.3.

CakeRequest::is($type)¶

Vérifie si la requête remplit certains critères ou non. Utilisez les règles de détection déjà construites ainsi que toute règle supplémentaire définie dans CakeRequest::addDetector().

CakeRequest::addDetector($name, $options)¶

Ajoute un détecteur pour être utilisé avec CakeRequest::is(). Voir Inspecter la requête pour plus d’informations.

CakeRequest::accepts($type = null)¶

Trouve quels types de contenu le client accepte ou vérifie si ils acceptent un type particulier de contenu.

Récupère tous les types:

<?php
$this->request->accepts();

Vérifie pour un unique type:

$this->request->accepts('application/json');

static CakeRequest::acceptLanguage($language = null)¶

Obtenir toutes les langues acceptées par le client, ou alors vérifier si une langue spécifique est acceptée.

Obtenir la liste des langues acceptées:

CakeRequest::acceptLanguage();

Vérifier si une langue spécifique est acceptée:

CakeRequest::acceptLanguage('es-es');

CakeRequest::param($name)¶

Lit les valeurs en toute sécurité dans $request->params. Celle-ci enlève la nécessité d’appeler isset() ou empty() avant l’utilisation des valeurs de param.

Nouveau dans la version 2.4.

property CakeRequest::$data¶

Un tableau de données POST. Vous pouvez utiliser CakeRequest::data() pour lire cette propriété d’une manière qui supprime les erreurs notice.

property CakeRequest::$query¶

Un tableau des paramètres de chaîne requêtés.

property CakeRequest::$params¶

Un tableau des éléments de route et des paramètres requêtés.

property CakeRequest::$here¶

Retourne l’URL requêtée courante.

property CakeRequest::$base¶

Le chemin de base de l’application, normalement /, à moins que votre application soit dans un sous-répertoire.

property CakeRequest::$webroot¶

Le webroot courant.

Changer la classe de réponse¶

CakePHP utilise CakeResponse par défaut. CakeResponse est flexible et transparente pour l’utilisation de la classe. Si vous avez besoin de la remplacer avec une classe spécifique de l’application, vous pouvez l’écraser et remplacer CakeResponse avec votre propre classe en remplaçant la classe CakeResponse utilisée dans app/webroot/index.php.

Cela fera que tous les controllers dans votre application utiliseront VotreResponse au lieu de CakeResponse. Vous pouvez aussi remplacer l’instance de réponse de la configuration $this->response dans vos controllers. Ecraser l’objet réponse est à portée de main pour les tests car il vous permet d’écraser les méthodes qui interagissent avec header(). Voir la section sur CakeResponse et les tests pour plus d’informations.

Gérer les types de contenu¶

Vous pouvez contrôler le Content-Type des réponses de votre application en utilisant CakeResponse::type(). Si votre application a besoin de gérer les types de contenu qui ne sont pas construits dans CakeResponse, vous pouvez faire correspondre ces types avec CakeResponse::type() comme ceci:

// Ajouter un type vCard
$this->response->type(array('vcf' => 'text/v-card'));

// Configurer la réponse de Type de Contenu pour vcard.
$this->response->type('vcf');

Habituellement, vous voudrez faire correspondre des types de contenu supplémentaires dans le callback beforeFilter() de votre controller, afin que vous puissiez tirer parti de la fonctionnalité de vue de commutation automatique de RequestHandlerComponent, si vous l’utilisez.

Envoyer des fichiers¶

Il y a des fois où vous voulez envoyer des fichiers en réponses de vos requêtes. Avant la version 2.3, vous pouviez utiliser MediaView pour faire cela. Depuis 2.3, MediaView est dépréciée et vous pouvez utiliser CakeResponse::file() pour envoyer un fichier en réponse:

public function sendFile($id) {
    $file = $this->Attachment->getFile($id);
    $this->response->file($file['path']);
    //Retourne un objet reponse pour éviter que le controller n'essaie de
    // rendre la vue
    return $this->response;
}

Comme montré dans l’exemple ci-dessus, vous devez passer le chemin du fichier à la méthode. CakePHP va envoyer le bon en-tête de type de contenu si c’est un type de fichier connu listé dans CakeResponse::$_mimeTypes. Vous pouvez ajouter des nouveaux types avant d’appeler CakeResponse::file() en utilisant la méthode CakeResponse::type().

Si vous voulez, vous pouvez aussi forcer un fichier à être téléchargé au lieu d’être affiché dans le navigateur en spécifiant les options:

$this->response->file(
    $file['path'],
    array('download' => true, 'name' => 'foo')
);

Envoyer une chaîne en fichier¶

Vous pouvez répondre avec un fichier qui n’existe pas sur le disque, par exemple si vous voulez générer un pdf ou un ics à la volée et voulez servir la chaîne générée en fichier, vous pouvez faire cela en utilisant:

public function sendIcs() {
    $icsString = $this->Calendar->generateIcs();
    $this->response->body($icsString);
    $this->response->type('ics');

    //Force le téléchargement de fichier en option
    $this->response->download('filename_for_download.ics');

    //Retourne l'object pour éviter au controller d'essayer de rendre
    // une vue
    return $this->response;
}

Définir les en-têtes¶

Le réglage des en-têtes est fait avec la métode CakeResponse::header(). Elle peut être appelée avec quelques paramètres de configurations:

// Régler un unique en-tête
$this->response->header('Location', 'http://example.com');

// Régler plusieurs en-têtes
$this->response->header(array(
    'Location' => 'http://example.com',
    'X-Extra' => 'My header'
));
$this->response->header(array(
    'WWW-Authenticate: Negotiate',
    'Content-type: application/pdf'
));

Régler le même header() de multiples fois entraînera l’écrasement des précédentes valeurs, un peu comme les appels réguliers d’en-tête. Les en-têtes ne sont aussi pas envoyés quand CakeResponse::header() est appelée; à la place, ils sont simplement conservés jusqu’à ce que la réponse soit effectivement envoyée.

Vous pouvez maintenant utiliser la méthode pratique CakeResponse::location() pour directement définir ou récupérer l’en-tête de localisation du redirect.

Interagir avec le cache du navigateur¶

Vous avez parfois besoin de forcer les navigateurs à ne pas mettre en cache les résultats de l’action d’un controller. CakeResponse::disableCache() est justement prévu pour cela:

public function index() {
    // faire quelque chose.
    $this->response->disableCache();
}

Vous pouvez aussi dire aux clients que vous voulez qu’ils mettent en cache des réponses. En utilisant CakeResponse::cache():

public function index() {
    //faire quelque chose
    $this->response->cache('-1 minute', '+5 days');
}

Ce qui est au-dessus dira aux clients de mettre en cache la réponse résultante pendant 5 jours, en espérant accélérer l’expérience de vos visiteurs. CakeResponse::cache() définit valeur Last-Modified en premier argument. Expires, et max-age sont définis en se basant sur le second paramètre. Le Cache-Control est défini aussi à public.

Réglage fin du Cache HTTP¶

Une des façons les meilleures et les plus simples de rendre votre application plus rapide est d’utiliser le cache HTTP. Avec la mise en cache des models, vous n’avez qu’à aider les clients à décider si ils doivent utiliser une copie mise en cache de la réponse en configurant un peu les en-têtes comme les temps modifiés, les balises d’entité de réponse et autres.

Opposé à l’idée d’avoir à coder la logique de mise en cache et de sa nullité (rafraîchissement) une fois que les données ont changé, HTPP utilise deux models, l’expiration et la validation qui habituellement sont beaucoup plus simples que d’avoir à gérer le cache soi-même.

En dehors de l’utilisation de CakeResponse::cache() vous pouvez aussi utiliser plusieurs autres méthodes pour affiner le réglage des en-têtes de cache HTTP pour tirer profit du navigateur ou à l’inverse du cache du proxy.

Cache-Control: private, max-age=3600, must-revalidate

public function view() {
    ...
    // Défini le Cache-Control en public pour 3600 secondes
    $this->response->sharable(true, 3600);
}

public function mes_donnees() {
    ...
    // Défini le Cache-Control en private pour 3600 secondes
    $this->response->sharable(false, 3600);
}

public function view() {
    $this->response->expires('+5 days');
}

public function index() {
    $articles = $this->Article->find('all');
    $this->response->etag($this->Article->generateHash($articles));
    if ($this->response->checkNotModified($this->request)) {
        return $this->response;
    }
    ...
}

public function view() {
    $article = $this->Article->find('first');
    $this->response->modified($article['Article']['modified']);
    if ($this->response->checkNotModified($this->request)) {
        return $this->response;
    }
    ...
}

$this->response->vary('User-Agent');
$this->response->vary('Accept-Encoding', 'User-Agent');
$this->response->vary('Accept-Language');

CakeResponse et les tests¶

Probablement l’une des plus grandes victoires de CakeResponse vient de comment il facilite les tests des controllers et des components. Au lieu d’avoir des méthodes répandues à travers plusieurs objets, vous avez un seul objet pour mocker pendant que les controllers et les components délèguent à CakeResponse. Cela vous aide à rester plus près d’un test unitaire et facilite les tests des controllers:

public function testSomething() {
    $this->controller->response = $this->getMock('CakeResponse');
    $this->controller->response->expects($this->once())->method('header');
    // ...
}

De plus, vous pouvez faciliter encore plus l’exécution des tests à partir d’une ligne de commande, pendant que vous pouvez mocker pour éviter les erreurs “d’envois d’en-têtes” qui peuvent arriver en essayant de configurer les en-têtes dans CLI.

API de CakeResponse¶

class CakeResponse¶

CakeResponse fournit un nombre de méthodes utiles pour interagir avec la réponse que vous envoyez à un client.

CakeResponse::header($header = null, $value = null)¶

Vous permet de configurer directement un ou plusieurs en-têtes à envoyer avec la réponse.

CakeResponse::location($url = null)¶

Vous permet de définir directement l’en-tête de localisation du redirect à envoyer avec la réponse:

// Définit la localisation du redirect
$this->response->location('http://example.com');

// Récupère l'en-tête de localisation du redirect actuel
$location = $this->response->location();

Nouveau dans la version 2.4.

CakeResponse::charset($charset = null)¶

Configure le charset qui sera utilisé dans la réponse.

CakeResponse::type($contentType = null)¶

Configure le type de contenu pour la réponse. Vous pouvez soit utiliser un alias de type de contenu connu, soit le nom du type de contenu complet.

CakeResponse::cache($since, $time = '+1 day')¶

Vous permet de configurer les en-têtes de mise en cache dans la réponse.

CakeResponse::disableCache()¶

Configure les en-têtes pour désactiver la mise en cache des clients pour la réponse.

CakeResponse::sharable($public = null, $time = null)¶

Configure l’en-tête Cache-Control pour être soit public soit private et configure optionnellement une directive de la ressource à un max-age.

Nouveau dans la version 2.1.

CakeResponse::expires($time = null)¶

Permet de configurer l’en-tête Expires à une date spécifique.

Nouveau dans la version 2.1.

CakeResponse::etag($tag = null, $weak = false)¶

Configure l’en-tête Etag pour identifier de manière unique une ressource de réponse.

Nouveau dans la version 2.1.

CakeResponse::modified($time = null)¶

Configure l’en-tête Last-modified à une date et un temps donné dans le format correct.

Nouveau dans la version 2.1.

CakeResponse::checkNotModified(CakeRequest $request)¶

Compare les en-têtes mis en cache pour l’objet request avec l’en-tête mis en cache de la réponse et détermine si il peut toujours être considéré comme récent. Dans ce cas, il supprime tout contenu de réponse et envoie l’en-tête 304 Not Modified.

Nouveau dans la version 2.1.

CakeResponse::compress()¶

Démarre la compression gzip pour la requête.

CakeResponse::download($filename)¶

Vous permet d’envoyer la réponse en pièce jointe et de configurer le nom de fichier.

CakeResponse::statusCode($code = null)¶

Vous permet de configurer le code de statut pour la réponse.

CakeResponse::body($content = null)¶

Configurer le contenu du body pour la réponse.

CakeResponse::send()¶

Une fois que vous avez fini de créer une réponse, appeler send() enverra tous les en-têtes configurés ainsi que le body. Ceci est fait automatiquement à la fin de chaque requête par Dispatcher.

CakeResponse::file($path, $options = array())¶

Vous permet de définir un fichier pour l’affichage ou le téléchargement.

Nouveau dans la version 2.3.