sentry-php-sdk

All Skills > SDK Setup > PHP SDK

Sentry PHP SDK

Opinionated wizard that scans your PHP project and guides you through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to PHP" or "setup Sentry" in a PHP app
• User wants error monitoring, tracing, profiling, logging, metrics, or crons in PHP
• User mentions sentry/sentry, sentry/sentry-laravel, sentry/sentry-symfony, or Sentry + any PHP framework
• User wants to monitor Laravel routes, Symfony controllers, queues, scheduled tasks, or plain PHP scripts

Note: SDK versions and APIs below reflect Sentry docs at time of writing (sentry/sentry 4.x, sentry/sentry-laravel 4.x, sentry/sentry-symfony 5.x). Always verify against docs.sentry.io/platforms/php/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making recommendations:

# Check existing Sentry
grep -i sentry composer.json composer.lock 2>/dev/null

# Detect framework
cat composer.json | grep -E '"laravel/framework"|"symfony/framework-bundle"|"illuminate/'

# Confirm framework via filesystem markers
ls artisan 2>/dev/null && echo "Laravel detected"
ls bin/console 2>/dev/null && echo "Symfony detected"

# Detect queue systems
grep -E '"laravel/horizon"|"symfony/messenger"' composer.json 2>/dev/null

# Detect AI libraries
grep -E '"openai-php|"openai/|anthropic|llm' composer.json 2>/dev/null

# Check for companion frontend
ls frontend/ resources/js/ assets/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'

What to note:

• Is sentry/sentry (or -laravel / -symfony) already in composer.json? If yes, check if the init call exists — may just need feature config.
• Framework detected? Laravel (has artisan + laravel/framework in composer.json), Symfony (has bin/console + symfony/framework-bundle), or plain PHP.
• Queue system? (Laravel Queue / Horizon, Symfony Messenger need queue worker configuration.)
• AI libraries? (No PHP AI auto-instrumentation yet — document manually if needed.)
• Companion frontend? (Triggers Phase 4 cross-link.)

---

Phase 2: Recommend

Based on what you found, present a concrete proposal. Don't ask open-ended questions — lead with a recommendation:

Always recommended (core coverage):

• ✅ Error Monitoring — captures unhandled exceptions and PHP errors
• ✅ Logging — Monolog integration (Laravel/Symfony auto-configure; plain PHP uses MonologHandler)

Recommend when detected:

• ✅ Tracing — web framework detected (Laravel/Symfony auto-instrument HTTP, DB, Twig/Blade, cache)
• ⚡ Profiling — production apps where performance matters (requires excimer PHP extension, Linux/macOS only)
• ⚡ Crons — scheduler patterns detected (Laravel Scheduler, Symfony Scheduler, custom cron jobs)
• ⚡ Metrics — business KPIs or SLO tracking (beta; uses TraceMetrics API)

Recommendation matrix:

Feature	Recommend when...	Reference
Error Monitoring	Always — non-negotiable baseline	${SKILL_ROOT}/references/error-monitoring.md
Tracing	Laravel/Symfony detected, or manual spans needed	${SKILL_ROOT}/references/tracing.md
Profiling	Production + excimer extension available	${SKILL_ROOT}/references/profiling.md
Logging	Always; Monolog for Laravel/Symfony	${SKILL_ROOT}/references/logging.md
Metrics	Business events or SLO tracking needed (beta)	${SKILL_ROOT}/references/metrics.md
Crons	Scheduler or cron patterns detected	${SKILL_ROOT}/references/crons.md

Propose: "I recommend Error Monitoring + Tracing [+ Logging]. Want Profiling, Crons, or Metrics too?"

---

Phase 3: Guide

Install

# Plain PHP
composer require sentry/sentry "^4.0"

# Laravel
composer require sentry/sentry-laravel "^4.0"

# Symfony
composer require sentry/sentry-symfony "^5.0"

System requirements:

• PHP 7.2 or later
• Extensions: ext-json, ext-mbstring, ext-curl (all required)
• excimer PECL extension (Linux/macOS only — required for profiling)

Framework-Specific Initialization

Plain PHP

Place \Sentry\init() at the top of your entry point (index.php, bootstrap.php, or equivalent), before any application code:

<?php

require_once 'vendor/autoload.php';

