cerbero / notifiable-exception
Laravel package to send notifications when some exceptions are thrown.
Fund package maintenance!
cerbero90
Requires
- php: ^7.0
- illuminate/bus: ^5.5|^6.0|^7.0
- illuminate/contracts: ^5.5|^6.0|^7.0
- illuminate/notifications: ^5.5|^6.0|^7.0
- illuminate/support: ^5.5|^6.0|^7.0
Requires (Dev)
- mockery/mockery: ^1.0
- orchestra/testbench: ^3.5|^4.0
- phpunit/phpunit: ^5.4|^6.0|^7.0|^8.0
- squizlabs/php_codesniffer: ^3.0
This package is auto-updated.
Last update: 2024-09-09 13:53:31 UTC
README
Laravel package to send notifications when exceptions are thrown.
Install
Via Composer
$ composer require cerbero/notifiable-exception
We might need to install other packages depending on the notification channels we want to use (e.g. Slack, Telegram). Please refer to Laravel Notification Channels for more information.
For better performance notifications are queued, please check the documentation to find out what are the requirements for your queue driver.
Usage
In order to be notifiable, exceptions need to implement the Notifiable
interface and use the Notifies
trait:
use Cerbero\NotifiableException\Notifiable; use Cerbero\NotifiableException\Notifies; use Exception; class UrgentException extends Exception implements Notifiable { use Notifies; }
Otherwise, if we don't need to extend a particular exception class, we may just extend the NotifiableException
for convenience:
use Cerbero\NotifiableException\Exceptions\NotifiableException; class UrgentException extends NotifiableException
When notifiable exceptions are not handled manually in a try-catch
, they are notified automatically. However when we actually need to handle them we can send their notifications by calling the notify()
method in the try-catch
:
try { $this->methodThrowingNotifiableException(); } catch (NotifiableException $e) { $e->notify(); // exception handling logic }
Sometimes we might want some channel routes to always be notified when an exception is thrown. If so, we can set default routes for every channel we want to notify in config/notifiable_exception.php
:
$ php artisan vendor:publish --tag=notifiable_exception_config
As an example, the following configuration defines a Slack and a mail route that will always be notified when any notifiable exception is thrown:
'default_routes' => [ 'mail' => [ 'example@test.com', ], 'slack' => [ 'https://hooks.slack.com/services/xxx/xxx/xxx', ], ],
Please note: this README shows routes in the code for convenience, however it is recommended to set routes in environment variables that can then be read from configuration files.
Different routes might need to be notified depending on what instance of notifiable exception is thrown. Ad hoc channels and routes can be defined in notifiable exceptions themselves by overriding the method getCustomRoutes()
:
class UrgentException extends NotifiableException { protected function getCustomRoutes(): array { return [ 'nexmo' => [ '15556666666', ], ]; } }
In the example above, the phone number +1 555-666-6666
will receive an SMS whenever UrgentException
is thrown, alongside with the default routes specified in the configuration.
If we want an exception to notify only its custom routes while ignoring the default ones, we can instruct the method overridesRoutes()
to do so:
protected function overridesRoutes(): bool { return true; }
Messages to send can be customized per channel by overriding the method getMessages()
:
public function getMessages(): array { return [ 'mail' => (new MailMessage) ->error() ->subject('An error occurred') ->line($this->getMessage()), 'slack' => (new SlackMessage) ->error() ->content($content) ->attachment(function (SlackAttachment $attachment) { $attachment ->title($this->getMessage()) ->fields([ 'File' => $this->getFile(), 'Line' => $this->getLine(), 'Code' => $this->getCode(), 'Previous exception' => $this->getPrevious() ? get_class($this->getPrevious()) : 'none', ]); }), 'nexmo' => (new NexmoMessage)->content($this->getMessage()), ]; }
By default Laravel supports some notification channels (e.g. mail
, slack
), however custom channel classes need to be specified when using third-party solutions. We can define them by overriding the method getCustomChannels()
:
use NotificationChannels\Telegram\TelegramChannel; ... public function getCustomChannels(): array { return [ 'telegram' => TelegramChannel::class, ]; }
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.