---
title: Configuration
description: Configuration options for Honeybadger PHP and Laravel packages.
url: https://docs.honeybadger.io/lib/php/reference/configuration/
---

There are several ways to configure Honeybadger. See [Default Configuration](https://docs.honeybadger.io/lib/php/reference/configuration/#default-configuration) for all the options that are available.

## Creating a new client

In any PHP app, you can configure a new Honeybadger client directly via its constructor function:

```php
$honeybadger = Honeybadger\Honeybadger::new([
    'api_key' => 'PROJECT_API_KEY'
]);
```

Using Honeybadger this way is good for creating custom integrations or adding Honeybadger to frameworks which don’t have an official integration yet.

## Laravel/Lumen

In [Laravel](https://docs.honeybadger.io/lib/php/integration/laravel/) and [Lumen](https://docs.honeybadger.io/lib/php/integration/lumen/) apps, you should add your configuration to `config/honeybadger.php` instead.

In addition to the [default configuration](https://docs.honeybadger.io/lib/php/reference/configuration/#default-configuration) below, you can also define the [`middleware`](https://github.com/honeybadger-io/honeybadger-laravel/blob/master/config/honeybadger.php) option to enable or disable middleware that are automatically registered by the package. For example, the [`AssignRequestId`](https://github.com/honeybadger-io/honeybadger-laravel/blob/master/src/Middleware/AssignRequestId.php) middleware is registered by default, which assigns a unique request ID to each request. If you already have a way to assign request IDs in your app, you can disable this middleware.

## Default configuration

The default configuration options are shown below:

```php
[
    // Honeybadger API Key
    'api_key' => null,


    // Personal authentication token (needed to synchronize checkins from this configuration file)
    'personal_auth_token' => null,


    // The application environment
    'environment_name' => 'production',


    // To disable exception reporting, set this to false (or an expression that returns false).
    'report_data' => ! in_array(env('APP_ENV'), ['local', 'testing']),


    'environment' => [
        // Environment keys to filter before the payload sent to Honeybadger (see Environment Whitelist)
        'filter' => [],


        // Additional environment keys to include (see Environment Whitelist)
        'include' => [],
    ],


    'request' => [
        // Request keys to filter before the payload sent to Honeybadger
        'filter' => [
            'password',
            'password_confirmation'
        ],
    ],


    // Application version
    'version' => '',


    // System hostname
    'hostname' => gethostname(),


    // Project root (/var/www)
    'project_root' => '',


    'handlers' => [
        // Enable global exception handler
        'exception' => true,


        // Enable global error handler
        'error' => true,


        // Enable global shutdown handler
        'shutdown' => true,
    ],


    // Configure the underlying Guzzle client used
    'client' => [
        // Request timeout in seconds (default: 15s)
        'timeout' => 15,


        // Request proxy settings
        'proxy' => [
            // Use this proxy with 'http' (tcp://username:password@localhost:8125)
            'http'  => '',


            // Use this proxy with 'https' (tcp://username:password@localhost:8125)
            'https' => '',
        ],
    ],


    // Specify a custom endpoint
    'endpoint' => 'https://api.honeybadger.io',


    // Exclude exceptions from being reported
    'excluded_exceptions' => [],


    // Enable reporting deprecation warnings.
    'capture_deprecations' => false,


    // Specify how failures to reach Honeybadger should be handled
    'service_exception_handler' => function (\Honeybadger\Exceptions\ServiceException $e) {
        throw $e;
    },


    // Enable breadcrumbs
    'breadcrumbs' => [
        'enabled' => true,
    ],


    // Define your checkins here and synchronize them to Honeybadger
    'checkins' => [],


    // Configure Insights events reporting
    'events' => [
        'enabled' => false,
        'bulk_threshold' => BulkEventDispatcher::BULK_THRESHOLD,
        'dispatch_interval_seconds' => BulkEventDispatcher::DISPATCH_INTERVAL_SECONDS,
        'sample_rate' => 100 // Percentage of events to send
    ],
]
```

## Environment whitelist

All keys beginning with `HTTP_` are reported by default, as well as the following whitelisted keys:

```plaintext
'PHP_SELF'
'argv'
'argc'
'GATEWAY_INTERFACE'
'SERVER_ADDR'
'SERVER_NAME'
'SERVER_SOFTWARE'
'SERVER_PROTOCOL'
'REQUEST_METHOD'
'REQUEST_TIME'
'REQUEST_TIME_FLOAT'
'QUERY_STRING'
'DOCUMENT_ROOT'
'HTTPS'
'REMOTE_ADDR'
'REMOTE_HOST'
'REMOTE_PORT'
'REMOTE_USER'
'REDIRECT_REMOTE_USER'
'SCRIPT_FILENAME'
'SERVER_ADMIN'
'SERVER_PORT'
'SERVER_SIGNATURE'
'PATH_TRANSLATED'
'SCRIPT_NAME'
'REQUEST_URI'
'PHP_AUTH_DIGEST'
'PHP_AUTH_USER'
'PHP_AUTH_PW'
'AUTH_TYPE'
'PATH_INFO'
'ORIG_PATH_INFO'
'APP_ENV'
```

## Exceptions

If there is an error contacting Honeybadger a `\Honeybadger\Exceptions\ServiceException::class` will be thrown with a relevant exception message.

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)