omar-makled/aqarmap-notification

This package is abandoned and no longer maintained. No replacement package was suggested.
There is no license information available for the latest version (1.6) of this package.

1.6 2018-02-18 14:36 UTC

README

Introduction

We serve as a great way to decouple various aspect of notification and channels since each one of them is a detached class which provides a very low coupling.

We provides support for sending notifications across a variety of delivery channels, including mail, database, SMS, and more ..

Installing

Aqarmap Notification is a symfony bundle, first off you need to create new symfony app

symfony new my-app

Via Composer

To get the latest version, simply require the bundle using composer

composer require omar-makled/aqarmap-notification

Notice you may need to set "minimum-stability": "dev" inside composer.json

"minimum-stability": "dev",
"prefer-stable": true

Via Clone Repo

Alternatively, you may also install Notification by cloning repo inside src directory git clone git@github.com:OmarMakled/aqarmap-notification.git NotificationBundle after download is complete you should update composer autoload and run composer dump

"autoload": {
    "psr-4": {
        "AppBundle\\": "src/AppBundle",
        "Aqarmap\\NotificationBundle\\": "src/NotificationBundle/src"
    },

Once installed, you need to register the new Aqarmap\NotificationBundle\NotificationBundle in your app/AppKernel.php You also need run the bin/console doctrine:schema:update --dump-sql to create a notification table qaramap_notification

Creating Notifications

Each notification is represented by a single class (typically stored in the Bundle/Notifications directory), as a convenient place to register all of your application's notifications.

bin/console aqarmap:notification-create

This command will help you to create a fresh notification class in AppBundle/Notifications directory.

Welcome to the Aqarmap notification generator

Bundle name (e.g. AppBundle): AppBundle
Notification name (e.g InvoicePaid): NewListing
Please select notfication config [default ClassConfig]
  [0] ClassConfig
  [1] YmlConfig
 > ClassConfig
Please select channel [default all]
  [0] Database
  [1] Mail
  [2] SMS
 >
Do you want to queue channel [Yes]?
Please select queue channel (defaults to all)
  [0] Database
  [1] Mail
  [2] SMS
 >
Do you want to constructor injection with `TwigEngine` [recommended Yes]?

Summary before generation
You are going to generate a NewListing command inside AppBundle bundle.
Do you confirm generation [Yes]?
  created ./src/AppBundle/Notifications/NewListing.php
Generated the NewListing command in AppBundle
Everything is OK! Now get to work :).

Notifications Config

Each notification can be configured inside class or yml file it depends on your needs.

For example here's inside NewListing.php we defined channel and queue, notice it's important to set public $config = \Aqarmap\NotificationBundle\Config\ClassConfig::class it tells NotificationManager about config type

/**
 * Point to config type
 *
 * @var \Aqarmap\NotificationBundle\Config\ConfigInterface
 */
public $config = \Aqarmap\NotificationBundle\Config\ClassConfig::class;

/**
 * List of channels
 *
 * @var array
 */
public $channel = ["Database","Mail","SMS"];

/**
 * List of queue channels
 *
 * @var array
 */
public $queue = [];

Sometime you may need to config notification in config.yml for releasing purpose here we point to YmlConfig telling manager look for config inside config.yml (stored in the Bundle/Notifications/config.yml and generated automatically)

NewListing.php

/**
 * Point to config type
 *
 * @var \Aqarmap\NotificationBundle\Config\ConfigInterface
 */
public $config = \Aqarmap\NotificationBundle\Config\YmlConfig::class;

config.yml

Notifications:
    NewListing:
        class: Notifications\NewListing
        channel: ['sms', 'database', 'mail']
        queue: ['sms', 'database', 'mail']

Sending Notifications

Inside controller

Notification Manager is defined inside service container so you can get new instance by $this->get('noification_manager)

Notice If you answer yes Do you want to constructor injection withTwigEngine[recommended Yes]? It can be helpful to render email skeleton, if so You must pass dependencies it will not be injected automatically, you can use to power of service container.

Controller.php

$manager = $this->get('notification_manager');
$manager->send($users, new NewListing($this->get('templating'));

NewListing.php

/**
 * Define the message via Mail channel
 *
 * @return string
 */
public function byMail()
{
    return $this->twigEngine->render(
        __DIR__.'/views/newlisting.php.twig'
    );
}

Using The Event Subscriber

Event subscribers are classes that may subscribe to multiple events from within the class itself Creating Event Subscriber, typically event subscriber should be registered via services.yml

services.yml

notification_subscriber:
    class: AppBundle\NotificationSubscriber
    arguments: ["@notification_manager"]
    tags:
        - {name: kernel.event_subscriber}

NotificationSubscriber.php

class NotificationSubscriber implements EventSubscriberInterface
{
    /**
     * Notification manager instance.
     *
     * @var \Aqarmap\NotificationBundle\NotificationManager
     */
    public $manager;

    /**
     * Create a notification subscriber instance.
     *
     * @param \Aqarmap\NotificationBundle\NotificationManager $manager
     */
    public function __construct(NotificationManager $manager)
    {
        $this->manager = $manager;
    }

    /**
     * Register the listeners for the subscriber.
     */
    public static function getSubScribedEvents()
    {
        return [
            'add.listing' =>  'SendNewListingNotification'
        ];
    }

    /**
     * Send new listing notification
     *
     * @param \AppBundle\Events\AddListingEvent $event
     */
    public function SendNewListingNotification(AddListingEvent $event)
    {
        $this->manager->send($event->users, new NewListingNotification($event->listing));
        $event->stopPropagation();
    }
}

Using The Event Listner

Since a single event can have multiple listeners that do not depend on each other. For example, you may wish to send a SMS notification to your users each time an new listing has added. Instead of coupling your code is one class such as EventSubscriber EventListner is the most common way.

Notifications Events

Events provides a simple observer implementation, allowing you to subscribe and listen for various events that occur in your application.

When a notification is sent, the Aqarmap\NotificationBundle\Events\NotificationSent event is fired by the notification system. This contains the NotificationInterface and channel. You may register listeners for this event in your app.

Queueing Notifications

Sending notifications can take time, You can set a particular channel to run asynchronously, by just define queue property

Test Case

Aqarmap notifications is built with testing in mind and shipped with test case.

ToDo

  • there're still alot of things ....