Download the PHP package talentrydev/rollbar without Composer

layout: page sidebar: rollbar_sidebar permalink: /notifiers/rollbar-php/ toc: false

Rollbar notifier for PHP

This library detects errors and exceptions in your application and reports them to Rollbar for alerts, reporting, and analysis.

Table of Contents

• Quick start
• Installation
  • General
  • If Using Composer
• Setup
  • For Heroku Users
• Basic Usage
• Batching
• Using Monolog
• Configuration
  • Asynchronous Reporting
  • Configuration reference
• Related projects
• Help / Support
• Contributing

Quick start

Installation

General

Download rollbar.php and Level.php and put them together somewhere you can access.

If Using Composer

Add rollbar/rollbar to your composer.json:

Setup

Add the following code at your application's entry point:

Be sure to replace with your project's 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:

For Heroku Users

First, add the addon:

The access_token and root config variables will be automatically detected, so the config is simply:

Basic Usage

That's it! Uncaught errors and exceptions will now be reported to Rollbar.

If you'd like to report exceptions that you catch yourself:

You can also send Rollbar log-like messages:

Batching

By default, payloads are batched and sent to the Rollbar servers at the end of every script execution via a shutdown handler, or when the batch size reaches 50, whichever comes first. This works well in standard short-lived scripts, like serving web requests.

If you're using Rollbar in a long-running script, such as a Laravel project or a background worker, you may want to manually flush the batch. To flush, simply call:

For example, if using Laravel, add the above line to your App::after() event handler. Or in a looping background worker, call it at the end of each loop.

You can also tune the max batch size or disable batching altogether. See the batch_size and batched config variables, documented below.

Using Monolog

Here is an example of how to use Rollbar as a handler for Monolog:

Configuration

Asynchronous Reporting

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:

You'll also need to run the agent. See the rollbar-agent docs for setup instructions.

Configuration reference

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/`

batch_size

Flush batch early if it reaches this size. Default: `50`

batched

True to batch all reports from a single request together. Default: `true`

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: `null`
Parameters: * $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/

code_version

The currently-deployed version of your code/application (e.g. a Git SHA). Should be a string. Default: `null`

enable_utf8_sanizations

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 to `gethostname()` (or `php_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 Exeptions. 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 E.g. Using a local proxy with basic authentication Default: No proxy

Example use of error_sample_rates:

Example use of person_fn:

Related projects

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

Help / Support

If you run into any issues, please email us at [email protected]

You can also find us in IRC: #rollbar on chat.freenode.net

For bug reports, please open an issue on GitHub.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Tests are in tests. To run the tests: phpunit