Middleware¶

Les Middlewares dans CakePHP¶

CakePHP fournit nativement plusieurs middlewares pour gérer des cas classiques d’une application web :

• Cake\Error\Middleware\ErrorHandlerMiddleware capture les exceptions à partir du middleware encapsulé et affiche un page d’erreur en utilisant le gestionnaire d’exception Gestion des Erreurs & Exceptions.

• Cake\Routing\AssetMiddleware verifie si la requête fait référence à un thème ou à un fichier ressource d’un plugin, tel que un fichier CSS, JavaScript ou image enregistré soit dans le dossier racine du plugin ou celui correspondant, pour un thème.

• Cake\Routing\Middleware\RoutingMiddleware utilise le Router pour analyser l’URL entrante et assigner les paramètres de routing à la requête.

• Cake\I18n\Middleware\LocaleSelectorMiddleware active le changement automatique de langage à partir de l’en-tête Accept-Language envoyé par le navigateur

• Cake\Http\Middleware\SecurityHeadersMiddleware facilite l’ajout de header liés à la sécurité comme X-Frame-Options aux réponses.

• Cake\Http\Middleware\EncryptedCookieMiddleware vous permet de manipuler des cookies chiffrés dans le cas où vous auriez besoin de manipuler des cookies avec des données obfusqués.

• Cake\Http\Middleware\CsrfProtectionMiddleware ajoute une protection CSRF à votre application.

Utilisation des Middleware¶

Les middlewares peuvent être appliqués de manière globale à votre application ou un scope de routing.

Pour appliquer un middleware à toutes les requêtes, utilisez la méthode middleware de la classe App\Application. Si la classe App\Application n’existe pas, reportez-vous à la section Ajout de la nouvelle pile HTTP à une application existante pour plus d’informations. La méthode d’attache middleware de votre application sera appelée très tôt dans le processus de requête, vous pouvez utiliser les objets MiddlewareQueue pour en attacher

namespace App;

use Cake\Http\BaseApplication;
use Cake\Error\Middleware\ErrorHandlerMiddleware;

class Application extends BaseApplication
{
    public function middleware($middlewareQueue)
    {
        // Attache le gestionnaire d'erreur dans la file du middleware
        $middlewareQueue->add(new ErrorHandlerMiddleware());
        return $middlewareQueue;
    }
}

En plus d’ajouter à la fin de la MiddlewareQueue vous pouvez effectuer différentes opérations

$layer = new \App\Middleware\CustomMiddleware;

// Le middleware sera ajouté à la fin de la file.
$middlewareQueue->add($layer);

// Le middleware sera ajouté au début de la file
$middlewareQueue->prepend($layer);

// Insère dans une place spécifique. Si cette dernière est
// hors des limites, il sera ajouté à la fin.
$middlewareQueue->insertAt(2, $layer);

// Insère avant un autre middleware.
// Si la classe nommée ne peut pas être trouvée,
// une exception sera renvoyée.
$middlewareQueue->insertBefore(
    'Cake\Error\Middleware\ErrorHandlerMiddleware',
    $layer
);

// Insère après un autre middleware.
// Si la classe nommée ne peut pas être trouvée,
// le middleware sera ajouté à la fin.
$middlewareQueue->insertAfter(
    'Cake\Error\Middleware\ErrorHandlerMiddleware',
    $layer
);

En plus d’appliquer des middleware à la totalité de votre application, vous pouvez appliquer des middleware à des jeux de routes spécifiques en utilisant les middlewares connectés à un scope.

// Dans le bootstrap.php du plugin ContactManager
use Cake\Event\EventManager;

EventManager::instance()->on(
    'Server.buildMiddleware',
    function ($event, $middlewareQueue) {
        $middlewareQueue->add(new ContactPluginMiddleware());
    });

Requêtes et Réponses PSR-7¶

Les Middleware et la nouvelle pile HTTP sont construits sur les Interfaces de Requête et Réponse PSR-7. Alors que les middleware sont exposés à ces interfaces, vos controlleurs, composants, et vues ne le seront pas.

// Lire l'en-tête en tant que texte
$value = $request->getHeaderLine('Content-Type');

// Lire l'en-tête en tant que tableau
$value = $request->getHeader('Content-Type');

// Lire l'ensemble des en-têtes en tant que tableau associatif.
$headers = $request->getHeaders();

// Récupérer un tableau des valeurs des cookies.
$cookies = $request->getCookieParams();

// Récupérer une liste des objets UploadedFile.
$files = $request->getUploadedFiles();

// Lire les données du fichier.
$files[0]->getStream();
$files[0]->getSize();
$files[0]->getClientFileName();

// Déplacer le fichier.
$files[0]->moveTo($targetPath);

// Récupérer l'URI
$uri = $request->getUri();

// Lire les données de l'URI.
$path = $uri->getPath();
$query = $uri->getQuery();
$host = $uri->getHost();

// Ceci *ne modifie pas* $response. Le nouvel objet n'a pas été
// assigné à une variable.
$response->withHeader('Content-Type', 'application/json');

// Utilisation correcte :
$newResponse = $response->withHeader('Content-Type', 'application/json');

// Assigne les en-têtes et un status code
$response = $response->withHeader('Content-Type', 'application/json')
    ->withHeader('Pragma', 'no-cache')
    ->withStatus(422);

// Modifier le corps
$body = $response->getBody();
$body->write(json_encode(['errno' => $errorCode]));

Créer un Middleware¶

