jenssegers/rollbar
A Laravel wrapper for the Rollbar PHP notifier that sends exceptions and logs to Rollbar, registers a service provider and facade, and provides publishable configuration for quick error-monitoring setup.
Do the version check before you type composer require. This package's ceiling is Laravel 5.x / PHP 7.x (v1.5.1 was the Laravel 5.4 bump, and upstream is archived in favor of rollbar/rollbar-laravel). If the app is Laravel 8+/PHP 8, the illuminate/support constraint will not resolve — stop here and use the official SDK. If it's an inherited Laravel 5.x monolith already paying for Rollbar, this is a half-day wire-up. That decision comes first, because everything below assumes the version fits.
Install and pin the exact version.
composer require jenssegers/rollbar:1.5.1
Don't use ^1.5. There is no upstream maintenance, so a caret constraint only buys you a surprise one day.
Register the provider and facade. On Laravel 5.5+ auto-discovery handles it. On 5.4 and below, add to config/app.php:
'providers' => [
Jenssegers\Rollbar\RollbarServiceProvider::class,
],
'aliases' => [
'Rollbar' => Jenssegers\Rollbar\Facades\Rollbar::class,
],
Confirm the facade namespace against src/Facades/ of the version you pinned — that path has moved between releases.
Publish the config and set environment variables.
php artisan vendor:publish --provider="Jenssegers\Rollbar\RollbarServiceProvider"
# .env.production
ROLLBAR_ACCESS_TOKEN=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
ROLLBAR_ENVIRONMENT=production
# .env.local
ROLLBAR_ACCESS_TOKEN=
ROLLBAR_ENVIRONMENT=local
Separate tokens per environment, never hardcoded, never shared. An empty token in local and test is how you avoid burning quota on your own dd() throwaways.
First use case: prove the pipe is real. This package fails silently — a bad token or blocked egress gives you zero errors and zero warnings, and the dashboard looks healthy. Ten minutes here is worth more than any later instrumentation:
// routes/web.php — temporary, staging only
Route::get('/rollbar-smoke', function () {
throw new \RuntimeException('Rollbar smoke test — delete me');
});
Hit the route, then confirm the item shows up in Rollbar under the correct environment. If it doesn't, walk token → environment name → network egress → composer.lock resolution before writing any integration code.
Where to look first in the codebase: config/rollbar.php for the knobs, and App\Exceptions\Handler::report() for where production value actually originates. Those two files are the whole integration surface for day-to-day work.
The package hooks Laravel's exception handler, so the highest-value change is often deleting code. Keep App\Exceptions\Handler::report() focused and let uncaught exceptions flow through:
public function report(Exception $e)
{
if ($this->shouldReport($e) && auth()->check()) {
\Rollbar::configure(['person' => [
'id' => (string) auth()->id(),
'email' => auth()->user()->email,
]]);
}
parent::report($e);
}
Resist sprinkling \Rollbar::reportException($e) through controllers and services. Every scattered call site is a call site you rewrite when you migrate.
This is the single move that makes the package's abandonment survivable. Product code should never see the Rollbar facade.
namespace App\Support;
interface ErrorReporter
{
public function report(\Throwable $e, array $context = []): void;
public function message(string $msg, array $context = []): void;
}
namespace App\Support;
use Jenssegers\Rollbar\Facades\Rollbar;
class RollbarReporter implements ErrorReporter
{
public function report(\Throwable $e, array $context = []): void
{
Rollbar::reportException($e, $context);
}
public function message(string $msg, array $context = []): void
{
Rollbar::reportMessage($msg, $context);
}
}
Bind it in a service provider and inject ErrorReporter where needed. When you move to rollbar/rollbar-laravel, you write one new class and change one binding. Verify the argument order against the pinned rollbar-php — the second parameter is extra data in some versions, not a flat context array.
The places worth an explicit report are where an exception would otherwise vanish: queued jobs that swallow after retries, webhook handlers that must return 200 regardless, and cron-driven console commands.
public function handle(StripeWebhook $event)
{
try {
$this->process($event);
} catch (\Throwable $e) {
$this->reporter->report($e, [
'webhook_id' => $event->id,
'event_type' => $event->type,
]);
// Still return 200 so Stripe doesn't retry-storm us.
}
}
Report once, add context once, then either rethrow or degrade. Don't report and rethrow and log — you'll get three copies in three systems.
error and aboveThe package registers a Monolog handler alongside the exception hook, so Log::error() and Log::critical() reach Rollbar for free. Keep the config level set at error or warning — dropping it to debug on a chatty app is a fast route to quota exhaustion and unusable triage.
Log::error('Payment reconciliation mismatch', [
'invoice_id' => $invoice->id,
'expected' => $expected,
'actual' => $actual,
]);
Structured context arrays survive into the payload as custom fields. String concatenation does not.
person_fn, not middlewareperson_fn in config/rollbar.php is the cleanest hook — evaluated at report time, so it works uniformly for HTTP, queued jobs, and console commands, and you don't have to remember to call configure() in report().
'person_fn' => function () {
return auth()->check()
? ['id' => (string) auth()->id(), 'email' => auth()->user()->email]
: null;
},
Errors without a version are archaeology. Set ROLLBAR_ENVIRONMENT per environment and populate a release SHA from the deploy script so an error spike correlates to a deploy — the answer to "was this us, just now?"
Once wired, the day-to-day pattern is: Rollbar dashboard filtered by environment and release SHA → group by stack trace → pull person and custom fields to reproduce → assign to owning team via your issue tracker. Because structured context lands as custom fields, a single query like invoice_id:12345 becomes the fastest way to trace a report back to a real customer.
Silent failure is the default failure mode. Bad token, blocked egress, misconfigured environment name, or a swallowed handler — all produce zero telemetry and zero alerts. Keep the smoke-test route (behind auth, in staging) or add an artisan command that reports a synthetic message and asserts on the API response. Treat "no errors in Rollbar" as a claim to verify, not a fact.
Check for a competing handler before you install. If Sentry, Ignition, Telescope, or a custom reporter already owns App\Exceptions\Handler, you now have two chains racing — duplicate quota burn and incoherent triage. Pick exactly one owner and document it. Telescope in particular will make it look like reporting works when only Telescope sees it.
The transport is synchronous on the error path. This is the biggest operational trap. During an error storm, every request blocks on an HTTPS POST to Rollbar before it can return a 500 — latency cascades into a full outage. Mitigate with a short timeout, sampling, and payload caps:
'timeout' => 2, // do not let Rollbar be your slowest dependency
'max_items' => 10, // cap array/collection items in payloads
'sample_rate' => 0.25, // verify the exact key your rollbar-php version honors
Run a synthetic error burst against staging and measure the latency delta before canarying to production. Don't skip this.
Scrub before any production traffic. Error payloads carry request bodies, headers, cookies, session IDs, query bindings, and PII. scrub_fields in config/rollbar.php must be verified to actually reach the SDK — a wrapper that overrides payload shaping could bypass it. Have someone sign off on the field list; a missing scrub field is a compliance incident, not a bug. Separate tokens per environment contain a leak and make rotation surgical.
Composer conflicts are likely, not exceptional. Expect friction on illuminate/support and on the transitive rollbar-php version. Resolve it before committing a sprint — a composer update that quietly pulls a newer rollbar-php with different config semantics can change your payloads without a code change. Commit composer.lock, and keep config/rollbar.php keys (access_token, environment, level, scrub_fields, person_fn, max_items, batch_size) aligned with the official SDK's names so the eventual swap is a config diff rather than a redesign.
Disable it in local and test. A null or empty access_token plus a transmit-style off switch keeps your test suite from making outbound HTTP calls and keeps your tinker sessions out of production triage. If the pinned version doesn't honor an empty token gracefully, guard provider registration by environment.
The Rollbar alias can collide. It's a short, generic global name — check it doesn't shadow anything, and prefer importing the FQCN or, better, using ErrorReporter so the alias never appears in product code.
Extension points are thin, and that's the point. person_fn, the config array, and the registered Monolog handler are essentially the whole surface. Anything more sophisticated — custom payload shaping, batching, per-tenant token routing — lives in rollbar-php and you're fighting the wrapper to reach it. Needing multi-tenant token routing or advanced sampling is a signal to move to the official SDK, not to patch this one.
File the migration ticket on the day it ships, not after the first incident. Every future Laravel upgrade is blocked until the wrapper is replaced. Keeping ErrorReporter in place makes it a one-class substitution; keeping the config keys aligned makes it a config diff. The migration is cheap only if you built for it on day one.
How can I help you explore Laravel packages today?