A Lumen & Laravel package for Google Pub/Sub or Amazon SNS
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
tests Adding Amazon SNS driver tests Jan 19, 2017
composer.json Adding Amazon SNS driver tests Jan 19, 2017



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.


  • 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


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

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


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


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.


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.

  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.


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.


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:

        'pubsub' => \GenTux\PubSub\Http\PubSubMiddleware::class,
  2. Generate a random string and add it to your .env file.

  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(
                    // AccountCreatedMessage::class,
  4. Add a route for the controller.

            '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


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

Be sure that the PubSubServiceProvider is registered.