sentry-php-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > 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/](https://docs.sentry.io/platforms/php/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making recommendations: ```bash # 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 '"(laravel/ai|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? (`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:** | 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` | | AI Monitoring | `laravel/ai` detected in a Laravel app, or manual PHP AI spans needed | `${SKILL_ROOT}/references/ai-monitoring.md` | Propose: *"I recommend Error Monitoring + Tracing [+ Logging]. Want Profiling, Crons, Metrics, or AI Monitoring too?"* --- ## Phase 3: Guide ### Install ```bash # Plain PHP composer require sentry/sentry "^4.0" # Laravel composer require sentry/sentry-laravel "^4.0" # Laravel with Laravel AI monitoring composer require sentry/sentry-laravel "^4.27.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 <?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`: ```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:** ```bash php artisan sentry:publish --dsn=YOUR_DSN ``` This creates `config/sentry.php` and adds `SENTRY_LARAVEL_DSN` to `.env`. **Step 3 — Configure `.env`:** ```ini 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): ```php Sentry\SentryBundle\SentryBundle::class => ['all' => true], ``` **Step 2 — Create `config/packages/sentry.yaml`:** ```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`:** ```ini 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: ```php \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 | | AI Monitoring | `${SKILL_ROOT}/references/ai-monitoring.md` | `laravel/ai` detected in Laravel, or manual PHP AI spans needed | 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 |