Un Middleware peut soit être implémenté en tant que fonctions anonymes (Closures), soit en tant que classes appelables. Tandis que les Closures sont adaptées pour les petites tâches elles rendent les tests plus complexes, et peuvent créer une classe Application complexe. Les classes Middleware dans CakePhp ont quelques conventions :

• Les fichiers de classe Middleware doivent être placés dans src/Middleware. Par exemple : src/Middleware/CorsMiddleware.php

• Les classes Middleware doivent avoir Middleware en suffixe. Par exemple : LinkMiddleware.

• Les Middleware requièrent l’implémentation du protocole middleware.

Bien que pas (encore) une interface formelle, Middleware a une soft-interface ou “protocole”. Ce dernier est tel que :

1. Middleware doit implémenter __invoke($request, $response, $next).

2. Middleware doit rendre un objet implémentant la ResponseInterface PSR-7.

Middleware peut rendre une réponse soit en appelant $next ou en créant sa propre réponse. Nous pouvons observer les deux options dans ce middleware

// Dans src/Middleware/TrackingCookieMiddleware.php
namespace App\Middleware;

class TrackingCookieMiddleware
{
    public function __invoke($request, $response, $next)
    {
        // Appeler $next() délégue le controle au middleware *suivant*
        // dans la file de l'application.
        $response = $next($request, $response);

        // Lors d'une modification de la réponse, vous devriez le faire
        // *après* avoir appeler next.
        if (!$request->getCookie('landing_page')) {
            $response->cookie([
                'name' => 'landing_page',
                'value' => $request->here(),
                'expire' => '+ 1 year',
            ]);
        }
        return $response;
    }
}

Après avoir créer le middleware, attachez-le à votre application

// Dans src/Application.php
namespace App;

use App\Middleware\TrackingCookieMiddleware;

class Application
{
    public function middleware($middlewareQueue)
    {
        // Ajoutez votre middleware dans la file
        $middlewareQueue->add(new TrackingCookieMiddleware());

        // Ajoutez d'autres middleware dans la file

        return $middlewareQueue;
    }
}

Ajouter des Headers de Sécurité¶

La couche SecurityHeaderMiddleware facilite l’ajout de headers liés à la sécurité à votre application. Une fois configuré, le middleware peut ajouter les headers suivants aux réponses :

• X-Content-Type-Options

• X-Download-Options

• X-Frame-Options

• X-Permitted-Cross-Domain-Policies

• Referrer-Policy

Ce middleware peut être configuré en utilisant l’interface fluide avant d’être appliqué au stack de middlewares:

use Cake\Http\Middleware\SecurityHeadersMiddleware;

$headers = new SecurityHeadersMiddleware();
$headers
    ->setCrossDomainPolicy()
    ->setReferrerPolicy()
    ->setXFrameOptions()
    ->setXssProtection()
    ->noOpen()
    ->noSniff();

$middlewareQueue->add($headers);

Middleware de Gestion de Cookies Chiffrés¶

Si votre application utilise des cookies qui contiennent des données que vous avez besoin d’obfusquer pour vous protéger contre les modifications utilisateurs, vous pouvez utiliser le middleware de gestion des cookies chiffrés de CakePHP pour chiffrer et déchiffrer les données des cookies. Les données des cookies sont chiffrées via OpenSSL, en AES:

use Cake\Http\Middleware\EncryptedCookieMiddleware;

$cookies = new EncryptedCookieMiddleware(
    // Noms des cookies à protéger
    ['secrets', 'protected'],
    Configure::read('Security.cookieKey')
);

$middlewareQueue->add($cookies);

L’algorithme de chiffrement et le “padding style” utilisé par le middleware sont compatible avec le CookieComponent des versions précédents de CakePHP.

Middleware Cross Site Request Forgery (CSRF)¶

La protection CSRF peut être appliqué à votre application complète ou à des “scopes” spécifiques en applicant le CsrfProtectionMiddleware à votre stack de middlewares:

use Cake\Http\Middleware\CsrfProtectionMiddleware;

$options = [
    // ...
];
$csrf = new CsrfProtectionMiddleware($options);

$middlewareQueue->add($csrf);

Des options peuvent être passées au constructor du middleware. Les options utilisables sont :

• cookieName Le nom du cookie à envoyer. Défaut à csrfToken.

• expiry La durée de vie du token CSRF. Défaut à la durée de vie du navigateur.

• secure Si le cookie doit avoir le flag “Secure” ou pas. C’est-à-dire si le cookie sera seulement disponible sur une connexion HTTPS et que toute tentative d’accès via une requête HTTP « normale » échouera. Défaut à false.

• field Le champ du formulaire à vérifier. Défaut à _csrfToken. Changer cete valeur vous obligera également à configurer le FormHelper.

Une fois activé, vous pouvez accéder au token CSRF actuel via l’objet « Request »:

$token = $this->request->getParam('_csrfToken');

Ajout de la nouvelle pile HTTP à une application existante¶

Utiliser les Middleware HTTP dans une application existante nécessite quelques modification dans celle-ci.

1. Premièrement, mettez à jour votre webroot/index.php. Copiez le contenu du fichier depuis le squelette d’application.

2. Puis, créez une classe Application`. Reportez-vous à la section précédente Utilisation des Middleware pour plus de précisions. Ou copiez l’exemple dans le squelette d’application.

Lorsque ces deux étapes sont complétées, vous êtes prêts à réimplémenter tous les dispatch filters de votre application/plugins en tant que middleware HTTP.

Si vous exécutez des tests, vous aurez aussi besoin de mettre à jour tests/bootstrap.php en copiant le contenu du fichier depuis le squelette d’application.