Gestionnaires et intergiciels dans la version 3 AWS SDK for PHP

Le principal mécanisme d'extension passe par les AWS SDK for PHP gestionnaires et les intergiciels. Chaque classe de SDK client possède une Aws\HandlerList instance accessible via la getHandlerList() méthode d'un client. Vous pouvez récupérer la HandlerList d'un client et la modifier afin d'ajouter ou de supprimer un comportement client.

Gestionnaires

Un gestionnaire est une fonction qui transforme une commande et une requête en un résultat. Un gestionnaire envoie généralement des HTTP demandes. Les gestionnaires peuvent comporter des intergiciels, qui renforcent leur comportement. Un gestionnaire est une fonction qui accepte un Aws\CommandInterface et un Psr\Http\Message\RequestInterface, et renvoie une promesse exécutée avec un Aws\ResultInterface ou rejetée avec une raison Aws\Exception\AwsException.

Voici un gestionnaire qui renvoie le même résultat fictif pour chaque appel.

use Aws\CommandInterface;
use Aws\Result;
use Psr\Http\Message\RequestInterface;
use GuzzleHttp\Promise;

$myHandler = function (CommandInterface $cmd, RequestInterface $request) {
    $result = new Result(['foo' => 'bar']);
    return Promise\promise_for($result);
};

Vous pouvez ensuite utiliser ce gestionnaire avec un SDK client en fournissant une handler option dans le constructeur d'un client.

// Set the handler of the client in the constructor
$s3 = new Aws\S3\S3Client([
    'region'  => 'us-east-1',
    'version' => '2006-03-01',
    'handler' => $myHandler
]);

Vous pouvez également modifier le gestionnaire existant d'un client à l'aide de la méthode setHandler de Aws\ClientInterface.

// Set the handler of the client after it is constructed
$s3->getHandlerList()->setHandler($myHandler);

$multiRegionClient->useCustomHandler($myHandler);

Gestionnaire fictif

Nous vous recommandons d'utiliser le MockHandler lorsque vous rédigez des tests utilisant leSDK. Aws\MockHandler vous permet de renvoyer des résultats fictifs ou de lancer des exceptions de simulation. Vous mettez en file d'attente les résultats ou les exceptions, puis vous les MockHandler replacez dans l'ordre. FIFO

use Aws\Result;
use Aws\MockHandler;
use Aws\DynamoDb\DynamoDbClient;
use Aws\CommandInterface;
use Psr\Http\Message\RequestInterface;
use Aws\Exception\AwsException;

$mock = new MockHandler();

// Return a mocked result
$mock->append(new Result(['foo' => 'bar']));

// You can provide a function to invoke; here we throw a mock exception
$mock->append(function (CommandInterface $cmd, RequestInterface $req) {
    return new AwsException('Mock exception', $cmd);
});

// Create a client with the mock handler
$client = new DynamoDbClient([
    'region'  => 'us-west-2',
    'version' => 'latest',
    'handler' => $mock
]);

// Result object response will contain ['foo' => 'bar']
$result = $client->listTables();

// This will throw the exception that was enqueued
$client->listTables();

Intergiciel

Un intergiciel est un type spécial de fonction de haut niveau qui augmente le comportement de transfert d'une commande et délègue la tâche à un gestionnaire « suivant ». Les fonctions d'intergiciel acceptent un Aws\CommandInterface et un Psr\Http\Message\RequestInterface, et renvoient une promesse exécutée avec un Aws\ResultInterface ou rejetée avec une raison Aws\Exception\AwsException.

Un intergiciel est une fonction supérieure qui modifie les commandes, les requêtes ou les résultats qu'il traite. Un intergiciel se présente sous la forme suivante.

use Aws\CommandInterface;
use Psr\Http\Message\RequestInterface;

$middleware = function () {
    return function (callable $handler) use ($fn) {
        return function (
            CommandInterface $command,
            RequestInterface $request = null
        ) use ($handler, $fn) {
            // Do something before calling the next handler
            // ...
            $promise = $fn($command, $request);
            // Do something in the promise after calling the next handler
            // ...
            return $promise;
        };
    };
};

