A Lumen & Laravel package for Google Pub/Sub or Amazon SNS
PHP
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
tests Adding Amazon SNS driver tests Jan 19, 2017
.gitignore
.travis.yml
LICENSE.md
README.md
composer.json Adding Amazon SNS driver tests Jan 19, 2017
composer.lock
phpunit.xml

README.md

PubSub

Latest Version Coverage Status Build Status Software License

PubSub is a push notification system for your Lumen (and Laravel) backend systems. Publishers add Messages to a Topic and Subscribers receive the message as a push notification. Think of it as Laravel Echo for microservices.

Highlights

  • Build loosely coupled, scalable systems consistent with your other message-oriented Laravel code
  • Simple API that leaves your Laravel code looking clean
  • Driver-based so changing Pub/Sub providers is a simple configuration change
  • Delete the duplicated Pub/Sub boilerplate in each of your apps
  • Google Pub/Sub support
  • Amazon SNS support coming soon

Install

  1. Install PubSub using Composer.
composer require generationtux/pubsub
  1. Register the PubSub Service Provider.

    Add this line to config/app.php for Laravel:

    GenTux\PubSub\PubSubServiceProvider::class,

    Add this line to bootstrap/app.php for Lumen:

    $app->register(GenTux\PubSub\PubSubServiceProvider::class);

Pub/Sub Messages

Now you can get started defining your first Pub/Sub message. Every message must have 3 properties:

  1. $routingKey is a unique key within your application. It should follow this convention: Name of the app publishing the message dot Entity name dot Event name. Routing keys allow you to have a single topic per Object type. For example, "Customer" created, updated, and deleted messages can all be published to the same topic and the subscribers use the routing key to handle each message type accordingly.
  2. $version is used to version Topics.
  3. $entity is name of the object type (entity) that the message describes.

This is a "Customer Created" message definition.

<?php

namespace App\PubSub;

class CustomerCreatedMessage extends GenTux\PubSub\PubSubMessage
{
    public static $routingKey = 'accounts.customer.created';
    protected $version = 'v1';
    protected $entity = 'customer';
}

Google Pub/Sub

To begin using the Google Pub/Sub driver you will need to create a Google Cloud project and a Pub/Sub topic.

  1. Visit console.cloud.google.com and create a Google Cloud Project.

  2. Add the Google Project Id to your .env file.

     GOOGLE_PUBSUB_PROJECT_ID=pub-sub-demo-145921
    
  3. Create a Pub/Sub Topic under :fa-navicon: > Big Data > Pub/Sub. Use the environment-version-entity naming convention or override the topic method in your Message.

     local-v1-customer
    

Publisher Configuration

If your app is publishing messages to a Pub/Sub topic, then you need to add Google API credentials to your project. If this application is strictly subscribing to topics, then skip to the next section.

  1. Create Credentials under :fa-navicon: > API Manager > Credentials.

  2. In your .env file, add variables for the Google credentials file path.

     GOOGLE_APPLICATION_CREDENTIALS=/Users/lebronjames/google-service-account.json
    

Subscriber Configuration

  1. Register the Pub/Sub middleware. This middleware uses your PUBSUB_SUBSCRIBER_TOKEN to secure the subscription endpoint. Any messages sent to your Pub/Sub endpoint without a token will be rejected.

    Add pubsub middleware to end of the routeMiddleware array in Http\Kernel.php for Laravel apps:

    protected $routeMiddleware = [
        ...
        'pubsub' => \GenTux\PubSub\Http\PubSubMiddleware::class,
    ];

    Add the pubsub middleware line to the end of the routeMiddleware array in bootstrap/app.php for Lumen apps:

    $app->routeMiddleware([
        ...
        'pubsub' => \GenTux\PubSub\Http\PubSubMiddleware::class,
    ]);
  2. Generate a random string and add it to your .env file.

     PUBSUB_SUBSCRIBER_TOKEN=7RWfH4yxnXXsep5k3LpVxv7oSlnhyFPFeHda87i3Vc
    
  3. Add a PubSubController to your project.

    class PubSubController extends Controller
    {
        protected $pubsub;
    
        public function __construct(PubSub $pubSub)
        {
            $this->pubsub = $pubSub;
        }
    
        public function subscribe(Request $request)
        {
            return $this->pubsub->subscribe(
                $request,
                [
                    // AccountCreatedMessage::class,
                ]
            );
        }
    }
  4. Add a route for the controller.

    $app->group(
        [
            'namespace' => $ns,
            'middleware' => ['pubsub'],
        ],
        function ($app) {
            $app->post('subscribers/google-pub-sub', 'GooglePubSubController@subscribe');
        }
    );
    
  5. Start ngrok so Google Pub/Sub can reach your localhost.

  6. Follow the steps to verify the ngrok url in the Google Search Console

  7. Add the ngrok url under :fa-navicon: > API Manager > Credentials > Domain verification

FAQ

I see an error that says Target [GenTux\PubSub\Contracts\PubSub] is not instantiable.

Be sure that the PubSubServiceProvider is registered.