PubSub for Laravel

This package integrates Laravel projects with Publish/Subscribe providers, using a content-based pub/sub model.

Supported Providers

• AWS SNS

Install

via composer:

$ composer require thefreshuk/pubsub-laravel

Configuration

By default, this package looks for the following env variables:

PUBSUB_PROVIDER=sns
PUBSUB_TOPIC=<insert topic name>
PUBSUB_ALLOW_HTTP=<true or false>
PUBSUB_SNS_HOST_PATTERN=<regex string e.g /yourdomain.com/>

You may override this by running the following in your project:

php artisan vendor:publish

With regards to PUBSUB_ALLOW_HTTP, this configures the library to allow HTTP endpoints. Right now, only the signature cert URL is checked as part of SNS message verification. Setting this to true requires the use of a forked package (AWS SNS message validator doesn't allow HTTP at all out of the box). To set this up, add the following to your composer.json file:

"repositories": [
  {
    "type": "vcs",
    "url": "[email protected]:thefreshuk/aws-php-sns-message-validator.git"
  }
]

And then run:

$ composer update

Usage

Subscriptions

There are two ways to subscribe to a topic:

1. Extend SubscriptionServiceProvider:

use TheFresh\PubSub\SubscriptionServiceProvider as ServiceProvider;

class MockSubscriptionServiceProvider extends ServiceProvider
{
    public static $booted = false;

    /**
     * Like RouteServiceProvider, this namespace is applied to
     * the routes generated by this service provider.
     *
     * @var string $namespace
     */
    protected $namespace = 'App\Http\Controllers';

    /**
     * A mapping of message types to routes/controller actions that capture
     * messages.
     *
     * @var string $subscribe
     */
    protected $subscribe = [
        'test_type1' => ['/subscriptions/test-type', 'MockController@onTestType']
    ];

    public function boot()
    {
        parent::boot();

        static::$booted = true;
    }
}

This allows you to specify a mapping of 'types' to routes and controllers.

Types are our way of distinguishing between messages. Combined with content-based filtering, this provides a system that feels like a multi-topic system without the proliferation of topics in traditional SNS.

2. Inject Topic

The Topic class is available for use however you wish. By providing a ClientInterface object and a topic name, as a string, you can use multiple topics with this library.

Laravel will inject the default Topic into relevant type-hinted constructors. Since the library has been designed for use with a content-based Pub\Sub system, there must be a 'default' topic or else this will fail.

Publishing

The Topic class provides a publish method that accepts a message. It's as simple as calling this method for a given topic.

$topic->publish($message);

Messages

Messages are sent by publishers and received by subscribers. Every message has a 'type' and 'content':

{
  type: string,
  content: {}
}

The Pub\Sub system (preferably) filters based on the type property.

There are two ways to use Messages:

1. Separate classes

You can use the following command to generate message classes:

$ artisan make:message ExampleMessage

This generates a message class in <app_dir>/PubSub/Messages. You can instantiate and publish these messages.

2. DynamicMessage

You can also use the TheFresh\PubSub\Messages\DynamicMessage class. This accepts $type and $content constructor arguments. All messages received through subscriptions are DynamicMessages.