sentry-php-sdk

$27

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://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

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:

• 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)