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/sentrycomposer 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, ]);\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/1export 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"); }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-checkphp -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.
ProductNotFound
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);\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
ProductNotFound
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, ));$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']);$logger->error('Inventory import failed', ['feed' => 'warehouse']);
error monolog.inventory Inventory import failedBugsink preview: Monolog error
Log Entry
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());\Sentry\captureMessage('Inventory feed is stale', \Sentry\Severity::warning());
warning Inventory feed is staleBugsink preview: captured message
Log Entry
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');$scope->setTag('component', 'inventory');
inventoryBugsink preview: component tag
Tags
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, ]);$scope->setContext('checkout', [ 'sku' => $sku, 'quantity' => 1, ]);
php-handled 1Bugsink preview: structured context
Contexts
CHECKOUT
Breadcrumbs
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], );\Sentry\addBreadcrumb( category: 'checkout', message: 'Starting inventory reservation', metadata: ['sku' => $sku], );
Bugsink preview: breadcrumb
checkout
Starting inventory reservation
event time
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.
