Handler und Middleware in der Version 3 AWS SDK for PHP

Der Hauptmechanismus für die Erweiterung von AWS SDK for PHP ist der Einsatz von Handlern und Middleware. Jede SDK Clientklasse besitzt eine Aws\HandlerList Instanz, auf die über die getHandlerList() Methode eines Clients zugegriffen werden kann. Sie können die HandlerList eines Clients abrufen und ändern, um Client-Verhaltensweisen hinzuzufügen oder zu entfernen.

Handler

Ein Handler ist eine Funktion, die die eigentliche Transformation eines Befehls und einer Anfrage in ein Ergebnis durchführt. Ein Handler sendet normalerweise HTTP Anfragen. Handler können mit Middleware konstruiert werden, um ihr Verhalten zu verbessern. Ein Handler ist eine Funktion, die eine Aws\CommandInterfaceund einePsr\Http\Message\RequestInterface akzeptiert und ein Promise zurückgibt, das mit einer Aws\ResultInterface erfüllt oder mit einem Aws\Exception\AwsException Grund abgelehnt wird.

Hier ist ein Handler, der für jeden Aufruf das gleiche modellhafte Ergebnis liefert.

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);
};

Sie können diesen Handler dann mit einem SDK Client verwenden, indem Sie eine handler Option im Konstruktor eines Clients angeben.

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

Sie können den Handler eines Clients auch ändern, nachdem er erstellt wurde. Dazu verwenden Sie die setHandler-Methode eines Aws\ClientInterface.

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

$multiRegionClient->useCustomHandler($myHandler);

Handler vortäuschen

Wir empfehlen die Verwendung vonMockHandler, wenn Sie Tests schreiben, die den verwendenSDK. Du kannst den Aws\MockHandler benutzen, um modellhafte Ergebnisse zurückzugeben oder modellhafte Ausnahmen aufzuwerfen. Sie stellen Ergebnisse oder Ausnahmen in die Warteschlange und stellen sie dann der Reihe MockHandler nach aus der Warteschlange. 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();

Middleware

Middleware ist eine spezielle Art von High-Level-Funktion, die das Verhalten bei der Übertragung eines Befehls erweitert und an einen „nächsten“ Handler delegiert. Middleware-Funktionen akzeptieren eine Aws\CommandInterface und eine Psr\Http\Message\RequestInterface und geben ein Promise zurück, das mit einer Aws\ResultInterfaceerfüllt oder mit einem Aws\Exception\AwsException-Grund abgelehnt wird.

Eine Middleware ist eine Funktion höherer Ordnung, die einen Befehl, eine Anforderung oder ein Ergebnis beim Durchlaufen der Middleware ändert. Ein Middleware hat die folgende Form.

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;
        };
    };
};

Eine Middleware erhält einen Befehl zum Ausführen und ein optionales Anfrage-Objekt. Die Middleware kann die Anfrage und den Befehl erweitern oder sie unverändert lassen. Eine Middleware ruft dann das nächste Handle in der Kette auf oder kann den nächsten Handler kurzschließen und ein Promise zurückgeben. Das Promise, das durch den Aufruf des nächsten Handlers erzeugt wird, kann dann mit der Methode then des Promise erweitert werden, um das eventuelle Ergebnis oder den Fehler zu ändern, bevor das Promise zurück auf den Stack der Middleware gesendet wird.

HandlerList

Der SDK verwendet eineAws\HandlerList, um die Middleware und die Handler zu verwalten, die bei der Ausführung eines Befehls verwendet werden. Jeder SDK Client besitzt einenHandlerList, und dieser HandlerList wird geklont und zu jedem Befehl hinzugefügt, den ein Client erstellt. Sie können eine Middleware und einen Standard-Handler für jeden von einem Client erstellten Befehl anfügen, indem Sie eine Middleware zur HandlerList des Clients hinzufügen. Sie können Middleware zu bestimmten Befehlen hinzufügen oder entfernen, indem Sie die HandlerList für einen bestimmten Befehl ändern.

Eine HandlerList stellt einen Stack von Middleware dar, der verwendet wird, um einen Handler zu kapseln. Für die Verwaltung der Liste der Middleware und die Reihenfolge, in der sie einen Handler kapseln, unterteilt die HandlerList den Middleware-Stack in benannte Schritte, die Teil des Lebenszyklus der Übertragung eines Befehls sind:

Verfügbare Middleware

Die SDK stellt mehrere Middleware bereit, die Sie verwenden können, um das Verhalten eines Clients zu verbessern oder die Ausführung eines Befehls zu beobachten.

mapCommand

Die Aws\Middleware::mapCommand Middleware ist nützlich, wenn Sie einen Befehl ändern müssen, bevor der Befehl als Anfrage serialisiert wird. HTTP Beispielsweise kann mapCommand verwendet werden, um eine Validierung durchzuführen oder Standardparameter hinzuzufügen. Die mapCommand-Funktion akzeptiert eine aufrufbare Funktion, die ein Aws\CommandInterface-Objekt entgegennimmt und ein Aws\CommandInterface-Objekt zurückgibt.

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

Die Aws\Middleware::mapRequest Middleware ist nützlich, wenn Sie einen Befehl ändern müssen, nachdem er serialisiert wurde, aber bevor er gesendet wird. Dies kann beispielsweise verwendet werden, um einer Anfrage benutzerdefinierte HTTP Header hinzuzufügen. Die mapRequest-Funktion akzeptiert eine aufrufbare Funktion, die ein Psr\Http\Message\RequestInterface-Argument entgegennimmt und ein Psr\Http\Message\RequestInterface-Objekt zurückgibt.

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'
);

Wenn der Befehl ausgeführt wird, wird er mit dem benutzerdefinierten Header gesendet.

mapResult

Die Aws\Middleware::mapResult Middleware ist nützlich, wenn Sie das Ergebnis einer Befehlsausführung ändern müssen. Die mapResult-Funktion akzeptiert eine aufrufbare Funktion, die ein Aws\ResultInterface-Argument entgegennimmt und ein Aws\ResultInterface-Objekt zurückgibt.

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;
    })
);

Wenn der Befehl ausgeführt wird, enthält das zurückgegebene Ergebnis ein foo-Attribut.

history

Die history Middleware ist nützlich, um zu testen, SDK ob sie die erwarteten Befehle ausgeführt, die erwarteten HTTP Anfragen gesendet und die erwarteten Ergebnisse erhalten hat. Es ist im Wesentlichen eine Middleware, die sich ähnlich verhält wie der Verlauf eines Web-Browsers.

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));

Ein Aws\History-Verlaufscontainer speichert standardmäßig 10 Einträge, bevor er Einträge löscht. Sie können die Anzahl der Einträge anpassen, indem Sie die Anzahl der beizubehaltenden Einträge an den Konstruktor übergeben.

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

Sie können den Verlaufscontainer nach der Ausführung von Anforderungen, die die Verlaufs-Middleware durchlaufen, überprüfen.

// 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

Die tap Middleware wird als Beobachter verwendet. Sie können diese Middleware verwenden, um Funktionen aufzurufen, wenn Sie Befehle durch die Middleware-Kette senden. Die tap Funktion akzeptiert eine aufrufbare Funktion, die die Aws\CommandInterface entgegennimmt, ebenso wie eine optionale Psr\Http\Message\RequestInterface, die gerade ausgeführt wird.

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";
        }
    }
);

Benutzerdefinierte Handler erstellen

Ein Handler ist einfach eine Funktion, die ein Aws\CommandInterface-Objekt und ein Psr\Http\Message\RequestInterface-Objekt entgegennimmt und eine GuzzleHttp\Promise\PromiseInterface zurückgibt, die mit einer Aws\ResultInterface erfüllt oder mit einer Aws\Exception\AwsException abgelehnt wird.

Obwohl der mehrere @http Optionen SDK hat, muss ein Handler nur wissen, wie man die folgenden Optionen verwendet:

Sofern die Option nicht als optional angegeben ist, MUST kann ein Handler die Option verarbeiten oder sie gibt ein abgelehntes Versprechen zurück. MUST

Zusätzlich zur Behandlung bestimmter @http Optionen fügt ein Handler einen User-Agent Header MUST hinzu, der die folgende Form hat, wobei „3.X“ durch ersetzt werden kann Aws\Sdk::VERSION und „HandlerSpecificData/version...“ durch Ihre handlerspezifische User-Agent-Zeichenfolge ersetzt werden sollte.

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