Un intergiciel reçoit une commande à exécuter et un objet de requête facultatif. Il peut choisir d'augmenter la requête et la commande ou de les laisser en l'état. Un intergiciel appelle le gestionnaire suivant de la chaîne ou choisit de le court-circuiter et de renvoyer une promesse. La promesse ainsi créée en appelant le gestionnaire suivant peut alors être augmentée à l'aide de la méthode then de la promesse afin de modifier le résultat ou l'erreur avant le renvoi de la promesse à la pile d'intergiciels.

HandlerList

Il SDK utilise un Aws\HandlerList pour gérer le middleware et les gestionnaires utilisés lors de l'exécution d'une commande. Chaque SDK client possède unHandlerList, qui HandlerList est cloné et ajouté à chaque commande créée par un client. Vous pouvez attacher un intergiciel et un gestionnaire par défaut à utiliser pour chaque commande créée par un client en ajoutant un intergiciel à la HandlerList du client. Vous pouvez ajouter et supprimer des intergiciels de certaines commandes spécifiques en modifiant la HandlerList appartenant à une commande spécifique.

HandlerList représente une pile d’intergiciels utilisés pour encapsuler un gestionnaire. Pour vous aider à gérer la liste d'intergiciels et l'ordre dans lequel ils encapsulent un gestionnaire, HandlerList divise la pile d'intergiciels en plusieurs étapes nommées qui représentent une partie du cycle de vie du transfert d'une commande :

Intergiciels disponibles

SDKIl fournit plusieurs intergiciels que vous pouvez utiliser pour améliorer le comportement d'un client ou pour observer l'exécution d'une commande.

mapCommand

Le Aws\Middleware::mapCommand middleware est utile lorsque vous devez modifier une commande avant que celle-ci ne soit sérialisée en tant que demande. HTTP Par exemple, vous pouvez utiliser mapCommand pour effectuer une validation ou pour ajouter des paramètres par défaut. La fonction mapCommand accepte une fonction de type callable, qui accepte un objet Aws\CommandInterface et renvoie un objet Aws\CommandInterface.

use Aws\Middleware;
use Aws\CommandInterface;

// Here we've omitted the require Bucket parameter. We'll add it in the
// custom middleware.
$command = $s3Client->getCommand('HeadObject', ['Key' => 'test']);

// Apply a custom middleware named "add-param" to the "init" lifecycle step
$command->getHandlerList()->appendInit(
    Middleware::mapCommand(function (CommandInterface $command) {
        $command['Bucket'] = 'amzn-s3-demo-bucket';
        // Be sure to return the command!
        return $command;
    }),
    'add-param'
);

mapRequest

L'intergiciel Aws\Middleware::mapRequest vous permet de modifier une requête après sa sérialisation, mais avant son envoi. Par exemple, cela peut être utilisé pour ajouter des HTTP en-têtes personnalisés à une demande. La fonction mapRequest accepte une fonction de type callable, qui accepte un argument Psr\Http\Message\RequestInterface et renvoie un objet Psr\Http\Message\RequestInterface.

use Aws\Middleware;
use Psr\Http\Message\RequestInterface;

// Create a command so that we can access the handler list
$command = $s3Client->getCommand('HeadObject', [
    'Key'    => 'test',
    'Bucket' => 'amzn-s3-demo-bucket'
]);

// Apply a custom middleware named "add-header" to the "build" lifecycle step
$command->getHandlerList()->appendBuild(
    Middleware::mapRequest(function (RequestInterface $request) {
        // Return a new request with the added header
        return $request->withHeader('X-Foo-Baz', 'Bar');
    }),
    'add-header'
);

Désormais, lorsque la commande est exécutée, elle est envoyée avec l'en-tête personnalisé.

mapResult

L'intergiciel Aws\Middleware::mapResult permet de modifier le résultat de l'exécution d'une commande. La fonction mapResult accepte une fonction de type callable, qui accepte un argument Aws\ResultInterface et renvoie un objet Aws\ResultInterface.

use Aws\Middleware;
use Aws\ResultInterface;

$command = $s3Client->getCommand('HeadObject', [
    'Key'    => 'test',
    'Bucket' => 'amzn-s3-demo-bucket'
]);

