---
title: "Usage"
description: "Learn more about automatically reporting errors, exceptions, and rejections as well as how to manually capture errors and enable message capture."
url: https://docs.sentry.io/platforms/php/guides/laravel/usage/
---

# Usage | Sentry for Laravel

Sentry's SDK hooks into your runtime environment and automatically reports errors, exceptions, and rejections.

The most common form of capturing is to capture errors. What can be captured as an error varies by platform. In general, if you have something that looks like an exception it can be captured. For some SDKs you can also omit the argument to `capture_exception` and Sentry will attempt to capture the current exception. It can also be useful to manually report errors or messages to Sentry.

Separately to capture you can also record the breadcrumbs that lead up to an event. Breadcrumbs are different from events: they will not create an event in Sentry, but will be buffered until the next event is sent. Learn more about breadcrumbs in our [Breadcrumbs documentation](https://docs.sentry.io/platforms/php/guides/laravel/enriching-events/breadcrumbs.md).

## [Capturing Errors](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#capturing-errors)

In Laravel, you can pass an error object to `captureException()` to get it captured as an event. It’s also possible to throw strings as errors, in which case no traceback can be recorded.

In PHP you can either capture a caught exception or capture the last error with `captureLastError`.

```php
try {
    $this->functionFailsForSure();
} catch (\Throwable $exception) {
    \Sentry\captureException($exception);
}
```

## [Capturing Messages](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#capturing-messages)

Another common operation is to capture a bare message. A message is textual information that should be sent to Sentry. Typically, our SDKs don't automatically capture messages, but you can capture them manually.

Messages show up as issues on your issue stream, with the message as the issue name.

```php
\Sentry\captureMessage('Something went wrong');

// Optionally, specify a severity level.
// Supported levels: debug, info, warning, error, fatal.
\Sentry\captureMessage('Something went wrong', \Sentry\Severity::warning());
```

## [Customization](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#customization)

### [Decorating the Client Builder](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#decorating-the-client-builder)

Starting with version [`1.5.0`](https://github.com/getsentry/sentry-laravel/releases/tag/1.5.0) of [sentry-laravel](https://github.com/getsentry/sentry-laravel) you can customize how the PHP SDK client is built by modifying the client builder.

You might want to do this to, for example, replace the transport or change the serializer options used, which can only be changed when building the client.

The snippet below must be placed in the `register` method of a service provider (for example your `AppServiceProvider`).

In this example we increase `maxDepth` to 5 in for the default serializer.

```php
use Sentry\Serializer\Serializer;
use Sentry\ClientBuilderInterface;

$this->app->extend(ClientBuilderInterface::class, function (ClientBuilderInterface $clientBuilder) {
    $clientBuilder->setSerializer(new Serializer($clientBuilder->getOptions(), 5));

    return $clientBuilder;
});
```

### [User Context](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#user-context)

Starting with Laravel 5.3 we can automatically add the authenticated user id to the scope if `send_default_pii` option is set to `true` in your `config/sentry.php`.

The mechanism to add more user context to the scope will vary depending on which version of Laravel you're using, but the general approach is the same. Find a good entry point to your application in which the context you want to add is available, ideally early in the process.

In the following example, we'll use a middleware to add the user information if a user is logged in:

```php
namespace App\Http\Middleware;

use Closure;
use Sentry\State\Scope;

class SentryContext
{
    /**
     * Handle an incoming request.
     *
     * @param \Illuminate\Http\Request $request
     * @param \Closure                 $next
     *
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        if (auth()->check() && app()->bound('sentry')) {
            \Sentry\configureScope(function (Scope $scope): void {
                $scope->setUser([
                    'id' => auth()->user()->id,
                    'email' => auth()->user()->email,
                ]);
            });
        }

        return $next($request);
    }
}
```

### [Queue Jobs](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#queue-jobs)

When you have defined a `failed` method on your job class ([documentation](https://laravel.com/docs/8.x/queues#cleaning-up-after-failed-jobs)), that failed method acts as if your job runs inside a `try {} catch (\Exception $e) {}`. This will prevent reporting exception, causing the job to have failed to be reported to Sentry.

This could be expected since your job sometimes fails due to an API that is not reachable or other expected failures. If you still want the exception to be reported to Sentry, you can implement the following in your `failed` method:

```php
/**
 * The job failed to process.
 *
 * @param \Exception $exception
 *
 * @return void
 */
public function failed(\Exception $exception)
{
    // Send user notification of failure, etc...

    if (app()->bound('sentry')) {
        app('sentry')->captureException($exception);
    }
}
```

### [Resolve Name Conflicts](https://docs.sentry.io/platforms/php/guides/laravel/usage.md#resolve-name-conflicts)

If you have other packages also named Sentry, you'll need to create your own service provider extending ours so we can prevent naming conflicts.

```php
<?php

namespace App\Support;

class SentryLaravelServiceProvider extends \Sentry\Laravel\ServiceProvider
{
    public static $abstract = 'sentry-laravel';
}
```

You can then add this service provider to the `config/app.php`.

`config/app.php`

```php
'providers' => array(
    // ...
    App\Support\SentryLaravelServiceProvider::class,
)
```

Optionally, if you want to use the facade, you also need to extend/create a new facade.

```php
<?php

namespace App\Support;

class SentryLaravelFacade extends \Sentry\Laravel\Facade
{
    protected static function getFacadeAccessor()
    {
        return 'sentry-laravel';
    }
}
```

And add that facade to your `config/app.php`.

`config/app.php`

```php
'aliases' => array(
    // ...
    'SentryLaravel' => App\Support\SentryLaravelFacade::class,
)
```

After you've added your own service provider, running `php artisan vendor:publish --provider="App\Support\SentryLaravelServiceProvider"` publishes the Sentry config file to your chosen name (in the example above `config/sentry-laravel.php`) preventing conflicts with a `config/sentry.php` config file that might be used by the other package.

If you followed the regular installation instructions above (you should), make sure you replace `app('sentry')` with `app('sentry-laravel')`.

The namespace `\App\Support` can be anything you want in the examples above.

##### Note

If you're on Laravel 5.5+ the Sentry package is probably auto-discovered by Laravel. To solve this, add or append to the `extra` section in your `composer.json` file and run composer update/install afterward.

`composer.json`

```json
"extra": {
    "laravel": {
        "dont-discover": ["sentry/sentry-laravel"]
    }
}
```

## Pages in this section

- [Set the Level](https://docs.sentry.io/platforms/php/guides/laravel/usage/set-level.md)
- [SDK Fingerprinting](https://docs.sentry.io/platforms/php/guides/laravel/usage/sdk-fingerprinting.md)