---
title: "Usage"
url: https://docs.sentry.io/platforms/php/legacy-sdk/usage/
---

# Usage | Sentry for PHP

##### Deprecation Warning

A new PHP SDK has superseded this deprecated version. Sentry preserves this documentation for customers using the old client. If you are using PHP 7.1 or later, we recommend using the [updated PHP SDK](https://docs.sentry.io/platforms/php.md) for your projects.

Using Sentry with PHP is straightforward. After installation of the library you can directly interface with the client and start submitting data.

## [Basics](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#basics)

The most important part is the creation of the raven client. Create it once and reference it from anywhere you want to interface with Sentry:

```php
$sentryClient = new Raven_Client('___PUBLIC_DSN___');
```

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

Sentry includes basic functionality for reporting any uncaught exceptions or PHP errors. This is done via the error handler, and appropriate hooks for each of PHP’s built-in reporting:

```php
$error_handler = new Raven_ErrorHandler($sentryClient);
$error_handler->registerExceptionHandler();
$error_handler->registerErrorHandler();
$error_handler->registerShutdownFunction();
```

##### Note

Calling `install()` on a Raven\_Client instance will automatically register these handlers.

## [Reporting Exceptions](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#reporting-exceptions)

If you want to report exceptions manually you can use the *captureException* function.

```php
// Basic Reporting
$sentryClient->captureException($ex);

// Provide some additional data with an exception
$sentryClient->captureException($ex, array(
    'extra' => array(
        'php_version' => phpversion()
    ),
));
```

## [Reporting Other Errors](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#reporting-other-errors)

Sometimes you don’t have an actual exception object, but something bad happened and you want to report it anyways. This is where *captureMessage* comes in. It takes a message and reports it to sentry.

```php
// Capture a message
$sentryClient->captureMessage('my log message');
```

Note, `captureMessage` has a slightly different API than `captureException` to support parameterized formatting:

```php
$sentryClient->captureMessage('my %s message', array('log'), array(
    'extra' => array(
        'foo' => 'bar',
    ),
));
```

## [Optional Attributes](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#optional-attributes)

With calls to `captureException` or `captureMessage` additional data can be supplied:

```php
$sentryClient->captureException($ex, array(
    'attr' => 'value',
));
```

`extra`

Additional context for this event. Must be a mapping. Children can be any native JSON type.

```php
array(
    'extra' => array('key' => 'value')
)
```

`fingerprint`

The fingerprint for grouping this event.

```php
array(
    'fingerprint' => ['{{ default }}', 'other value']
)
```

`level`

The level of the event. Defaults to `error`.

```php
array(
    'level' => 'warning'
)
```

Sentry is aware of the following levels:

* debug (the least serious)
* info
* warning
* error
* fatal (the most serious)

`logger`

The logger name for the event.

```php
array(
    'logger' => 'default'
)
```

`tags`

Tags to index with this event. Must be a mapping of strings.

```php
array(
    'tags' => array('key' => 'value')
)
```

`user`

The acting user.

```php
array(
    'user' => array(
        'id' => 42,
        'email' => 'clever-girl'
    )
)
```

## [Getting Back an Event ID](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#getting-back-an-event-id)

An event id is a globally unique id for the event that was just sent. This event id can be used to find the exact event from within Sentry.

This is often used to display for the user and report an error to customer service.

```php
$sentryClient->getLastEventID();
```

## [User Feedback](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#user-feedback)

To enable user feedback for crash reports, you will need to create an error handler which is aware of the last event ID.

```php
<?php

$sentry = new \Raven_Client(___PUBLIC_DSN___);

public class App {
    function error500($exc) {
        $event_id = $sentry->captureException($exc);

        return $this->render('500.html', array(
            'sentry_event_id' => $event_id,
        ), 500);
    }
}
```

Then in your template you can load up the feedback widget:

```html
<!-- Sentry JS SDK 2.1.+ required -->
<script src="https://cdn.ravenjs.com/2.3.0/raven.min.js"></script>

{% if sentry_event_id %}
<script>
  Raven.showReportDialog({
    eventId: "{{ sentry_event_id }}",

    // use the public DSN (don't include your secret!)
    dsn: "___PUBLIC_DSN___",
  });
</script>
{% endif %}
```

That’s it!

For more details on this feature, see the [*User Feedback guide*](https://docs.sentry.io/platforms/php/user-feedback.md).

## [Handling Failures](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#handling-failures)

The SDK attempts to minimize failures, and when they happen will always try to avoid bubbling them up to your application. If you do want to know when an event fails to record, you can use the `getLastError` helper:

```php
if ($sentryClient->getLastError() !== null) {
    echo "Something went very, very wrong";
    // $sentryClient->getLastError() contains the error that occurred
} else {
    // Give the user feedback
    echo "Sorry, there was an error!";
    echo "Your reference ID is " . $event_id;
}
```

## [Breadcrumbs](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#breadcrumbs)

Sentry supports capturing breadcrumbs – events that happened prior to an issue.

```php
$sentryClient->breadcrumbs->record(array(
    'message' => 'Authenticating user as ' . $username,
    'category' => 'auth',
    'level' => 'info',
));
```

## [Filtering Out Errors](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#filtering-out-errors)

Its common that you might want to prevent automatic capture of certain areas. Ideally you simply would avoid calling out to Sentry in that case, but that’s often easier said than done. Instead, you can provide a function which the SDK will call before it sends any data, allowing you both to mutate that data, as well as prevent it from being sent to the server.

```php
$sentryClient->setSendCallback(function($data) {
    $ignore_types = array('Symfony\Component\HttpKernel\Exception\NotFoundHttpException');

    if (isset($data['exception']) && in_array($data['exception']['values'][0]['type'], $ignore_types))
    {
        return false;
    }
});
```

## [Error Control Operators](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#error-control-operators)

In PHP its fairly common to use the [suppression operator](https://php.net/manual/en/language.operators.errorcontrol.php) to avoid bubbling up handled errors:

```php
$my_file = @file('non_existent_file');
```

In these situations, Sentry will never capture the error. If you wish to capture it at that stage you’d need to manually call out to the PHP client:

```php
$my_file = @file('non_existent_file');
if (!$my_file) {
    // ...
    $sentryClient->captureLastError();
}
```

## [Testing Your Connection](https://docs.sentry.io/platforms/php/legacy-sdk/usage.md#testing-your-connection)

The PHP client includes a simple helper script to test your connection and credentials with the Sentry master server:

```bash
bin/sentry test ___PUBLIC_DSN___
Client configuration:
-> server: [___API_URL___]
-> project: ___PROJECT_ID___
-> public_key: ___PUBLIC_KEY___

Sending a test event:
-> event ID: f1765c9aed4f4ceebe5a93df9eb2d34f

Done!
```