By Shalvah Adebayo
If you're building web applications and care about your users, Laravel breadcrumbs can help you debug why you're seeing an error, giving you greater insight into what users are experiencing. It's easy to take advantage of this feature and add breadcrumbs without much extra configuration, especially if you're already using Honeybadger. Here's a quick walkthrough.
How do breadcrumbs help you find problems?
A big part of debugging errors is wondering things like:
- "How did this exception happen?"
- "Why is this value null?"
- "Why is this user ID a String instead of an Integer?"
- "How did this parameter get dropped?"
- "What state is this user in?"
- "What methods were called before this exception was thrown?"
To help with common missing context problems like these, you've probably added extra logs to your app at some point. It's convenient to be able to reference them when something happens.
Log::debug("Processed payment request for $userId");
Log::debug("Sending notification to user $userId on channel $channel");
Logs like these are helpful, but they introduce a new problem to your Laravel project. These sorts of unstructured logs can be noisy and challenging to sort through.
Breadcrumbs let you replace those unstructured debugging logs with structured event records. Say goodbye to painful hours spent looking through some breadcrumbs file or log files to find out what was going on at 11:20 PM a few weeks ago. Record these events with Honeybadger, and you'll see the breadcrumbs right in the error detail on your dashboard:
Breadcrumbs associate extra context directly with errors so that you can see more than just an error message. You can send breadcrumbs manually in PHP with the Honeybadger client library, and we record many helpful breadcrumbs in Laravel automatically.
How to send breadcrumbs to Honeybadger in PHP
Recording a breadcrumb for Honeybadger in your PHP app is pretty straightforward. It's as simple as using the addBreadcrumb() method on the Honeybadger client and providing the breadcrumb title. You'll call the method with a message and associated context like this:
// Without Laravel
$honeybadger->addBreadcrumb('Sending notification', ['user' => $user->id, 'channel' => $channel]);
// With Laravel
Honeybadger::addBreadcrumb('Sending notification', ['user' => $user->id, 'channel' => $channel]);
It doesn't matter whether it's from a static page or something more complicated. If an error occurs at some point in future execution, the breadcrumb will show up in your dashboard like this:
If an error doesn't occur, the information doesn't pollute the rest of your logs. This example is perfect because the breadcrumb title indicates what might actually be the cause of the error without requiring changing any settings in a config file. Can you spot it?
In the screenshot above, you'll notice that the channel attribute is empty. In the code example, we set that value to $channel. The value being missing might be the cause of our error. While this is somewhat trivial, you can imagine how useful this information can become when displayed right alongside your reported errors.
Automatic Laravel breadcrumbs
Adding breadcrumbs manually is great, but it has one pretty big shortcoming. It requires that you have the foresight to add a breadcrumb where it might be needed without actually knowing you're going to have an error! To an extent, you can intelligently add useful bits of information throughout your codebase as breadcrumbs, but you're still likely to miss some useful information. If you knew you were going to have an error, you wouldn't need the breadcrumb because you would just fix it!
Fortunately for those of us using Laravel, there's a better option for breadcrumbs. If you're using Laravel, we'll automatically capture breadcrumbs for interesting events in your web application. The Honeybadger Laravel library automatically listens for the following events:
- Log messages
- View renders
- Email dispatches
- Job dispatches
- Notification dispatches
- Database queries
- Redis commands
- Incoming requests
All of this can be configured in the config/honeybadger.php configuration file. You can also turn off breadcrumb collection entirely if you prefer.
How can you use breadcrumbs in PHP?
Breadcrumbs are currently available in our PHP client as of version 2.8.0, and in our Laravel client as of version 3.8.0. You can update your Honeybadger client, our Laravel breadcrumbs package, by running:
composer update honeybadger-io/honeybadger-laravel
or by running:
composer update honeybadger-io/honeybadger-php
(depending on which you're using.)
What about breadcrumb categories?
Breadcrumbs have categories to help add visual context to your events. If you're adding breadcrumbs manually, you can use the following categories:
- custom
- error
- query
- job
- request
- render
- log
- notice
The error category is for errors or exceptions that get thrown, and these events will render breadcrumbs in red on the dashboard. You can use the custom category or actually create your own category for your own template, which will be displayed on the dashboard as if it belonged to the custom category. No need to change any config file! A Laravel breadcrumb is treated the same as the ones that come from vanilla PHP.
Let us know how it goes
We hope that breadcrumbs will be a helpful addition to your debugging toolbox. We find them to be a great source of context when debugging particularly tricky errors.
Try it out, and give our team a shout if there is anything you would like to see added. In Laravel, you can get started right away without extra configuration or even sending any events on your own! Check out our documentation for more details on using breadcrumbs in PHP.
