sentry-php-sdk

by sentry

Full Sentry SDK setup for PHP. Use when asked to "add Sentry to PHP", "install sentry/sentry", "setup Sentry in PHP", or configure error monitoring, tracing,… npx skills add https://github.com/getsentry/sentry-for-claude --skill sentry-php-sdk Download ZIPGitHub232

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:

 $_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.

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)