Download the PHP package itprojektrepo/laravel-aws-pubsub without Composer

AWS PubSub for Laravel

The Pub

Similar to Pusher, this package provides Laravel Broadcasting drivers for AWS SNS (Simple Notification Service) and AWS EventBridge in order to publish server-side events.

We understand Broadcasting is usually used to "broadcast" your server-side Laravel Events over a WebSocket connection to your client-side JavaScript application. However, we believe this approach of leveraging broadcasting makes sense for a Pub/Sub architecture where an application would like to broadcast a server-side event to the outside world about something that just happened.

In this context, "channels" can be assimilated to "topics" when using the SNS driver and "event buses" when using the EventBridge driver.

The Sub

This part is pretty straight forward, we simply have to listen to these messages pushed to an SQS queue and act upon them. The only difference here is that we don't use the default Laravel SQS driver as the messages pushed are not following Laravel's classic JSON payload for queued Jobs/Events pushed from a Laravel application. The messages from SNS are simpler.

Prerequisites

1. This package installed and configured on both Laravel applications: the publisher and the subscriber
2. At least one SQS Queue - one queue per Laravel application subscribing
3. At least one SNS Topic
4. An disabled
5. The relevant Access policies configured, especially if you want to be able to publish messages directly from the AWS Console.

Installation

You can install the package on a Laravel 8+ application via composer:

Note: For Laravel 5.x, 6.x or 7.x you can use pod-point/laravel-aws-pubsub:^0.0.1.

This package needs a separate Service Provider, please install it by running:

This will create App\Providers\PubSubEventServiceProvider and load it within your config/app.php file automatically.

Publishing / Broadcasting

Configuration

You will need to add the following connection and configure your SNS credentials in the config/broadcasting.php configuration file:

Make sure to define your environment variables accordingly:

The arn-suffix can be used to help manage SNS topics for different environments. It will be added to the end when constructing the full SNS Topic ARN.

Next, you will need to make sure you're using the sns broadcast driver as your default driver when broadcasting in your .env file:

or

Remember that you can define the connection at the Event level if you ever need to be able to use two drivers concurrently.

Usage

Simply follow the default way of broadcasting Laravel events, explained in the official documentation.

In a similar way, you will have to make sure you're implementing the Illuminate\Contracts\Broadcasting\ShouldBroadcast interface and define which channel / Topic you'd like to broadcast on.

Broadcast Data

By default, the package will publish the default Laravel payload which is already used when broadcasting an Event. Once published, its JSON representation could look like this:

By default, Laravel will automatically add any additional public property to the payload:

Which would produce the following payload:

However, using the broadcastWith method, you will be able to define exactly what kind of payload gets published.

Now, when the event is being triggered, it will behave like a standard Laravel event, which means other listeners can listen to it, as usual, but it will also broadcast to the Topic defined by the broadcastOn method using the payload defined by the broadcastWith method.

Broadcast Name / Subject

In a Pub/Sub context, it can be handy to specify a Subject on each notification which broadcast to SNS. This can be an easy way to configure a Listeners for each specific kind of subject you can receive and process later on within queues.

By default, the package will use the standard Laravel broadcast name in order to define the Subject of the notification sent. Feel free to customize it as you wish.

Model Broadcasting

If you're familiar with Model Broadcasting, you already know that Eloquent models dispatch several events during their lifecycle and broadcast them accordingly.

In the context of model broadcasting, only the following model events can be broadcasted:

• created
• updated
• deleted
• trashed if soft delete is enabled
• restored if soft delete is enabled

In order to broadcast the model events, you need to use the Illuminate\Database\Eloquent\BroadcastsEvents trait on your Model and follow the official documentation.

You can use broadcastOn(), broadcastWith() and broadcastAs() methods on your model in order to customize the Topic names, the payload and the Subject respectively.

Note: Model Broadcasting is only available from Laravel 8.x. If you'd like to do something similar with an older version of Laravel, we recommend to manually dispatch some "broadcastable" Events you'd be creating yourself from the Model Observer functions.

Subscribing / Listening

Configuration

Once the package is installed and similar to what you would do for a standard Laravel SQS queue, you will need to add the following connection and configure your credentials in the config/queue.php configuration file:

Once your queue is configured properly, you will need to be able to define which listeners you would like to use for which kind of incoming events. In order to do so, you'll need to create Laravel listeners and associate the events through a Service Provider the package can create for you.

Registering Events & Listeners

You'll need a separate Service Provider in order to define the mapping for each PubSub event and its Listeners. We provide App\Providers\PubSubEventServiceProvider which you should have already installed by now when running php artisan pubsub:install upon package installation.

The listen property contains an array of all events (keys) and their listeners (values). Unlike the standard Laravel EventServiceProvider, you can only define one Listeners per event, however you may add as many events to this array as your application requires.

Using the Broadcast Name / Subject of an SNS message

You can define a PubSub event by using its Broadcast Name / Subject. For example, let's add an event with orders.shipped as its Subject (aka. Broadcast Name):

Using the SNS Topic Name

As a fallback, you can also use the ARN of an SNS Topic itself and have a more generic Listener for any event coming from that Topic which haven't been already mapped to an existing subject-based Event/Listeners couple.

For example, let's add a generic Listener for any event pushed to a given SNS Topic as a fallback:

You may do whatever you want from that generic OrdersListener, you could even dispatch more events internally within your application.

Note: Topic-based Event/Listeners couples should be registered last so the Subject-based ones take priority.

Defining Listeners

Here we are simply re-using standard Laravel event listeners. The only difference being the function definition of the main handle() method which differs slightly. Instead of expecting an instance of an Event class passed, we simply receive the payload and the subject, if it's found.

Feel free to queue these listeners, just like you would with a standard Laravel Listeners.

Generating Listeners

We also provide a convenient command to generate these classes for you:

Note: you will still need to make sure the mapping within the PubSubEventServiceProvider is configured.

Testing

Run the tests with:

Changelog

Please see our releases for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• laravel-sns-broadcaster for some inspiration
• laravel-sqs-sns-subscription-queue for more inspiration
• Laravel Package Development documentation by John Braun
• Pod Point
• All Contributors

License

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

Travel shouldn't damage the earth 🌍

Made with ❤️  at Pod Point