PHPackages                             iphuongtt/heimdal - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. iphuongtt/heimdal

ActiveLibrary

iphuongtt/heimdal
=================

1.5.1(8y ago)132MITPHP

Since Dec 28Pushed 8y ago1 watchersCompare

[ Source](https://github.com/iphuongtt/heimdal)[ Packagist](https://packagist.org/packages/iphuongtt/heimdal)[ RSS](/packages/iphuongtt-heimdal/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (13)Used By (0)

Heimdal
=======

[](#heimdal)

[![Latest Version](https://camo.githubusercontent.com/fb0753aeba35bbcdeb715ff673b9e91f5718dab9aa3e9e56321b8ff9c2bd815c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f697068756f6e6774742f6865696d64616c2e7376673f7374796c653d666c61742d737175617265)](https://github.com/esbenp/heimdal/releases)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Build Status](https://camo.githubusercontent.com/52f43b9ad6e3321b594d2b29272ff9eeb3c90a73c49c94c57c877962dd51ae9c/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f697068756f6e6774742f6865696d64616c2f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/iphuongtt/heimdal)[![Coverage Status](https://camo.githubusercontent.com/080029c7241de6aa01d4bab499c7336f5f870dc7f2fe636f4a35595ab698307f/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f697068756f6e6774742f6865696d64616c2e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/github/iphuongtt/heimdal)[![Total Downloads](https://camo.githubusercontent.com/4627b7138b853d915035ba2358877c80b3fc8358a1f04652cc9d1da481c685b3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f697068756f6e6774742f6865696d64616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iphuongtt/heimdal)

Introduction
------------

[](#introduction)

Heimdal is a Laravel exception handler build specifically for APIs.

### Why is it needed?

[](#why-is-it-needed)

When building APIs there are specific formatting do's and dont's on how to send errors back to the user. Frameworks like Laravel are not build specifically for API builders. This small library just bridges that gap. For instance, specifications like [JSON API](https://jsonapi.org)have [guidelines for how errors should be formatted](http://jsonapi.org/format/#error-objects).

Installation
------------

[](#installation)

```
composer require iphuongtt/heimdal ~1.0
```

Add the service provider to `config/app.php`

```
// other providers...
Iphuongtt\Heimdal\Provider\LaravelServiceProvider::class,

```

Publish the configuration.

```
php artisan vendor:publish --provider="Iphuongtt\Heimdal\Provider\LaravelServiceProvider"

```

Add the exception handler to `bootstrap/app.php`

```
$app->singleton(
    Illuminate\Contracts\Debug\ExceptionHandler::class,
    Iphuongtt\Heimdal\ExceptionHandler::class
);

```

What does it do?
----------------

[](#what-does-it-do)

Imagine you have a piece of code that throws an `InvalidArgumentException`. This is a server error (500). It will parse through the flow described below.

```
1. Exception is thrown
2. The Exception is parsed through reports. A reporter is a class that reports the Exception. Log it in logs, send to external trackers like Sentry, Bugsnag etc.
3. The Exception is parsed through an appropriate formatter that formats the response in accordance to the error type.
4. The response is sent to the user.

```

### Is this not what Laravel does?

[](#is-this-not-what-laravel-does)

Yes, pretty much. However, if you want to report to something like Sentry you usually do this through something like Monolog. The problem with Monolog is that it is difficult to [pick up the response of the reporters](https://github.com/Seldaek/monolog/issues/651). For instance, Sentry reports back a unique ID for every reported exception which is extremely useful to give to the user, so they can give it to customer support. Heimdal supports this out-of-the-box by giving the response of all reporters to the formatter classes. This makes it trivial for formatters to use the response of the reporters in their final response to the user.

Second, Heimdal comes with sensible defaults as how different error types should be reported to the user. And makes it trivial to implement alternative responses for specific exception types.

Configuration
-------------

[](#configuration)

Heimdal has two things that should be configured: formatters and reporters.

### Reporters

[](#reporters)

You should determine where your exceptions should be reported to. Heimdal still calls the base report function in Laravel, so your exceptions will still be logged as normal. However, adding external reporting is easy. Heimdal comes with Sentry integration out of the box. To send exceptions to Sentry simply add this entry to the `reporters` section in `config/iphuongtt.heimdal.php`

```
'sentry' => [
    'class'  => \Iphuongtt\Heimdal\Reporters\SentryReporter::class,
    'config' => [
        'dsn' => '',
        // For extra options see https://docs.sentry.io/clients/php/config/
        // php version and environment are automatically added.
        'sentry_options' => []
    ]
]
```

Adding a custom reporter, for instance Bugsnag, is as simple as writing a small reporter class like this

```