PHPackages                             our-edu/laravel-sqs-messaging - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. our-edu/laravel-sqs-messaging

ActiveLibrary

our-edu/laravel-sqs-messaging
=============================

Laravel package for AWS SQS messaging with RabbitMQ rollback support

3.0.0(3mo ago)06.2k↓30.5%MITPHPPHP ^8.1

Since Dec 18Pushed 3mo agoCompare

[ Source](https://github.com/our-edu/laravel-sqs-messaging)[ Packagist](https://packagist.org/packages/our-edu/laravel-sqs-messaging)[ RSS](/packages/our-edu-laravel-sqs-messaging/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (7)Versions (19)Used By (0)

Laravel SQS Messaging Package
=============================

[](#laravel-sqs-messaging-package)

A comprehensive Laravel package for AWS SQS messaging with RabbitMQ rollback support, idempotency, error handling, and CloudWatch metrics integration.

Features
--------

[](#features)

- ✅ AWS SQS integration with automatic queue/DLQ creation
- ✅ Message envelope with idempotency keys
- ✅ Redis + Database idempotency checking
- ✅ Error classification (validation, transient, permanent)
- ✅ CloudWatch metrics integration
- ✅ Dead Letter Queue (DLQ) management
- ✅ Long polling support
- ✅ RabbitMQ adapter for easy migration
- ✅ Environment-aware queue naming

Installation
------------

[](#installation)

### Via Composer

[](#via-composer)

```
composer require our-edu/laravel-sqs-messaging:3.*
```

Configuration
-------------

[](#configuration)

### 1. Publish Configuration

[](#1-publish-configuration)

```
php artisan vendor:publish --provider="OurEdu\SqsMessaging\SqsMessagingServiceProvider"
```

### 2. Environment Variables

[](#2-environment-variables)

Add to your `.env`:

```
# AWS Credentials (required)
AWS_SQS_DEFAULT_REGION=us-east-2
AWS_SQS_ACCESS_KEY_ID=your-access-key
AWS_SQS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=me-central-1
SQS_ALLOW_TIMESTAMP_ATTRIBUTE=false  # Set to true if you want to use the timestamp attribute for idempotency

# SQS Configuration
SQS_QUEUE_PREFIX=staging  # or production, dev, etc.

# Messaging Driver
MESSAGING_DRIVER=sqs        # Use SQS (default) or rabbitmq for rollback
MESSAGING_FALLBACK_TO_RABBITMQ=true  # Enable fallback to RabbitMQ when SQS queue doesn't exist

# CloudWatch Metrics (optional)
SQS_CLOUDWATCH_ENABLED=true
SQS_CLOUDWATCH_NAMESPACE=SQS/PaymentService
```

**Notes:**

1- Set `MESSAGING_FALLBACK_TO_RABBITMQ=true` if you have other projects still using RabbitMQ. This ensures messages go to RabbitMQ when SQS queue doesn't exist.

2-Set `SQS_ALLOW_TIMESTAMP_ATTRIBUTE=true` and append `timestamp` attribute to the payload of the message if you want to generate the IdempotencyKey based on the timestamp.

### 3. Configure Queues

[](#3-configure-queues)

Edit `config/sqs_queues.php`: HINT: This File Defines The SQS Queues Used By Your Application

```
return [
    'payment' => [
        'default' => 'payment-service-queue',
        'specific' => [
            'refunds' => 'payment-service-refunds-queue',
        ],
    ],
];
```

### 4. Configure Event Mappings

[](#4-configure-event-mappings)

Edit `config/sqs_events.php`:

HINT: This File Maps Events To Their Respective Listeners ( used in receiving messages )

```
return [
     'admission:admission:assign.subscription.services' => CreateStudentSchoolSubscriptionListener::class,
     'admission:admission:cancel.application' => CancelStudentSubscriptionServicesListener::class,
];
```

### 5. Configure Target Queues

[](#5-configure-target-queues)

Edit `config/sqs_target_queues.php`:

HINT: This File Maps Events To Their Target Queues ( used in publishing messages )

```
return [
    'payment:payment:student.subscribe.and.pay' => 'admission-service-queue',
    'payment:payment:cancel.students' => 'admission-service-queue',
    ];
```

### 6. Run Migration

[](#6-run-migration)

```
php artisan migrate
```

This creates the `processed_events` table for idempotency.

### 7. Ensure Queues Exist

[](#7-ensure-queues-exist)

```
php artisan sqs:ensure
```

**For Production:** Add this to your `entrypoint.sh` or container startup script to ensure queues exist before starting consumers:

```
php artisan sqs:ensure || echo "Warning: SQS queue ensure failed, but continuing startup..."
```

Usage
-----

[](#usage)

### Publishing Messages

[](#publishing-messages)

#### Option 1: Use Unified MessagingService (Recommended)

[](#option-1-use-unified-messagingservice-recommended)

The package includes a `MessagingService` that can switch between available drivers (SQS and RabbitMQ).

**Step 1:** Update your `Support\RabbitMQ\Publishable` trait and add the following method:

```
public static function publishFromInstance(object $event): void
{
    Container::getInstance()
        ->make(Publisher::class)
        ->publish($event);
}
```

**Complete updated trait:**

```