Source de données : SQS

1Présentation

Amazon SQS (Simple Queue Service) est une file de messages qui sert à enregistrer des ordres de traitement d'un côté, et de l'autre côté de récupérer ces ordres pour les traiter.

Si vous avez correctement configuré les paramètres de connexion à SQS, Temma crée automatiquement un objet de type \Temma\Datasources\Sqs. Par convention, nous partirons du principe que vous avez nommé cette connexion sqs dans le fichier etc/temma.php (voir la documentation de la configuration).

La connexion est alors disponible dans le contrôleur en écrivant : 

$this->sqs

Dans les autres objets gérés par le composant d'injection de dépendances, la connexion à SQS est accessible en écrivant : 

$loader->dataSources['sqs']

2Installation

Pour pouvoir se connecter à AWS (Amazon Web Services), Temma a besoin d'accéder au SDK AWS PHP. Cela peut se faire en l'installant avec Composer, ou en l'installant manuellement.

2.1Installation avec Composer

Pour installer le SDK AWS PHP avec Composer, il suffit de taper cette commande depuis la racine du projet : 

$ composer require aws/aws-sdk-php

2.2Installation manuelle

Pour installer le SDK AWS PHP manuellement, il faut télécharger le fichier aws.phar et le placer dans le répertoire lib/ du projet. Par exemple en exécutant la commande suivante : 

$ wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

Vous pouvez choisir d'installer le SDK AWS PHP au niveau du système entier, pour ne pas avoir à le réinstaller dans chaque projet. Pour cela, vous n'avez qu'à copier le fichier aws.phar dans un répertoire qui fait partie des chemins d'inclusion, comme par exemple /usr/share/php (au lieu de le mettre dans le répertoire lib/ de votre projet).

3Configuration

Dans le fichier etc/temma.php (voir la documentation de la configuration), vous déclarez le DSN (Data Source Name) qui permet de se connecter à SQS.

Le DSN permettant de se connecter à SQS s'écrit de la forme : sqs://CLÉ_ACCÈS:CLÉ_PRIVÉE@QUEUE_URL
La clé d'accès et la clé privée sont fournis par AWS.
QUEUE_URL correspond à l'URL de la file de messages, sans le préfixe "https://".
Exemple : sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name

4Spécificités des files de messages

Contrairement aux autres sources de données, l'ajout de messages dans une file de message se fait sans fournir d'identifiant (nom, clé, chemin…). L'identifiant est créé automatiquement par SQS. Lorsqu'un message est lu, son identifiant est retourné en même temps que ses données ; cet identifiant est utile par la suite pour effacer le message de la file.

En conséquence, SQS ne permet pas de vérifier l'existence d'un message à partir de son identifiant, ni de sélectionner un message, ni de définir une valeur par défaut lors de la récupération d'un message.

5Appels unifiés

5.1Accès de type tableau

// écriture d'un message (sérialisé)
$this->sqs[''] = $data;

// lecture d'un message (désérialisé)
$msg = $this->sqs[''];
// retourne un tableau associatif avec les clés "id" et "data"

// effacement d'un message
unset($this->sqs[$msg['id']]);

// nombre de messages en attente
$nbr = count($this->sqs);

5.2Méthodes générales

// effacement d'un message
$this->sqs->remove($msg['id']);

// effacement de tous les messages
$this->sqs->flush();

5.3Gestion de données complexes sérialisées

// lecture d'un message (désérialisé)
$msg = $this->sqs->get('');
// retourne un tableau associatif avec les clés "id" et "data"

// écriture d'un message (sérialisé)
$this->sqs->set('', $msgData);

// écriture de plusieurs messages (sérialisés)
$this->sqs->mSet([
    $user1data,
    $user2data,
    $user3data,
]);

5.4Gestion de données brutes

// lecture de données (brutes)
$html = $this->sqs->read('');
// retourne un tableau associatif avec les clés "id" et "data"

// écriture d'un message (brut)
$this->sqs->write('', $msgData);

// écriture de plusieurs messages (bruts)
$this->sqs->mWrite({
    $user1data,
    $user2data,
    $user3data,
]);

// écriture d'une message (brut) à partir d'un fichier local
$this->sqs->copyTo('', '/path/to/file');

// écriture de plusieurs données (brutes) à partir de fichiers locaux
$this->sqs->mCopyTo([
    '/path/to/file1',
    '/path/to/file2',
    '/path/to/file3',
]);