airbrake / phpbrake
Airbrake exception and error notifier for PHP
Installs: 1 562 674
Dependents: 28
Suggesters: 3
Security: 0
Stars: 48
Watchers: 14
Forks: 36
Open Issues: 12
Requires
- php: >=8.1
- cash/lrucache: ^1.0
- guzzlehttp/guzzle: >=6.3
Requires (Dev)
- mikey179/vfsstream: ^1.6
- monolog/monolog: ^1.22|^2.0
- phpunit/phpunit: ^10.0
- psy/psysh: ^0.11
- squizlabs/php_codesniffer: ^3.7
Suggests
- guzzlehttp/guzzle: Guzzle HTTP client
- dev-master / 1.0.x-dev
- v1.0.0
- v0.8.0
- v0.7.5
- v0.7.4
- v0.7.3
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.3
- v0.5.2
- v0.5.1
- v0.4.1
- v0.4.0
- v0.3.1
- v0.3.0
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1.0
- v0.0.12
- v0.0.11
- v0.0.10
- v0.0.9
- v0.0.8
- v0.0.7
- v0.0.6
- v0.0.5
- v0.0.4
- v0.0.3
- v0.0.2
- v0.0.1
- dev-pr/106
- dev-php-8.2
- dev-docker-php-8.2
- dev-circle-expand-coverage
- dev-wip/remote-config
This package is auto-updated.
Last update: 2024-09-19 00:42:00 UTC
README
PHPBrake
Features
PHPBrake is the official Airbrake PHP error notifier. PHPBrake supports PHP 8.2 and higher. PHPBrake includes many useful features that give you control over when and what you send to Airbrake, you can:
- Send notices from try-catch blocks in your code
- Add custom data to a notice
- Filter sensitive data from the notice
- Ignore specific exceptions
- Configure an error handler to capture uncaught exceptions
- Integrate with monolog
- Integrate with Laravel
- Integrate with CakePHP 3.x
- Integrate with Symfony
- Integrate with Zend
- and more
Installation
composer require airbrake/phpbrake
Quickstart
// Create new Notifier instance. $notifier = new Airbrake\Notifier([ 'projectId' => 12345, // FIX ME 'projectKey' => 'abcdefg' // FIX ME ]); // Set global notifier instance. Airbrake\Instance::set($notifier); // Register error and exception handlers. $handler = new Airbrake\ErrorHandler($notifier); $handler->register(); // Somewhere in the app... try { throw new Exception('hello from phpbrake'); } catch(Exception $e) { Airbrake\Instance::notify($e); }
API
Notifier API consists of 4 methods:
buildNotice
- builds Airbrake notice.sendNotice
- sends notice to Airbrake.notify
- shortcut forbuildNotice
andsendNotice
.addFilter
- adds filter that can modify and/or filter notices.
Adding custom data to the notice
$notifier->addFilter(function ($notice) { $notice['context']['environment'] = 'production'; return $notice; });
Filtering sensitive data from the notice
$notifier->addFilter(function ($notice) { if (isset($notice['params']['password'])) { $notice['params']['password'] = 'FILTERED'; } return $notice; });
Ignoring specific exceptions
$notifier->addFilter(function ($notice) { if ($notice['errors'][0]['type'] == 'MyExceptionClass') { // Ignore this exception. return null; } return $notice; });
Add user data to the notice
$notifier->addFilter(function ($notice) { $notice['context']['user']['name'] = 'Avocado Jones'; $notice['context']['user']['email'] = 'AJones@guacamole.com'; $notice['context']['user']['id'] = 12345; return $notice; });
Setting severity
Severity allows
categorizing how severe an error is. By default, it's set to error
. To
redefine severity, simply overwrite context/severity
of a notice object. For
example:
$notice = $notifier->buildNotice($e); $notice['context']['severity'] = 'critical'; $notifier->sendNotice($notice);
Error handler
Notifier can handle PHP errors, uncaught exceptions and shutdown. You can register appropriate handlers using following code:
$handler = new Airbrake\ErrorHandler($notifier); $handler->register();
Under the hood $handler->register
does following:
set_error_handler([$this, 'onError'], error_reporting()); set_exception_handler([$this, 'onException']); register_shutdown_function([$this, 'onShutdown']);
Laravel integration
See https://github.com/TheoKouzelis/laravel-airbrake
Symfony integration
See https://github.com/aminin/airbrake-bundle
CakePHP 3.x integration
See https://gist.github.com/mauriciovillalobos/01a97f9ee6179ad70b17d54f37cc5010
Zend Framework integration
See https://github.com/FrankHouweling/zend-airbrake
Monolog integration
$log = new Monolog\Logger('billing'); $log->pushHandler(new Airbrake\MonologHandler($notifier)); $log->addError('charge failed', ['client_id' => 123]);
Extra configuration options
appVersion
The version of your application that you can pass to differentiate exceptions between multiple versions. It's not set by default.
$notifier = new Airbrake\Notifier([ // ... 'appVersion' => '1.2.3', // ... ]);
host
By default, it is set to api.airbrake.io
. A host
is a web address containing a
scheme ("http" or "https"), a host and a port. You can omit the port (80 will be
assumed) and the scheme ("https" will be assumed).
$notifier = new Airbrake\Notifier([ // ... 'host' => 'errbit.example.com', // put your errbit host here // ... ]);
remoteConfig
Configures the remote configuration feature. Every 10 minutes the notifier will make a GET request to Airbrake servers to fetching a JSON document containing configuration settings for your project. The notifier will apply these new settings at runtime. By default, it is enabled.
To disable this feature, configure your notifier with:
$notifier = new Airbrake\Notifier([ // ... 'remoteConfig' => false, // ... ]);
Note: it is not recommended to disable this feature. It might negatively impact how your notifier works. Please use this option with caution.
rootDirectory
Configures the root directory of your project. Expects a String or a Pathname, which represents the path to your project. Providing this option helps us to filter out repetitive data from backtrace frames and link to GitHub files from our dashboard.
$notifier = new Airbrake\Notifier([ // ... 'rootDirectory' => '/var/www/project', // ... ]);
environment
Configures the environment the application is running in. Helps the Airbrake dashboard to distinguish between exceptions occurring in different environments. By default, it's not set.
$notifier = new Airbrake\Notifier([ // ... 'environment' => 'staging', // ... ]);
httpClient
Configures the underlying http client that must implement GuzzleHttp\ClientInterface
.
// Supply your own client. $client = new Airbrake\Http\GuzzleClient( new GuzzleHttp\Client(['timeout' => 3]) ); $notifier = new Airbrake\Notifier([ // ... 'httpClient' => $client, // ... ]);
Filtering keys
With keysBlocklist
option you can specify list of keys containing sensitive information that must be filtered out, e.g.:
$notifier = new Airbrake\Notifier([ // ... 'keysBlocklist' => ['/secret/i', '/password/i'], // ... ]);
Running tests
Run via docker:
docker compose run tests
Or run locally
composer install vendor/bin/phpunit
PHPDoc
composer require phpdocumentor/phpdocumentor vendor/bin/phpdoc -d src firefox output/index.html
Contact
In case you have a problem, question or a bug report, feel free to:
License
PHPBrake is licensed under The MIT License (MIT).