Download the PHP package foodticket/laravel-aws-pubsub without Composer
On this page you can find all versions of the php package foodticket/laravel-aws-pubsub. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download foodticket/laravel-aws-pubsub
More information about foodticket/laravel-aws-pubsub
Files in foodticket/laravel-aws-pubsub
Package laravel-aws-pubsub
Short Description A Laravel broadcasting driver and queue driver that broadcasts and listens to published events utilising AWS SNS, EventBridge and SQS.
License MIT
Homepage https://github.com/pod-point/laravel-aws-pubsub
Informations about the package laravel-aws-pubsub
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
- This package installed and configured on both Laravel applications: the publisher and the subscriber
- At least one SQS Queue - one queue per Laravel application subscribing
- At least one SNS Topic
- An disabled
- 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 enabledrestored
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
All versions of laravel-aws-pubsub with dependencies
ext-json Version *
aws/aws-sdk-php Version ^3.155
illuminate/support Version ^8.52|^9.0|^10.0|^11.0