Bugsnag-laravel

Bugsnag notifier for the Laravel PHP framework

View the Project on GitHub cfralick/bugsnag-laravel

Bugsnag Notifier for Laravel and Lumen

The Bugsnag Notifier for Laravel gives you instant notification of errors and exceptions in your Laravel PHP applications. We support Laravel 5, Laravel 4, Laravel 3, and Lumen.

Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing errors from your applications.

Check out this excellent Laracasts screencast for a quick overview of how to use Bugsnag with your Laravel apps.

How to Install

Laravel

  1. Install the bugsnag/bugsnag-laravel package

    $ composer require bugsnag/bugsnag-laravel:1.*

  2. Update config/app.php (or app/config/app.php for Laravel 4) to activate Bugsnag

    # Add `BugsnagLaravelServiceProvider` to the `providers` array
'providers' => array(
    ...
    'Bugsnag\BugsnagLaravel\BugsnagLaravelServiceProvider',
)

# Add the `BugsnagFacade` to the `aliases` array
'aliases' => array(
    ...
    'Bugsnag' => 'Bugsnag\BugsnagLaravel\BugsnagFacade',
)

  3. (Laravel 5 only) Use the Bugsnag exception handler from App/Exceptions/Handler.php.

    # DELETE this line
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
    # ADD this line instead
use Bugsnag\BugsnagLaravel\BugsnagExceptionHandler as ExceptionHandler;

    After this change, your file should look like this:

    <?php namespace App\Exceptions;

use Exception;
use Bugsnag\BugsnagLaravel\BugsnagExceptionHandler as ExceptionHandler;

class Handler extends ExceptionHandler {
    ...
}

Configuration (Laravel 5)

  1. Create a file config/bugsnag.php that contains your API key:

  2. Configure your api_key:

    <?php # config/bugsnag.php

return array(
    'api_key' => 'YOUR-API-KEY-HERE'
);

  3. Optionally, you can add the notify_release_stages key to the same file above to define which Laravel environments will send Exceptions to Bugsnag.

    return array(
    'api_key' => 'YOUR-API-KEY-HERE',
    'notify_release_stages' => ['production', 'staging']
);

Configuration (Laravel 3,4)

  1. Generate a template Bugsnag config file

    $ php artisan config:publish bugsnag/bugsnag-laravel

  2. Update app/config/packages/bugsnag/bugsnag-laravel/config.php with your Bugsnag API key:

    return array(
    'api_key' => 'YOUR-API-KEY-HERE'
);

  3. Optionally, you can add the notify_release_stages key to the same file above to define which Laravel environments will send Exceptions to Bugsnag.

    return array(
    'api_key' => 'YOUR-API-KEY-HERE',
    'notify_release_stages' => ['production', 'staging']
);

Lumen

  1. In bootstrap/app.php add the line

    $app->register('Bugsnag\BugsnagLaravel\BugsnagLaravelServiceProvider');

    just before the line 

    require __DIR__ . '/../app/Http/routes.php';

  2. Change the function report in app/Exceptions/Handler.php to look like this:

    public function report(Exception $e) {
    app('bugsnag')->notifyException($e, []);
    return parent::report($e);
}

  3. Create a file config/bugsnag.php that contains your API key

    <?php # config/bugsnag.php

return array(
    'api_key' => 'YOUR-API-KEY-HERE'
);

Sending Custom Data With Exceptions

It is often useful to send additional meta-data about your app, such as information about the currently logged in user, along with any error or exceptions, to help debug problems.

To send custom data, you should define a before-notify function, adding an array of "tabs" of custom data to the $metaData parameter. For example:

Bugsnag::setBeforeNotifyFunction("before_bugsnag_notify");

function before_bugsnag_notify($error) {
    // Do any custom error handling here

    // Also add some meta data to each error
    $error->setMetaData(array(
        "user" => array(
            "name" => "James",
            "email" => "james@example.com"
        )
    ));
}

See the setBeforeNotifyFunction documentation on the bugsnag-php library for more information.

Sending Custom Errors or Non-Fatal Exceptions

You can easily tell Bugsnag about non-fatal or caught exceptions by calling Bugsnag::notifyException:

Bugsnag::notifyException(new Exception("Something bad happened"));

You can also send custom errors to Bugsnag with Bugsnag::notifyError:

Bugsnag::notifyError("ErrorType", "Something bad happened here too");

Both of these functions can also be passed an optional $metaData parameter, which should take the following format:

$metaData =  array(
    "user" => array(
        "name" => "James",
        "email" => "james@example.com"
    )
);

Error Reporting Levels

By default we'll use the value of error_reporting from your php.ini or any value you set at runtime using the error_reporting(...) function.

If you'd like to send different levels of errors to Bugsnag, you can call setErrorReportingLevel, for example:

Bugsnag::setErrorReportingLevel(E_ALL & ~E_NOTICE);

Additional Configuration

The Bugsnag PHP Client is available as Bugsnag, which allows you to set various configuration options, for example:

Bugsnag::setReleaseStage("production");

See the Bugsnag Notifier for PHP documentation for full configuration details.

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:

https://github.com/bugsnag/bugsnag-laravel/issues

Contributing

License

The Bugsnag Laravel notifier is free software released under the MIT License. See LICENSE.txt for details.