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

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? (laravel/ai is auto-instrumented by sentry/sentry-laravel >= 4.27.0 when tracing is enabled; other PHP AI libraries need manual spans.)
• 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)
• ✅ AI Monitoring — laravel/ai detected in a Laravel app (auto-instrumented in sentry/sentry-laravel >= 4.27.0)

Recommendation matrix:

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

Phase 3: Guide

Install

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:

Laravel

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

Step 2 — Publish config and set DSN:

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

Step 3 — Configure .env:

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

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

Step 3 — Set the DSN in .env:

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:

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:

Or for a non-crashing check:

Laravel:

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:

Troubleshooting