eonx-com/easy-bugsnag

Ease integrating bugsnag in your PHP projects

Introduction
Last Updated: 28/08/2020 05:28:36 - Edit on github

This package is a simple drop-in implementation of Bugsnag in your favourite PHP frameworks or plain PHP app.


Require package (Composer)

The recommended way to install this package is to use Composer:

$ composer require eonx-com/easy-bugsnag


Usage

Once installed in your favourite PHP framework, this package will allow you to inject the Bugsnag Client anywhere you like and start notifying your errors and exceptions:

// src/Exception/Handler.php

namespace App\Exception;

use Bugsnag\Client;

final class ExceptionHandler
{
    /**
     * @var \Bugsnag\Client
     */
    private $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function report(\Throwable $throwable): void
    {
        // Notify bugsnag of your throwable
        $this->client->notifyException($throwable);
    }
}


Client Factory

The core functionality of this package is to create a Bugsnag Client instance and make it available to your application, so you can focus on notifying your errors/exceptions instead of the boilerplate setup. To do so, it uses a factory.

This factory implements EonX\EasyBugsnag\Interfaces\ClientFactoryInterface which is able to create the client from just the api key you can find in your Bugsnag dashboard, handy! However, if needed you can set your own implementations of the additional objects used by the Bugsnag Client such as:

  • HttpClient: Guzzle Client used to send notifications to Bugsnag API
  • RequestResolver: used to resolve the request information
  • ShutdownStrategy: used to send bulk notifications while the application is shutting down


Configurators

Additionally, the client factory allows you to set a collection of "configurators". Once the client instantiated, the factory will loop through the configurators, providing them the client instance to be configured.

A configurator is a PHP class implementing EonX\EasyBugsnag\Interfaces\ClientConfiguratorInterface. When used within your favourite PHP framework, the configurators will be set on the factory for you so any created client will be configured before being injected into your services. Each configurator must define a priority, an integer value, which will be used to define the order of execution of the entire collection.

Here is an example of a configurator to set the release stage:

// src/Bugsnag/ReleaseStageConfigurator.php

namespace App\Bugsnag;

use Bugsnag\Client;
use EonX\EasyBugsnag\Configurators\AbstractClientConfigurator;

final class ReleaseStageConfigurator extends AbstractClientConfigurator
{
    public function configure(Client $bugsnag): void
    {
        $bugsnag->setReleaseStage('dev');
    }
}


Symfony
Last Updated: 28/08/2020 05:14:17 - Edit on github

Register Bundle

If you're using Symfony Flex, this step has been done automatically for you. If not, you can register the bundle yourself:

// config/bundles.php

return [
    // Other bundles ...

    EonX\EasyBugsnag\Bridge\Symfony\EasyBugsnagBundle::class => ['all' => true],
];


Configuration

The only required config is the api key from your Bugsnag organisation:

# config/packages/easy_bugsnag.yaml

easy_bugsnag:
    api_key: '%env(BUGSNAG_API_KEY)%'


Client Configurators In Symfony
Last Updated: 28/08/2020 05:14:17 - Edit on github

To register additional ClientConfigurators in Symfony, you simply need to register a new service implementing the EonX\EasyBugsnag\Interfaces\ClientConfiguratorInterface and you're done! This package register this interface for auto-configuration by default, so you have nothing else to worry about. You're welcome!



Doctrine ORM SQL Logger In Symfony
Last Updated: 28/08/2020 05:28:36 - Edit on github

To add SQL queries details to your Bugsnag reports in Symfony, you will need to update the configuration to enable this feature:

# config/packages/easy_bugsnag.yaml

easy_bugsnag:
    api_key: '%env(BUGSNAG_API_KEY)%'

    doctrine_dbal: true


Additionally, you can explicitly define the connections you want to log the queries for:

# config/packages/easy_bugsnag.yaml

easy_bugsnag:
    api_key: '%env(BUGSNAG_API_KEY)%'

    doctrine_dbal:
        enabled: true
        connections:
            - default
            - secure

That's it! Yes, for real... You are all setup to start logging SQL queries into your reports.



Laravel/Lumen
Last Updated: 28/08/2020 05:14:17 - Edit on github

Package Service Provider

