This library detects errors and exceptions in your application and reports them to Rollbar for alerts, reporting, and analysis.
Supported PHP versions: 5.3, 5.4, 5.5, 5.6, 7, and HHVM (currently tested on 3.6.6).
<?phpuse \Rollbar\Rollbar;
use \Rollbar\Payload\Level;
// installs global error and exception handlers
Rollbar::init(
array(
'access_token' => ROLLBAR_TEST_TOKEN,
'environment' => 'production'
)
);
try {
thrownew \Exception('test exception');
} catch (\Exception$e) {
Rollbar::log(Level::error(), $e);
}
// Message at level 'info'
Rollbar::log(Level::info(), 'testing info level');
// With extra data (3rd arg) and custom payload options (4th arg)
Rollbar::log(
Level::info(),
'testing extra data',
array("some_key" => "some value") // key-value additional data
);
// If you want to check if logging with Rollbar was successful$response = Rollbar::log(Level::info(), 'testing wasSuccessful()');
if (!$response->wasSuccessful()) {
thrownew \Exception('logging with Rollbar failed');
}
// raises an E_NOTICE which will *not* be reported by the error handler$foo = $bar;
// will be reported by the exception handlerthrownew \Exception('testing exception handler');
?>Add rollbar/rollbar to your composer.json:
{
"require": {
"rollbar/rollbar": "~1.0.1"
}
}Keep in mind, that even if you're not using composer for your project (using composer.json), you will still need composer package to install rollbar-php dependencies.
- If you don't have composer yet, follow these instructions to get the package: install composer. It will be needed to install dependencies.
- Clone git repository rollbar/rollbar-php into a your external libraries path:
git clone https://github.com/rollbar/rollbar-php - Install rollbar-php dependencies:
cd rollbar-php && composer install && cd .. - Require rollbar-php in your PHP scripts:
require_once YOUR_LIBS_PATH . '/rollbar-php/vendor/autoload.php';
Add the following code at your application's entry point:
<?phpuse \Rollbar\Rollbar;
$config = array(
// required'access_token' => 'POST_SERVER_ITEM_ACCESS_TOKEN',
// optional - environment name. any string will do.'environment' => 'production',
// optional - path to directory your code is in. used for linking stack traces.'root' => '/Users/brian/www/myapp'
);
Rollbar::init($config);
?>Be sure to replace POST_SERVER_ITEM_ACCESS_TOKEN with your project's post_server_item access token, which you can find in the Rollbar.com interface.
This will install an exception handler (with set_exception_handler) and an error handler (with set_error_handler). If you'd rather not do that:
<?php$set_exception_handler = false;
$set_error_handler = false;
Rollbar::init($config, $set_exception_handler, $set_error_handler);
?>First, add the addon:
heroku addons:create rollbar:free
The access_token and root config variables will be automatically detected, so the config is simply:
<?phpuseRollbar\Rollbar;
Rollbar::init(array(
'environment' => 'production'
));
?>That's it! Uncaught errors and exceptions will now be reported to Rollbar.
If you'd like to report exceptions that you catch yourself:
<?phpuseRollbar\Rollbar;
useRollbar\Payload\Level;
try {
do_something();
} catch (\Exception$e) {
Rollbar::log(Level::error(), $e);
// or
Rollbar::log(Level::error(), $e, array("my" => "extra", "data" => 42));
}
?>You can also send Rollbar log-like messages:
<?phpuseRollbar\Rollbar;
useRollbar\Payload\Level;
Rollbar::log(Level::warning(), 'could not connect to mysql server');
Rollbar::log(
Level::info(), 'Here is a message with some additional data',
array('x' => 10, 'code' => 'blue')
);
?>Here is an example of how to use Rollbar as a handler for Monolog:
useMonolog\Logger;
useRollbar\Rollbar;
useRollbar\Payload\Level;
$config = array('access_token' => 'POST_SERVER_ITEM_ACCESS_TOKEN');
// installs global error and exception handlers
Rollbar::init($config);
$log = newLogger('test');
$log->pushHandler(new \Monolog\Handler\PsrHandler(Rollbar::logger()));
try {
thrownew \Exception('exception for monolog');
} catch (\Exception$e) {
$log->error($e);
}By default, payloads (batched or not) are sent as part of script execution. This is easy to configure but may negatively impact performance. With some additional setup, payloads can be written to a local relay file instead; that file will be consumed by rollbar-agent asynchronously. To turn this on, set the following config params:
<?php$config = array(
// ... rest of current config'handler' => 'agent',
'agent_log_location' => '/var/www'// not including final slash. must be writeable by the user php runs as.
);
?>You'll also need to run the agent. See the rollbar-agent docs for setup instructions.
All of the following options can be passed as keys in the $config array.
- access_token
- Your project access token.
- agent_log_location
- Path to the directory where agent relay log files should be written. Should not include final slash. Only used when handler is `agent`.
Default:
/var/www - base_api_url
- The base api url to post to.
Default:
https://api.rollbar.com/api/1/ - branch
- Name of the current branch.
Default:
master - capture_error_stacktraces
- Record full stacktraces for PHP errors.
Default:
true - checkIgnore
- Function called before sending payload to Rollbar, return true to stop the error from being sent to Rollbar.
Default:
nullParameters:
- $isUncaught: boolean value set to true if the error was an uncaught exception.
- $exception: a RollbarException instance that will allow you to get the message or exception
- $payload: an array containing the payload as it will be sent to Rollbar. Payload schema can be found at https://rollbar.com/docs/api/items_post/
$config = array( 'access_token' => '...', 'checkIgnore' => function ($isUncaught, $exception, $payload) { if (isset($_SERVER['HTTP_USER_AGENT']) && strpos($_SERVER['HTTP_USER_AGENT'], 'Baiduspider') !== false) { // ignore baidu spiderreturntrue; } // no other ignoresreturnfalse; }; ); Rollbar::init($config);
- code_version
- The currently-deployed version of your code/application (e.g. a Git SHA). Should be a string.
Default:
null - enable_utf8_sanitization
- set to false, to disable running iconv on the payload, may be needed if there is invalid characters, and the payload is being destroyed
Default:
true - environment
- Environment name, e.g. `'production'` or `'development'`
Default:
'production' - error_sample_rates
- Associative array mapping error numbers to sample rates. Sample rates are ratio out of 1, e.g. 0 is "never report", 1 is "always report", and 0.1 is "report 10% of the time". Sampling is done on a per-error basis.
Default: empty array, meaning all errors are reported.
- handler
- Either `'blocking'` or `'agent'`. `'blocking'` uses curl to send requests immediately; `'agent'` writes a relay log to be consumed by [rollbar-agent](https://github.com/rollbar/rollbar-agent).
Default:
'blocking' - host
- Server hostname.
Default:
null, which will result in a call togethostname()(orphp_uname('n')if that function does not exist) - include_error_code_context
- A boolean that indicates you wish to gather code context for instances of PHP Errors.
This can take a while because it requires reading the file from disk, so it's off by default.
Default:
false - include_exception_code_context
- A boolean that indicates you wish to gather code context for instances of PHP Exceptions.
This can take a while because it requires reading the file from disk, so it's off by default.
Default:
false - included_errno
- A bitmask that includes all of the error levels to report. E.g. (E_ERROR \| E_WARNING) to only report E_ERROR and E_WARNING errors. This will be used in combination with `error_reporting()` to prevent reporting of errors if `use_error_reporting` is set to `true`.
Default:
(E_ERROR | E_WARNING | E_PARSE | E_CORE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR) - logger
- An object that has a `log($level, $message)` method. If provided, will be used by RollbarNotifier to log messages.
- person
- An associative array containing data about the currently-logged in user. Required: `id`, optional: `username`, `email`. All values are strings.
- person_fn
- A function reference (string, etc. - anything that [call_user_func()](http://php.net/call_user_func) can handle) returning an array like the one for 'person'.
- root
- Path to your project's root dir
- scrub_fields
- Array of field names to scrub out of \_POST and \_SESSION. Values will be replaced with asterisks. If overriding, make sure to list all fields you want to scrub, not just fields you want to add to the default. Param names are converted to lowercase before comparing against the scrub list.
Default:
('passwd', 'password', 'secret', 'confirm_password', 'password_confirmation', 'auth_token', 'csrf_token') - shift_function
- Whether to shift function names in stack traces down one frame, so that the function name correctly reflects the context of each frame.
Default:
true - timeout
- Request timeout for posting to rollbar, in seconds.
Default:
3 - report_suppressed
- Sets whether errors suppressed with '@' should be reported or not
Default:
false - use_error_reporting
- Sets whether to respect current `error_reporting()` level or not
Default:
false - proxy
- Send data via a proxy server.
E.g. Using a local proxy with no authentication
<?php$config['proxy'] = "127.0.0.1:8080"; ?>
E.g. Using a local proxy with basic authentication
<?php$config['proxy'] = array( 'address' => '127.0.0.1:8080', 'username' => 'my_user', 'password' => 'my_password' ); ?>
Default: No proxy
Example use of error_sample_rates:
<?php$config['error_sample_rates'] = array(
// E_WARNING omitted, so defaults to 1E_NOTICE => 0.1,
E_USER_ERROR => 0.5,
// E_USER_WARNING will take the same value, 0.5E_USER_NOTICE => 0.1,
// E_STRICT and beyond will all be 0.1
);
?>Example use of person_fn:
<?phpfunctionget_current_user() {
if ($_SESSION['user_id']) {
returnarray(
'id' => $_SESSION['user_id'], // required - value is a string'username' => $_SESSION['username'], // optional - value is a string'email' => $_SESSION['user_email'] // optional - value is a string
);
}
returnnull;
}
$config['person_fn'] = 'get_current_user';
?>A Laravel-specific package is available for integrating with Laravel: Laravel-Rollbar
A CakePHP-specific package is avaliable for integrating with CakePHP 2.x: CakeRollbar
A Flow-specific package is available for integrating with Neos Flow: m12/flow-rollbar
If you run into any issues, please email us at support@rollbar.com
You can also find us in IRC: #rollbar on chat.freenode.net
For bug reports, please open an issue on GitHub.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Tests are in tests.
To run the tests: composer test
To fix code style issues: composer fix