Connect PHP to Bugsink

When a PHP application fails, Bugsink gives you the exception, stack trace, request, and application context you need to investigate it.

This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting an application and triggering a deliberate exception to confirm that it reaches Bugsink.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the SDK

Install the open-source Sentry PHP SDK with Composer. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:

composer require sentry/sentry

Configure your DSN

Initialize the SDK immediately after Composer’s autoloader. Reading the DSN from the environment keeps it out of source control:

\Sentry\init([
    'dsn' => getenv('SENTRY_DSN') ?: null,
]);

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export SENTRY_DSN=https://key@bugsink.example/1

Send a test error

Temporarily add an exception to a code path you can request:

if (!isset($inventory[$sku])) {
    http_response_code(500);
    throw new ProductNotFound("Product {$sku} is not in inventory");
}

Start the application with its DSN, then request that code path once:

php -S 127.0.0.1:8080 -t public
:::bash
curl http://127.0.0.1:8080/checkout/php-setup-check

The exception still follows PHP’s normal error path. The SDK reports it to Bugsink before the request finishes.

See the error in Bugsink

Open your Bugsink project. The new ProductNotFound issue contains the request and points at the PHP line which raised the exception.

Bugsink preview

That’s it: your PHP application is connected. Remove the deliberate exception; future uncaught exceptions after Sentry\init() will be reported automatically.

Capture other kinds of errors

Unhandled exceptions arrive automatically. You can also report exceptions your code catches, Monolog records, and exceptional conditions that do not have an exception.

Handled exceptions

Handled exceptions let your application recover while still preserving the original type and stack in Bugsink. Call captureException() inside the catch block after deciding that the failure is worth reporting:

\Sentry\captureException($exception);

The response remains under your application’s control; this example returns a conflict response while Bugsink receives the exception.

Bugsink preview: handled exception
Bugsink preview

Monolog records

Monolog records become Bugsink events when you add the PHP SDK’s issue handler to a channel. This example names the channel inventory, forwards records at ERROR and above, and includes the record’s context:

$logger = new Logger('inventory');
$logger->pushHandler(new LogToSentryIssueHandler(
    hub: \Sentry\SentrySdk::getCurrentHub(),
    level: Level::Error,
    fillExtraContext: true,
));

An ordinary error call now creates an issue with the Monolog channel, severity, message, and feed context:

$logger->error('Inventory import failed', ['feed' => 'warehouse']);

Bugsink preview: Monolog error
Bugsink preview

Messages without exceptions

A message creates a Bugsink event without an exception. Use captureMessage() for a noteworthy condition such as a stale import feed, and pass the severity you want Bugsink to show. Prefer exceptions when a useful stack exists:

\Sentry\captureMessage('Inventory feed is stale', \Sentry\Severity::warning());

Bugsink preview: captured message
Bugsink preview

Add useful context

An exception tells you what failed; context helps explain why. Use withScope() around one operation so its data is attached to that event without leaking into later requests in a long-running PHP process.

Tags

Tags make events searchable by short key/value pairs. Bugsink already records standard values such as environment and release; add your own component, region, tenant plan, or feature flag with setTag():

$scope->setTag('component', 'inventory');

Bugsink preview: component tag
Bugsink preview

Structured context

Structured context adds a named group of details you want to inspect but do not need to search. setContext() creates a Checkout section containing the SKU and requested quantity on the event:

$scope->setContext('checkout', [
    'sku' => $sku,
    'quantity' => 1,
]);

Bugsink preview: structured context
Bugsink preview

Breadcrumbs record what happened before an error without creating a separate issue. Add one for a domain step the SDK cannot observe itself, such as starting a reservation or retrying an external inventory service:

\Sentry\addBreadcrumb(
    category: 'checkout',
    message: 'Starting inventory reservation',
    metadata: ['sku' => $sku],
);

Bugsink preview: breadcrumb
Bugsink preview

Exception arguments

PHP omits function arguments from exception traces when zend.exception_ignore_args is enabled. Set it to Off in php.ini if those arguments help debugging, after considering whether they may contain secrets or personal data.

The SDK still reports source files, line numbers, and code context while this setting is on; only the values passed into stack frames are absent.

PHP frameworks and applications

Framework integrations capture failures in their normal request, command, or plugin lifecycle and add the relevant PHP context automatically.