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 (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 | ${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://[email protected]/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://[email protected]/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 | | 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., "[email protected]" | | 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:

Enable debug output:

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

Verify the DSN is correct (format: https://<key>@o<org>.ingest.sentry.io/<project>)
Check SENTRY_DSN (or SENTRY_LARAVEL_DSN) env var is set in the running process
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) |

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 (uses TraceMetrics API)

Recommendation matrix:

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://[email protected]/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://[email protected]/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:

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

Configuration Reference

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

Environment Variables

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:

Enable debug output:

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

Verify the DSN is correct (format: https://<key>@o<org>.ingest.sentry.io/<project>)
Check SENTRY_DSN (or SENTRY_LARAVEL_DSN) env var is set in the running process
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:

Adoption

getsentry/sentry-php-sdk

$ install --global

Security Scan Results

SKILL.md

Sentry PHP SDK

Invoke This Skill When

Phase 1: Detect

Phase 2: Recommend

Phase 3: Guide

Install

Framework-Specific Initialization

Plain PHP

Laravel

Symfony

Quick Start — Recommended Init (Plain PHP)

For Each Agreed Feature

Configuration Reference

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

Environment Variables

Verification

Phase 4: Cross-Link

Troubleshooting

Related Skills

getsentry/sentry-instrumentation-guide

getsentry/sentry-react-native-sdk

getsentry/sentry-python-sdk

getsentry/sentry-feature-setup

getsentry/sentry-php-sdk

$ install --global

Security Scan Results

SKILL.md

Sentry PHP SDK

Invoke This Skill When

Phase 1: Detect

Phase 2: Recommend

Phase 3: Guide

Install

Framework-Specific Initialization

Plain PHP

Laravel

Symfony

Quick Start — Recommended Init (Plain PHP)

For Each Agreed Feature

Configuration Reference

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

Environment Variables

Verification

Phase 4: Cross-Link

Troubleshooting

Related Skills

getsentry/sentry-instrumentation-guide

getsentry/sentry-react-native-sdk

getsentry/sentry-python-sdk

getsentry/sentry-feature-setup

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

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