\Sentry\init([
    'dsn'                  => $_SERVER['SENTRY_DSN'] ?? '',
    'environment'          => $_SERVER['SENTRY_ENVIRONMENT'] ?? 'production',
    'release'              => $_SERVER['SENTRY_RELEASE'] ?? null,
    'send_default_pii'     => true,
    'traces_sample_rate'   => 1.0,
    'profiles_sample_rate' => 1.0,
    'enable_logs'          => true,
]);

// rest of application...

Laravel

Step 1 — Register exception handler in bootstrap/app.php:

use Sentry\Laravel\Integration;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        Integration::handles($exceptions);
    })->create();

Step 2 — Publish config and set DSN:

php artisan sentry:publish --dsn=YOUR_DSN

This creates config/sentry.php and adds SENTRY_LARAVEL_DSN to .env.

Step 3 — Configure .env:

SENTRY_LARAVEL_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

For full Laravel configuration options, read ${SKILL_ROOT}/references/laravel.md.

Symfony

Step 1 — Register the bundle in config/bundles.php (auto-done by Symfony Flex):

Sentry\SentryBundle\SentryBundle::class => ['all' => true],

Step 2 — Create config/packages/sentry.yaml:

sentry:
    dsn: '%env(SENTRY_DSN)%'
    options:
        environment: '%env(APP_ENV)%'
        release: '%env(SENTRY_RELEASE)%'
        send_default_pii: true
        traces_sample_rate: 1.0
        profiles_sample_rate: 1.0
        enable_logs: true

Step 3 — Set the DSN in .env:

SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

For full Symfony configuration options, read ${SKILL_ROOT}/references/symfony.md.

Quick Start — Recommended Init (Plain PHP)

Full init enabling the most features with sensible defaults:

\Sentry\init([
    'dsn'                     => $_SERVER['SENTRY_DSN'] ?? '',
    'environment'             => $_SERVER['SENTRY_ENVIRONMENT'] ?? 'production',
    'release'                 => $_SERVER['SENTRY_RELEASE'] ?? null,
    'send_default_pii'        => true,

    // Tracing (lower to 0.1–0.2 in high-traffic production)
    'traces_sample_rate'      => 1.0,

    // Profiling — requires excimer extension (Linux/macOS only)
    'profiles_sample_rate'    => 1.0,

    // Structured logs (sentry/sentry >=4.12.0)
    'enable_logs'             => true,
]);

For Each Agreed Feature

Walk through features one at a time. Load the reference, follow its steps, verify before moving on:

Feature	Reference file	Load when...
Error Monitoring	${SKILL_ROOT}/references/error-monitoring.md	Always (baseline)
Tracing	${SKILL_ROOT}/references/tracing.md	HTTP handlers / distributed tracing
Profiling	${SKILL_ROOT}/references/profiling.md	Performance-sensitive production
Logging	${SKILL_ROOT}/references/logging.md	Always; Monolog for Laravel/Symfony
Metrics	${SKILL_ROOT}/references/metrics.md	Business KPIs / SLO tracking (beta)
Crons	${SKILL_ROOT}/references/crons.md	Scheduler / cron patterns detected

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key \Sentry\init() Options (Plain PHP)

Option	Type	Default	Purpose
dsn	string|bool|null	$_SERVER['SENTRY_DSN']	SDK disabled if empty or false
environment	string|null	$_SERVER['SENTRY_ENVIRONMENT']	e.g., "staging"
release	string|null	$_SERVER['SENTRY_RELEASE']	e.g., "myapp@1.0.0"
send_default_pii	bool	false	Include request headers, cookies, IP
sample_rate	float	1.0	Error event sample rate (0.0–1.0)
traces_sample_rate	float|null	null	Transaction sample rate; null disables tracing
traces_sampler	callable|null	null	Custom per-transaction sampling (overrides rate)
profiles_sample_rate	float|null	null	Profiling rate relative to traces; requires excimer
enable_logs	bool	false	Send structured logs to Sentry (>=4.12.0)
max_breadcrumbs	int	100	Max breadcrumbs per event
attach_stacktrace	bool	false	Stack traces on captureMessage()
in_app_include	string[]	[]	Path prefixes belonging to your app
in_app_exclude	string[]	[]	Path prefixes for third-party code (hidden in traces)
ignore_exceptions	string[]	[]	Exception FQCNs to never report
ignore_transactions	string[]	[]	Transaction names to never report
error_types	int|null	error_reporting()	PHP error bitmask (e.g., E_ALL & ~E_NOTICE)
capture_silenced_errors	bool	false	Capture errors suppressed by @ operator
max_request_body_size	string	"medium"	"none" / "small" / "medium" / "always"
before_send	callable	identity	fn(Event $event, ?EventHint $hint): ?Event — return null to drop
before_breadcrumb	callable	identity	fn(Breadcrumb $b): ?Breadcrumb — return null to discard
trace_propagation_targets	string[]|null	null	Downstream hosts to inject sentry-trace headers into; null = all, [] = none
strict_trace_continuation	bool	false	Only continue an incoming distributed trace if the sentry-org_id baggage matches the SDK's org ID; prevents trace contamination from third-party Sentry-instrumented services (>=4.21.0)
debug	bool	false	Verbose SDK output (use a PSR-3 logger option instead for structured output)

