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

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:

1. Enable debug output:

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

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