coverzen / configurable-sqs

v1.4.0 2026-10-16 12:58 UTC

Requires

• php: ^8.2||^8.3
• aws/aws-sdk-php: ^3.304

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.53
• nunomaduro/phpinsights: ^2.11
• orchestra/testbench: ^8.22||^9.11||^10.0
• pestphp/pest: ^2.34||^3.0
• pestphp/pest-plugin-arch: ^2.7||^3.0
• pestphp/pest-plugin-laravel: ^2.3||^3.0
• phpmd/phpmd: ^2.15
• phpstan/extension-installer: ^1.3
• phpstan/phpstan: ^1.10
• phpstan/phpstan-mockery: ^1.1
• phpstan/phpstan-phpunit: ^1.3
• povils/phpmnd: ^3.4
• roave/security-advisories: dev-latest
• squizlabs/php_codesniffer: ^3.9
• timacdonald/log-fake: ^2.2

MIT

• Francesco Giovannini

Published on Packagist.org on 2026-10-16 12:59 UTC

README

This package provides a simple way to subscribe to an AWS SQS queue in Laravel. The package is designed to be as simple as possible to use, with a simple configuration for redirect any message to a specific listener. On Classic Laravel Listeners is possible add a enqueueFilter method to filter the message before the job is enqueued to SQS.

Installation

composer require coverzen/configurable-sqs

Configuration

First, you need to add the following environment variables to your .env file:

AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=your-region
AWS_ACCOUNT_ID=your-account-id

Then, you need to add the following configuration to your config/queue.php file:

'connections' => [

    ...
    
    'configurable-sqs' => [
        'driver' => 'configurable-sqs',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'prefix' => 'https://sqs.'.env('AWS_DEFAULT_REGION').'.amazonaws.com/'.env('AWS_ACCOUNT_ID').'/',
        'queue' => 'your-queue-name',
        'suffix' => '',
        'region' => env('AWS_DEFAULT_REGION'),
        'has_consumer' => true,
    ],
]

Usage

To subscribe custom listener to a queue, you need to create a new listener class and configure it in the configurable-sqs.php file.

    'your-queue-name' => [
        [
            'type' => ConfigurableJob::TYPE_SQS_SIMPLE_PAYLOAD,
            'search' => [
                'key' => 'message',
                'value' => 'test',
            ],
            'listener' => YourListener::class,
        ],
        [
            'type' => ConfigurableJob::TYPE_SQS_REGEX_PAYLOAD,
            'search' => [
                'key' => 'message',
                'value' => '/^test$/i',
            ],
            'listener' => YourListener::class,
        ],
        [
            'type' => ConfigurableJob::TYPE_SNS_FROM,
            'arn' => 'arn:aws:sns:eu-south-1:0000000000:HelloWorld',
            'listener' => YourListener::class,
        ],
    ],

The type key can be one of the following values:

• ConfigurableJob::TYPE_SQS_SIMPLE_PAYLOAD: This type will search for a specific key and value in the SQS message.
• ConfigurableJob::TYPE_SQS_REGEX_PAYLOAD: This type will search for a specific key and value in the SQS message using a regex pattern.
• ConfigurableJob::TYPE_SNS_FROM: This type will search for a specific SNS ARN in the SQS message.

Per-listener tries, backoff, timeout and fail_on_timeout

Every listener entry (any type) accepts optional keys that override the worker's --tries, --backoff and --timeout options for the messages it matches:

        [
            'type' => ConfigurableJob::TYPE_SQS_SIMPLE_PAYLOAD,
            'search' => [
                'key' => 'message',
                'value' => 'test',
            ],
            'listener' => YourListener::class,
            'tries' => 4,               // max attempts, based on SQS ApproximateReceiveCount
            'backoff' => [5, 30, 60],   // seconds before the message is visible again: int or array<int>
            'timeout' => 120,           // seconds before the worker is killed, 0 disables it
            'fail_on_timeout' => true,  // on timeout, fail the message instead of letting SQS deliver it again
        ],

When the listener throws, the message is released back to SQS with a visibility timeout equal to the backoff for the current attempt (the last value is reused for later attempts). When a key is missing, the worker options apply as before. Numeric strings (e.g. from env()) are accepted; invalid values are ignored.

Warning: keep timeout lower than the SQS queue VisibilityTimeout. Otherwise the message becomes visible again while the listener is still running, and another worker processes it in parallel.

The listener class can implement the Coverzen\ConfigurableSqs\Interfaces\ListenerInterface interface.

namespace App\Listeners;

YourListener implements ListenerInterface
{
    public function handle(array $message): void
    {
        // Your logic here
    }
}

Simple SQS message job

ExampleSimpleSQSJob.php

use Coverzen\ConfigurableSqs\Job\SimpleSQSJob;

class ExampleSimpleSQSJob extends SimpleSQSJob
{
    protected string $event = 'example';

    public function __construct($data)
    {
        parent::__construct($data);
    }
}

EventTrigger.php

use App\Jobs\ExampleSimpleSQSJob;

class EventTrigger
{
    public function trigger()
    {
        ExampleSimpleSQSJob::dispatch([
            'message' => 'test',
        ]);
    }
}

When the EventTrigger::trigger() class is executed the ExampleSimpleSQSJob will be dispatched to queue trough sqs-configurable driver using a simple message payload as:

{
    "event": "example",
    "data": {
        "message": "test"
    }
}

Filter message before job is enqueued

You can add a enqueueFilter method to your listener class to filter the message before the job is enqueued to SQS.

namespace App\Listeners;

use App\Events\MyEvent;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class TestListener implements ShouldQueue
{
    use Queueable;

    public static function enqueueFilter(MyEvent $event): bool
    {
        // Your logic here
        // If you return false the job will not be enqueued
        return true;
    }

    public function handle(MyEvent $event): bool
    {
        return true;
    }
}

Sending only queue configuration

If you want to send only the queue configuration, you need turn to false has_consumer configuration option.

'connections' => [

    ...
    
    'configurable-sqs-send-only' => [
        'driver' => 'configurable-sqs',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'prefix' => 'https://sqs.'.env('AWS_DEFAULT_REGION').'.amazonaws.com/'.env('AWS_ACCOUNT_ID').'/',
        'queue' => 'your-queue-name',
        'suffix' => '',
        'region' => env('AWS_DEFAULT_REGION'),
        'has_consumer' => false,
    ],
]

License

The MIT License (MIT). Please see License File for more information.

Credits

• Coverzen