Environment Variables

Variable	Maps to	Notes
SENTRY_DSN	dsn	Also $_SERVER['SENTRY_DSN']
SENTRY_ENVIRONMENT	environment
SENTRY_RELEASE	release	Also reads $_SERVER['AWS_LAMBDA_FUNCTION_VERSION']
SENTRY_SPOTLIGHT	spotlight

Laravel note: Uses SENTRY_LARAVEL_DSN (falls back to SENTRY_DSN). Other options follow SENTRY_TRACES_SAMPLE_RATE, SENTRY_PROFILES_SAMPLE_RATE, etc.

---

Verification

Test that Sentry is receiving events:

// Trigger a real error event — check the Sentry dashboard within seconds
throw new \Exception('Sentry PHP SDK test');

Or for a non-crashing check:

\Sentry\captureMessage('Sentry PHP SDK test');

Laravel:

php artisan sentry:test

If nothing appears:

1. Enable debug output:

   \Sentry\init([
       'dsn' => '...',
       'logger' => new \Sentry\Logger\DebugStdOutLogger(),
   ]);
   

2. Verify the DSN is correct (format: https://<key>@o<org>.ingest.sentry.io/<project>)
3. Check SENTRY_DSN (or SENTRY_LARAVEL_DSN) env var is set in the running process
4. For queue workers: ensure Sentry is initialized inside the worker process, not just the web process

---

Phase 4: Cross-Link

After completing PHP setup, check for a companion frontend missing Sentry:

ls frontend/ resources/js/ assets/ public/ 2>/dev/null
cat package.json frontend/package.json 2>/dev/null \
  | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"'

If a frontend exists without Sentry, suggest the matching skill:

Frontend detected	Suggest skill
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue / Nuxt	Use @sentry/vue — see docs.sentry.io/platforms/javascript/guides/vue/
Other JS/TS	sentry-react-sdk (covers generic browser JS patterns)

---

Troubleshooting

Issue	Solution
Events not appearing	Enable logger option (DebugStdOutLogger), verify DSN, check env vars in the running process
Malformed DSN error	Format: https://<key>@o<org>.ingest.sentry.io/<project>
Laravel exceptions not captured	Ensure Integration::handles($exceptions) is in bootstrap/app.php
Symfony exceptions not captured	Verify SentryBundle is registered in config/bundles.php
No traces appearing	Set traces_sample_rate (not null); confirm auto-instrumentation is enabled
Profiling not working	excimer extension required (Linux/macOS only; not available on Windows); requires traces_sample_rate > 0
enable_logs not working	Requires sentry/sentry >= 4.12.0, sentry/sentry-laravel >= 4.15.0, or sentry/sentry-symfony >= 5.4.0
Queue worker errors missing	Init Sentry in the worker process itself, not just the web process; for Laravel use SENTRY_LARAVEL_DSN in worker .env
Too many transactions	Lower traces_sample_rate or use traces_sampler to drop health check routes
PII not captured	Set send_default_pii: true; for Laravel set send_default_pii: true in config/sentry.php
@-suppressed errors missing	Set capture_silenced_errors: true
Cross-service traces broken	Check trace_propagation_targets; ensure downstream services have Sentry installed
Trace contamination from third-party services	Set strict_trace_continuation: true to only continue traces where the incoming sentry-org_id baggage matches your SDK's org ID (>=4.21.0)