$command->getHandlerList()->appendSign(
    Middleware::mapResult(function (ResultInterface $result) {
        // Add a custom value to the result
        $result['foo'] = 'bar';
        return $result;
    })
);

Désormais, lorsque la commande est exécutée, le résultat renvoyé contient un attribut foo.

historique

Le history middleware est utile pour vérifier qu'il a SDK exécuté les commandes que vous attendiez, envoyé les HTTP demandes que vous attendiez et reçu les résultats escomptés. Globalement, il agit de manière similaire à l'historique d'un navigateur web.

use Aws\History;
use Aws\Middleware;

$ddb = new Aws\DynamoDb\DynamoDbClient([
    'version' => 'latest',
    'region'  => 'us-west-2'
]);

// Create a history container to store the history data
$history = new History();

// Add the history middleware that uses the history container
$ddb->getHandlerList()->appendSign(Middleware::history($history));

Un conteneur d'historique Aws\History stocke 10 entrées par défaut avant de purger ses entrées. Vous pouvez personnaliser le nombre d'entrées en indiquant combien le constructeur peut en recevoir.

// Create a history container that stores 20 entries
$history = new History(20);

Vous pouvez inspecter le conteneur d'historique après l'exécution de requêtes traitées par l'intergiciel d'historique.

// The object is countable, returning the number of entries in the container
count($history);

// The object is iterable, yielding each entry in the container
foreach ($history as $entry) {
    // You can access the command that was executed
    var_dump($entry['command']);
    // The request that was serialized and sent
    var_dump($entry['request']);
    // The result that was received (if successful)
    var_dump($entry['result']);
    // The exception that was received (if a failure occurred)
    var_dump($entry['exception']);
}

// You can get the last Aws\CommandInterface that was executed. This method
// will throw an exception if no commands have been executed.
$command = $history->getLastCommand();

// You can get the last request that was serialized. This method will throw an exception
// if no requests have been serialized.
$request = $history->getLastRequest();

// You can get the last return value (an Aws\ResultInterface or Exception).
// The method will throw an exception if no value has been returned for the last
// executed operation (e.g., an async request has not completed).
$result = $history->getLastReturn();

// You can clear out the entries using clear
$history->clear();

tap

L'intergiciel tap fonctionne comme un observateur. Vous pouvez l'utiliser pour appeler des fonctions lors de l'envoi de commandes via la chaîne d'intergiciels. La fonction tap accepte une fonction de type callable qui accepte Aws\CommandInterface et une option Psr\Http\Message\RequestInterface en cours d'exécution (facultatif).

use Aws\Middleware;

$s3 = new Aws\S3\S3Client([
    'region'  => 'us-east-1',
    'version' => '2006-03-01'
]);

$handlerList = $s3->getHandlerList();

// Create a tap middleware that observes the command at a specific step
$handlerList->appendInit(
    Middleware::tap(function (CommandInterface $cmd, RequestInterface $req = null) {
        echo 'About to send: ' . $cmd->getName() . "\n";
        if ($req) {
            echo 'HTTP method: ' . $request->getMethod() . "\n";
        }
    }
);

Création de gestionnaires personnalisés

Un gestionnaire est une fonction qui accepte des objets Aws\CommandInterface et Psr\Http\Message\RequestInterface, et renvoie une promesse GuzzleHttp\Promise\PromiseInterface exécutée avec Aws\ResultInterface ou rejetée avec Aws\Exception\AwsException.

Bien qu'SDKil dispose de plusieurs @http options, un gestionnaire doit uniquement savoir comment utiliser les options suivantes :

À moins que l'option ne soit spécifiée comme facultative, un gestionnaire MUST peut gérer l'option ou MUST renvoyer une promesse rejetée.

En plus de gérer des @http options spécifiques, un gestionnaire MUST ajoute un User-Agent en-tête qui prend la forme suivante, où « 3.X » peut être remplacé par Aws\Sdk::VERSION et « HandlerSpecificData /version... » doit être remplacé par la chaîne User-Agent spécifique à votre gestionnaire.

User-Agent: aws-sdk-php/3.X HandlerSpecificData/version ...