Presentation

Amazon SQS (Simple Queue Service) is a message queue used to record processing orders on one side, and to retrieve these orders for processing on the other.

If you have correctly configured the SQS connection parameters, Temma automatically creates an object of type \Temma\Datasources\Sqs. By convention, we'll assume that you've named this connection sqs in the temma.json file (see configuration documentation).

The connection is then available in the controller by writing:

$this->sqs

In other objects managed by the dependency injection component, the SQS connection is accessible by writing:

$loader->dataSources['sqs']

Installation

To connect to AWS (Amazon Web Services), Temma requires the aws.phar file to be downloaded and placed in the project's lib/ directory.

This file is available at: https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

It can be copied with the following command:
wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

Configuration

In the temma.json file (see configuration documentation), you declare the DSN (Data Source Name) used to connect to SQS.

The DSN used to connect to SQS is written as: sqs://ACCESS_KEY:PRIVATE_KEY@QUEUE_URL
The access key and private key are supplied by AWS.
QUEUE_URL corresponds to the URL of the message queue, without the "https://" prefix.
Example: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name

Specific features of message queues

Unlike other data sources, messages are added to a message queue without providing an identifier (name, key, path, etc.). The identifier is created automatically by SQS. When a message is read, its identifier is returned along with its data; this identifier is subsequently used to delete the message from the queue.

Consequently, SQS does not allow you to check the existence of a message based on its identifier, nor to select a message, nor to define a default value when retrieving a message.

Array-type access

// write a message (serialized)
$this->sqs[''] = $data;

// read a message (deserialized)
$msg = $this->sqs[''];
// returns an associative array with the "id" and "data" keys

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

// waiting messages count
$nbr = count($this->sqs);

General methods

// delete a message
$this->sqs->remove($msg['id']);

// delete all messages
$this->sqs->flush();

Management of complex serialized data

// read a message (deserialized)
$msg = $this->sqs->get('');
// returns an associative array with the "id" and "data" keys

// write a message (serialized)
$this->sqs->set('', $msgData);

// write multiple messages (serialized)
$this->sqs->mSet([
    $user1data,
    $user2data,
    $user3data,
]);

Raw data management

// read a message (raw)
$html = $this->sqs->read('');
// returns an associative array with the "id" and "data" keys

// write a message (raw)
$this->sqs->write('', $msgData);

// write multiple messages (raw)
$this->sqs->mWrite({
    $user1data,
    $user2data,
    $user3data,
]);

// write a message (raw) from a local file
$this->sqs->copyTo('', '/path/to/file');

// write multiple messages (raw) from local files
$this->sqs->mCopyTo([
    '/path/to/file1',
    '/path/to/file2',
    '/path/to/file3',
]);