Usage
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 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.
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:
$sentryClient = new Raven_Client('https://examplePublicKey@o0.ingest.sentry.io/0');
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:
$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.
If you want to report exceptions manually you can use the captureException function.
// Basic Reporting
$sentryClient->captureException($ex);
// Provide some additional data with an exception
$sentryClient->captureException($ex, array(
'extra' => array(
'php_version' => phpversion()
),
));
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.
// Capture a message
$sentryClient->captureMessage('my log message');
Note, captureMessage has a slightly different API than captureException to support parameterized formatting:
$sentryClient->captureMessage('my %s message', array('log'), array(
'extra' => array(
'foo' => 'bar',
),
));
With calls to captureException or captureMessage additional data can be supplied:
$sentryClient->captureException($ex, array(
'attr' => 'value',
));
extra
Additional context for this event. Must be a mapping. Children can be any native JSON type.
array(
'extra' => array('key' => 'value')
)
fingerprint
The fingerprint for grouping this event.
array(
'fingerprint' => ['{{ default }}', 'other value']
)
level
The level of the event. Defaults to error.
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.
array(
'logger' => 'default'
)
tags
Tags to index with this event. Must be a mapping of strings.
array(
'tags' => array('key' => 'value')
)
user
The acting user.
array(
'user' => array(
'id' => 42,
'email' => 'clever-girl'
)
)
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.
$sentryClient->getLastEventID();
To enable user feedback for crash reports, you will need to create an error handler which is aware of the last event ID.
<?php
$sentry = new \Raven_Client(https://examplePublicKey@o0.ingest.sentry.io/0);
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:
<!-- 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: "https://examplePublicKey@o0.ingest.sentry.io/0",
});
</script>
{% endif %}
That’s it!
For more details on this feature, see the User Feedback guide.
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:
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;
}
Sentry supports capturing breadcrumbs – events that happened prior to an issue.
$sentryClient->breadcrumbs->record(array(
'message' => 'Authenticating user as ' . $username,
'category' => 'auth',
'level' => 'info',
));
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.
$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;
}
});
In PHP its fairly common to use the suppression operator to avoid bubbling up handled errors:
$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:
$my_file = @file('non_existent_file');
if (!$my_file) {
// ...
$sentryClient->captureLastError();
}
The PHP client includes a simple helper script to test your connection and credentials with the Sentry master server:
bin/sentry test https://examplePublicKey@o0.ingest.sentry.io/0
Client configuration:
-> server: [https://sentry.io/api]
-> project: 0
-> public_key: examplePublicKey
Sending a test event:
-> event ID: f1765c9aed4f4ceebe5a93df9eb2d34f
Done!
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").