Once the package required, you must tell your application to use it. Laravel uses service providers to do so, if you are not familiar with this concept make sure to have a look at the documentation.

// config/app.php

'providers' => [
    // Other Service Providers...

    \EonX\EasyBugsnag\Bridge\Laravel\EasyBugsnagServiceProvider::class,
],


Lumen Actions Required

To install this package in a Lumen application the procedures are a bit different.

Register Service Provider

In a Lumen application you must explicitly tell the application to register the package's service provider as following:

// bootstrap/app.php

$app = new Laravel\Lumen\Application(\dirname(__DIR__));

// Other actions...

$app->register(\EonX\EasyBugsnag\Bridge\Laravel\EasyBugsnagServiceProvider::class);


Configuration

The only required config is the api key from your Bugsnag organisation:

// config/easy-bugsnag.php

return [
    'api_key' => \env('BUGSNAG_API_KEY'),
]; 


Configuration in Lumen

In Lumen, you will need to explicitly call configure for this package:

// bootstrap/app.php

$app = new \Laravel\Lumen\Application(\realpath(\dirname(__DIR__)));

// ...

$app->configure('easy-bugsnag');

// ...


Client Configurators In Laravel
Last Updated: 28/08/2020 05:14:17 - Edit on github

To register additional ClientConfigurators in Laravel/Lumen, you will need to explicitly tag them within the service container.

Here is an example on how to add the Laravel version within the runtime versions.

Create Your ClientConfigurator

Create a class extending EonX\EasyBugsnag\Configurators\AbstractClientConfigurator, and add your logic:

// app/Bugsnag/RuntimeVersionConfigurator.php

namespace App\Bugsnag;

use Bugsnag\Client;
use EonX\EasyBugsnag\Configurators\AbstractClientConfigurator;
use Illuminate\Contracts\Foundation\Application;

final class RuntimeVersionConfigurator extends AbstractClientConfigurator
{
    /**
     * @var \Illuminate\Contracts\Foundation\Application
     */
    private $app;

    public function __construct(Application $app, ?int $priority = null) 
    {
        $this->app = $app;

        parent::__construct($priority);
    }

    public function configure(Client $client): void
    {
        $client->getConfig()->mergeDeviceData([
            'runtimeVersions' => ['laravel' => $this->app->version()],
        ]);
    }
}


Register It As A Service And Tag It

Then register your ClientConfigurator as a service and tag it using the EonX\EasyBugsnag\Bridge\BridgeConstantsInterface constant here for you. This should be done in a ServiceProvider:

// app/Providers/BugsnagServiceProvider.php

use App\Bugsnag\RuntimeVersionConfigurator;
use EonX\EasyBugsnag\Bridge\BridgeConstantsInterface; 
use Illuminate\Support\ServiceProvider;

final class BugsnagServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register your configurator as a service
        $this->app->singleton(RuntimeVersionConfigurator::class, function (): RuntimeVersionConfigurator {
            return new RuntimeVersionConfigurator($this->app); 
        });

        // Tag it as a ClientConfigurator
        $this->app->tag(RuntimeVersionConfigurator::class, [BridgeConstantsInterface::TAG_CLIENT_CONFIGURATOR]);
    }
}

Done! From now on, every Bugsnag Client created by the factory will have the laravel runtime version within its device metadata.



Doctrine ORM SQL Logger In Laravel
Last Updated: 28/08/2020 05:28:36 - Edit on github

Having the list of SQL queries executed during a request which triggered an error/exception to be notified is really important, it makes debugging easier. That's why easy-bugsnag got you sorted!

If your app is using Laravel/Lumen and Laravel Doctrine ORM, this section is for you.


Enable Logging In EasyBugsnag Config

To enable SQL queries logging into your Bugsnag reports, simply set the doctrine_orm config to true:

// config/easy-bugsnag.php

return [
    'api_key' => \env('BUGSNAG_API_KEY'),

    'doctrine_orm' => true,
]; 


Register SQL Logger Into Doctrine Config

Then you will need to register the SQL Logger from EasyBugsnag into Doctrine configuration:

// config/doctrine.php

return [
    // ...

    'logger' => EonX\EasyBugsnag\Bridge\Laravel\Doctrine\SqlOrmLogger::class,

    // ...
];