superbig/craft3-bugsnag

Log Craft errors/exceptions to Bugsnag.

Fund package maintenance!
verbb

Installs: 51 137

Dependents: 0

Suggesters: 0

Security: 0

Stars: 3

Watchers: 3

Forks: 9

Open Issues: 9

Type:craft-plugin

4.0.0 2022-07-19 13:33 UTC

This package is auto-updated.

Last update: 2022-11-23 01:00:55 UTC


README

Log Craft errors/exceptions to Bugsnag.

Installation

You can install Bugsnag via the plugin store, or through Composer.

Craft Plugin Store

To install Bugsnag, navigate to the Plugin Store section of your Craft control panel, search for Bugsnag, and click the Try button.

Composer

You can also add the package to your project using Composer and the command line.

  1. Open your terminal and go to your Craft project:
cd /path/to/project
  1. Then tell Composer to require the plugin, and Craft to install it:
composer require verbb/bugsnag && php craft plugin/install bugsnag

Configuring Bugsnag

  1. Copy the config.php configuration file into your craft/config folder as bugsnag.php.
  2. Update serverApiKey with an API key from your Bugsnag project.
  3. (Optionally) Set the releaseStage configuration setting to something. Defaults to production.

If you want to be able to capture early initialization errors, you need to add this plugin to your project's bootstrap configuration. To do this, in config/app.php, add the following:

'bootstrap' => [
    '\verbb\bugsnag\Bootstrap',
]

Blacklisting exceptions

If you want to ignore a certain type of exception, like a 404-error, you can do it like this:

<?php

use yii\web\NotFoundHttpException;

return [
    'blacklist' => [
        [
            'label' => '404 errors etc',
            'class' => function($exception) {
                if ($exception instanceof NotFoundHttpException && $exception->statusCode === 404) {
                    return false;
                }

                return true;
            },
        ],
    ],  
];

Using Bugsnag

It will automatically log most exceptions/errors. If you want to log an exceptions/error from a custom plugin, you may use the service methods:

  • For exceptions: Bugsnag::$plugin->getService()->handleException($exception);

Using Bugsnag on the frontend

You can log JavaScript errors on your site, by including the following in your Twig templates:

{% do view.registerAssetBundle('verbb\\bugsnag\\assetbundles\\frontend\\FrontEndAsset') %}

This currently uses v7.0.0 of the Bugsnag library.

You also need to set the browserApiKey setting.

If you'd rather include the Bugsnag client in your build and initialize it yourself, there is a helper method to get the browser config based on your plugin settings:

<script>
    const bugsnagConfig = { ...{{ craft.bugsnag.getBrowserConfig(true) }} }
</script>

The method takes one parameter, that toggles if it should return JSON or not.

Adding metadata from templates

If you want to send custom metadata with your request, you may do something like this:

{% do craft.bugsnag.metadata({ orderId: cart.id }) %}

Note that you have to call these methods before you include the JS bundle.

Throwing an exception from templates

You can trigger an exception from your templates.

{% do craft.bugsnag.handleException('Something went terribly wrong.') %}

Credits

Originally created by the team at Superbig.

Show your Support

Bugsnag is licensed under the MIT license, meaning it will always be free and open source – we love free stuff! If you'd like to show your support to the plugin regardless, Sponsor development.

68747470733a2f2f76657262622e696f2f6173736574732f696d672f76657262622d70696c6c2e737667