Advanced client configuration

Advanced BugSnag client usage for additional control over how and when BugSnag sends notifications.

Creating a custom client

To create a fully customized BugSnag integration, use the client constructor instead of the default make helper:

// Configuration options used
$config = new Bugsnag\Configuration("YOUR-API-KEY");
// Request resolver. The basic resolver resolves the current request.
$resolver = new Bugsnag\BasicResolver();
// Customizable HTTP client
$guzzle = new GuzzleHttp\Client(['timeout' => 30]);
$bugsnag = new Bugsnag\Client($config, $resolver, $guzzle);

At this point, the $bugsnag instance can be used directly to send error and exception reports. Each of the constructor arguments can be modified as needed to better suit your use case. Below are a few common examples.

Customizing transport

If you require using a proxy or a custom timeout length when sending error reports to BugSnag, you can create a Bugsnag\Client instance with a customized HTTP client via Guzzle. The example in creating a custom client would instead construct the $guzzle with additional parameters:

// Customizable HTTP client
$guzzle = new GuzzleHttp\Client([
    'timeout' => 30,
    'proxy' => 'tcp://localhost:8125',

Using Guzzle’s base_uri option to control the endpoint notifications are sent to has been deprecated in favour of using an environment variable or calling setNotifyEndpoint.

This avoids ambiguity between the different endpoints BugSnag uses for notifications, sessions and builds.

Customizing callbacks

After constructing a custom BugSnag client, you can register callbacks to collect information about the state of the application when the error occurred. To collect all of the metadata automatically collected by the default configuration in the integration guide, use registerDefaultCallbacks:


Alternately, you can select callbacks to register individually from the callbacks bundled into the library or create your own.

Modifying existing clients

A BugSnag client can be modified using the configuration options provided. The transport method of an existing client is immutable; to change the transport method (such as the endpoint or proxy), construct a new BugSnag client using the transport options.

Using BugSnag with php.ini

For capturing errors that may occur before the client initializes, such as E_COMPILE_ERROR or E_PARSE, a file declaring a shutdown handler can be registered before the application starts using the auto_prepend_file option its .ini configuration file.

This is not recommended for standard usage of any of the BugSnag PHP notifiers due to the behaviour being inconsistent across different configuration files and the possibility of it being removed in newer versions of PHP, but it can be used to report difficult to track issues such as when an out of memory error occurs.

An example of using BugSnag with an .ini file can be found in the examples folder of the main BugSnag PHP notifier.