sentry-php-sdk

What this skill does

> [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 '"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

```bash
# 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
<?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://[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):

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

```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 |

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