{"id":13624119,"url":"https://github.com/namshi/notificator","last_synced_at":"2025-04-04T21:07:45.148Z","repository":{"id":9433989,"uuid":"11308389","full_name":"namshi/notificator","owner":"namshi","description":"A very lightweight library to handle notifications the smart way.","archived":false,"fork":false,"pushed_at":"2018-06-05T22:12:10.000Z","size":122,"stargazers_count":193,"open_issues_count":0,"forks_count":26,"subscribers_count":46,"default_branch":"master","last_synced_at":"2025-03-28T20:07:09.696Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/namshi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-10T09:54:30.000Z","updated_at":"2025-03-09T00:51:23.000Z","dependencies_parsed_at":"2022-08-23T13:50:24.115Z","dependency_job_id":null,"html_url":"https://github.com/namshi/notificator","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fnotificator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fnotificator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fnotificator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fnotificator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namshi","download_url":"https://codeload.github.com/namshi/notificator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:38.988Z","updated_at":"2025-04-04T21:07:45.132Z","avatar_url":"https://github.com/namshi.png","language":"PHP","funding_links":[],"categories":["通知","通知 Notifications","目录","Table of Contents","PHP","Notifications","通知( Notifications )"],"sub_categories":["通知 Notifications","Notifications","Globalization"],"readme":"# NAMSHI | Notificator\n\n[![Build Status](https://travis-ci.org/namshi/notificator.png?branch=master)](https://travis-ci.org/namshi/notificator)\n\n[![SensioLabsInsight](https://insight.sensiolabs.com/projects/b373d6fe-b6a0-4ad2-a12e-fc2e788a79c2/mini.png)](https://insight.sensiolabs.com/projects/b373d6fe-b6a0-4ad2-a12e-fc2e788a79c2)\n\n*Notificator* is a very simple and\nlightweight library to handle\nnotifications the smart way.\n\nIt took inspiration from other\nlibraries and patterns (Monolog and event dispatching)\nin order to provide a domain-driven\nlean notification library.\n\nConcepts are very simple: you have a\nnotification **Manager** which has a\nfew handlers registered with it (maybe an\n**Email** handler, a **Skype** handler, etc.);\nyou only have to create a notification\nclass, define which handlers should\nhandle it and trigger it through the manager.\n\nIt is way simpler in code than in words, check\nthe documentation below!\n\n## Installation\n\nInstallation can be done via composer, as the\nlibrary is already on [packagist](https://packagist.org/packages/namshi/notificator).\n\nThe library uses semantic versioning for its API,\nso it is recommended to use a stable minor version\n(1.0, 1.1, etc.) and stick to it when declaring dependencies\nthrough composer:\n\n```\n\"namshi/notificator\": \"1.0.*\",\n```\n\n## Usage\n\nUsing this library is very easy thanks to the simple\nconcept - borrowed from others - behind it: you basically have a\nnotification manager with some handlers and then you fire\n(`trigger()`) the notification with the manager. At that point,\nall the handlers that need to fire that notification will take\ncare of firing it in their context (might be an email, a skype message, etc)\nand tell the manager that they're done, so that the manager\ncan forward the notification to the next handler.\n\n``` php\n\u003c?php\n\n// import namespaces\nuse Namshi\\Notificator\\Notification\\Handler\\NotifySend as NotifySendHandler;\nuse Namshi\\Notificator\\Manager;\nuse Namshi\\Notificator\\Notification\\NotifySend\\NotifySendNotification;\n\n//  create the handler\n$handler = new NotifySendHandler();\n\n// create the manager and assign the handler to it\n$manager = new Manager();\n$manager-\u003eaddHandler($handler);\n\n$notification = new NotifySendNotification(\"...whatever message...\");\n\n//  trigger the notification\n$manager-\u003etrigger($notification);\n```\n\nThis code, ran on ubuntu, will fire the notification using the\n`notify-send` utility:\n\n![notify-send](http://odino.org/images/phpunit-notification-ko.png)\n\n## The notification Manager\n\nThe manager is the entity that registers all the\nhandlers and fires the notification.\n\nYou can set and add handlers very easily:\n\n``` php\n\u003c?php\n\n$handler  = new MyHandler();\n$handlers = array(\n    new AnotherHandler(), new AnotherOneHandler(),\n);\n\n$manager = new Manager();\n\n// add multiple handlers\n$manager-\u003esetHandlers($handlers);\n\n// add a single handler\n$manager-\u003eaddHandler($handler);\n\n// reset the handlers\n$manager-\u003esetHandlers(array());\n```\n\n## Creating a new notification\n\nCreating new notifications is very easy, as they\nare plain PHP classes.\n\nThey *might* extend the base Notification class but\nthat is not mandatory.\nIt is recommended, to be able to fire one notification\nthrough multiple handlers, to extend the base Notification\nclass, and implement different interfaces that will be later\nchecked by the handlers.\n\n``` php\n\u003c?php\n\nuse Namshi\\Notificator\\Notification;\nuse Namshi\\Notificator\\NotificationInterface;\n\ninterface EchoedNotificationInterface extends NotificationInterface\n{\n    public function getMessage();\n}\n\ninterface EmailNotificationInterface extends NotificationInterface\n{\n    public function getAddress();\n    public function getSubject();\n    public function getBody();\n}\n\nclass DoubleNotification extends Notification implements EchoedNotificationInterface, EmailNotificationInterface\n{\n    protected $address;\n    protected $body;\n    protected $subject;\n\n    public function __construct($address, $subject, $body, array $parameters = array())\n    {\n        parent::__construct($parameters);\n\n        $this-\u003eaddress  = $address;\n        $this-\u003ebody     = $body;\n        $this-\u003esubject  = $subject;\n        $this-\u003emessage  = $body;\n    }\n\n    public function getAddress()\n    {\n        return $this-\u003eaddress;\n    }\n\n    public function getSubject()\n    {\n        return $this-\u003esubject;\n    }\n\n    public function getBody()\n    {\n        return $this-\u003ebody;\n    }\n\n    public function getMessage()\n    {\n        return $this-\u003emessage;\n    }\n}\n```\n\nAs you probably got, the above notification class is meant\nto be triggered via email **and** with the `echo` function\n(pretty useless, but gives you an idea).\n\nBut the work wouldn't be over here, as you would need to\nimplement handlers for this notification...\n\n## Creating a new handler\n\nLet's say that we want to create the handlers that would\nhandle the notification above, by echoing it and sending it\nvia email: it is a matter of implementing 2 classes with\na couple methods, `shouldHandle` and `handle`.\n\nLet's see how the `EchoedNotificationHandler` should look like:\n\n``` php\nuse Namshi\\Notificator\\Notification\\Handler\\HandlerInterface;\nuse Namshi\\Notificator\\NotificationInterface;\n\nclass EchoedNotificationHandler implements HandlerInterface\n{\n    public function shouldHandle(NotificationInterface $notification)\n    {\n        return $notification instanceOf EchoedNotificationInterface;\n    }\n\n    public function handle(NotificationInterface $notification)\n    {\n        echo $notification-\u003egetMessage();\n    }\n}\n```\n\nPretty easy, right?\n\nFirst, we need to check if this handler is handling the given notification,\nand that check is done by seeing if the notification implements\na known interface; second, we actually trigger the notification.\n\nThe same thing needs to be done for the `EmailNotificationHandler`:\n\n``` php\nuse Namshi\\Notificator\\Notification\\Handler\\HandlerInterface;\nuse Namshi\\Notificator\\NotificationInterface;\n\nclass EmailNotificationHandler implements HandlerInterface\n{\n    public function shouldHandle(NotificationInterface $notification)\n    {\n        return $notification instanceOf EmailNotificationInterface;\n    }\n\n    public function handle(NotificationInterface $notification)\n    {\n        mail($notification-\u003egetAddress(), $notification-\u003egetSubject(), $notification-\u003egetBody());\n    }\n}\n```\n\nIf you want to stop notification propagation after an handler has triggered\nthe notification, you just need to return `false` in the `handle` method of the\nhandler:\n\n``` php\npublic function handle(NotificationInterface $notification)\n{\n    // do whatever you want with the notification\n    // ...\n\n    return false;\n}\n```\n\nThis will tell the manager to stop propagating the notification to other\nhandlers.\n\n## Inside Symfony2\n\n[Namshi](http://en-ae.namshi.com) is currently using this library inside\ntheir Symfony2 applications.\n\nAdd the bundle to your AppKernel.php:\n\n```\n     $bundles = array(\n         ...\n         new Namshi\\Notificator\\Symfony\\NamshiNotificatorBundle()\n     );\n```\n\nTo register a new handler, create a service with the `notification.handler` tag:\n\n```\nnamshi.notification.handler.email:\n    class: Namshi\\Notificator\\Notification\\Handler\\Emailvision\n    arguments:\n      client: @namshi.email_client.emailvision\n            \n    tags:\n        - { name: notification.handler }\n\nnamshi.email_client.emailvision:\n    class: Namshi\\Emailvision\\Client\n    arguments:\n      config:\n        test_email:\n          random:   AAA\n          encrypt:  BBB\n          uidkey:   email\n          stype:    NOTHING\n```\n\nThis configuration registers an Emailvision handler.\n\n## RabbitMQ\n\nIf you use Symfony2 and the [RabbitMQBundle](https://github.com/videlalvaro/rabbitmqbundle)\nyou can trigger notifications with this library via RabbitMQ, by using the\n[provided consumer](https://github.com/namshi/notificator/blob/master/src/Namshi/Notificator/Messaging/RabbitMQ/Symfony2/Consumer.php).\n\nDeclare the consumer as a service:\n\n```\nnamshi.notification.consumer:\n    class: Namshi\\Notificator\\Messaging\\RabbitMQ\\Symfony2\\Consumer\n    arguments: [@namshi.notification.manager]\n```\n\nThen configure it within the RabbitMQ bundle:\n\n```\nold_sound_rabbit_mq:\n    consumers:\n        notification:\n            connection: default\n            exchange_options: {name: 'notifications', type: direct}\n            queue_options:    {name: 'notifications'}\n            callback:         namshi.notification.consumer\n```\n\nAnd at that point you can run the consumer with:\n\n```\nphp app/console rabbitmq:consumer -w notification\n```\n\nTo send notifications, the idea is that you serialize them inside the\nRabbitMQ messages:\n\n``` php\n$publisher = $container-\u003eget('old_sound_rabbit_mq.notifications_producer');\n\n$notification = new MyWhateverNotification(\"man, this comes from RabbitMQ and Symfony2!\");\n\n$publisher-\u003epublish(serialize($notification));\n```\n\nThat's it!\n\n## Built-in handlers\n\nWe, at [Namshi](https://github.com/namshi) have developed some very simple,\nbuilt-in, handlers according to our needs. Keep in mind that the main\nreason behind building this kind of library is the ability of triggering\nnotification from each component of our SOA, mostly via RabbitMQ.\n\nYou can take advantage of the following handlers:\n\n* `SwiftMailer`, which lets you use the amazing [SwiftMailer](http://swiftmailer.org/) to send email notifications through any SMTP server (ie. Amazon's SES, or SendGrid)\n* `HipChat`, which posts messages in an [HipChat](https://www.hipchat.com) room\n* `Emailvision`, which sends emails through the [Emailvision API](http://www.emailvision.com/)\n* `NotifySend`, which triggers notifications on Ubuntu\n* `RabbitMQ`, which triggers notifications through [RabbitMQ](http://www.rabbitmq.com/)\n\nIf you have an idea for a new handler, don't hesitate with a pull request:\nsure, they can be implemented within your own code, but why not sharing them\nwith the OSS ecosystem?\n\n## Examples\n\nYou can have a look at the few examples provided so far,\nunder the `examples` directory:\n\n* [sending messages on HipChat](https://github.com/namshi/notificator/blob/master/examples/hipchat.php)\n* [creating a custom handler that sends an email](https://github.com/namshi/notificator/blob/master/examples/email-custom-handler.php)\n* [using the notify-send handler](https://github.com/namshi/notificator/blob/master/examples/notify-send.php)\n* [triggering a notification that is not handled by any handler](https://github.com/namshi/notificator/blob/master/examples/unhandled.php)\n\n## Running specs\n\nIn order to run the spec suite after running `composer install` do the following:\n\n``` cli\nphp vendor/bin/phpspec run --format=dot\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fnotificator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamshi%2Fnotificator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fnotificator/lists"}