kinetis / queue-sqs

v1.2.0 2026-09-05 08:02 UTC

Requires

• php: ^8.4
• async-aws/sqs: ^2.9.0
• kinetis/framework: ^1.3.1
• kinetis/queue: ^1.2.0
• kinetis/revolt-http-client: ^1.1.3

Requires (Dev)

• infection/infection: ^0.35.0
• phpstan/phpstan: ^2.2.8
• phpunit/phpunit: ^12.5.33
• vimeo/psalm: ^6.16.1

MIT

• Alon Noy

Published on Packagist.org on 2026-09-05 08:08 UTC

README

kinetis/queue-sqs
A Fiber-native, non-blocking Amazon SQS backend for kinetis/queue's QueueInterface

Part of Kinetis, a non-blocking PHP framework for API-first applications, developed in the kinetis-dev/kinetis monorepo.

Adds Amazon SQS as a queue backend. push()/pop()/ack()/release()/fail() work exactly like any other backend — only your configuration changes.

SqsQueue implements Kinetis\Queue\QueueInterface and not Kinetis\Queue\ClearableQueueInterface: it has no clear(), and kinetis queue:clear names the backend and stops. SQS offers no operation that meets the clearing contract. PurgeQueue deletes the messages a worker holds in flight along with the waiting ones, keeps deleting messages sent during the up-to-60-second window it takes to finish, reports no count, and is rate-limited to once per 60 seconds per queue — so this package never calls it. size() could not report what such a call destroyed either: it excludes in-flight work and is an estimate. Empty an SQS queue the way you created it, with aws sqs purge-queue or by recreating it.

QueuedJob::$handle is the message's ReceiptHandle, which SQS scopes to the receive that produced it. This backend cannot tell SQS's answer for a spent handle apart from any other API error, so it raises no Kinetis\Queue\Exception\StaleJobHandleException and whatever SQS returns propagates as itself. SQS can also redeliver a message independently of anything this package does, so job handlers have to be idempotent.

use Kinetis\Config\Config;
use Kinetis\QueueSqs\SqsClientFactory;
use Kinetis\QueueSqs\SqsQueue;

$queue = new SqsQueue(SqsClientFactory::fromConfig($config));

$queue->push(new SendWelcomeEmail($email, $name), queue: 'default');

Configuration

QUEUE_CONNECTION=sqs
QUEUE_SQS_REGION=us-east-1

Key	Default	Purpose
QUEUE_SQS_REGION	(required)	AWS region.
QUEUE_SQS_ENDPOINT	—	SQS-compatible endpoint (e.g. LocalStack).
QUEUE_SQS_QUEUE_PREFIX	—	Prepended to every queue name — for shared AWS accounts.

All three are scoped — QUEUE_SQS_REGION + reports → QUEUE_REPORTS_SQS_REGION. kinetis/queue's own keys (QUEUE_CONNECTION, QUEUE_MAX_ATTEMPTS, ...) are documented in that package; full reference: kinetis.dev/docs/config.html.

Credentials are never read from Kinetis config — AsyncAws's own default credential provider chain (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or an IAM role) resolves them. A push()/pop() queue name resolves directly to an SQS queue of that name — create it ahead of time; this package never creates one automatically.

Installation

composer require kinetis/queue-sqs

Requires PHP 8.4+, kinetis/framework, kinetis/queue, and kinetis/revolt-http-client. Full documentation: kinetis.dev/docs/queue-sqs.html.

License

MIT — see LICENSE.