All Skills > SDK Setup > PHP SDK

Sentry PHP SDK

PHPプロジェクトをスキャンして、Sentryの完全セットアップをガイドする意見反映型ウィザード。

このスキルを呼び出すタイミング

• ユーザーが「PHPにSentryを追加する」または「PHPアプリでSentryをセットアップする」を求める場合
• ユーザーがPHPでエラー監視、トレーシング、プロファイリング、ログ、メトリクス、またはcronを希望する場合
• ユーザーが sentry/sentry、sentry/sentry-laravel、sentry/sentry-symfony、またはSentry + 任意のPHPフレームワークについて言及する場合
• ユーザーがLaravelルート、Symfonyコントローラー、キュー、スケジュール済みタスク、または単純なPHPスクリプトを監視したい場合

注記: 以下のSDKバージョンとAPIは、執筆時のSentryドキュメント（sentry/sentry 4.x、sentry/sentry-laravel 4.x、sentry/sentry-symfony 5.x）を反映しています。 実装前に必ず docs.sentry.io/platforms/php/ で確認してください。

---

フェーズ 1: 検出

推奨を行う前にプロジェクトを理解するため、以下のコマンドを実行します。

# 既存のSentryを確認
grep -i sentry composer.json composer.lock 2>/dev/null

# フレームワークを検出
cat composer.json | grep -E '"laravel/framework"|"symfony/framework-bundle"|"illuminate/'

# ファイルシステムマーカーでフレームワークを確認
ls artisan 2>/dev/null && echo "Laravel detected"
ls bin/console 2>/dev/null && echo "Symfony detected"

# キューシステムを検出
grep -E '"laravel/horizon"|"symfony/messenger"' composer.json 2>/dev/null

# AIライブラリを検出
grep -E '"openai-php|"openai/|anthropic|llm' composer.json 2>/dev/null

# フロントエンド関連を確認
ls frontend/ resources/js/ assets/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'

注意すべき点:

• sentry/sentry (または -laravel / -symfony) は既に composer.json にありますか？ 既にある場合、init呼び出しが存在するかを確認します。機能設定が必要な場合があります。
• フレームワークが検出されましたか？ Laravel (artisan があり、composer.json に laravel/framework がある)、Symfony (bin/console があり、symfony/framework-bundle がある)、または 単純なPHP。
• キューシステムはありますか？ (Laravel Queue / Horizon、Symfony Messengerはキューワーカー設定が必要です。)
• AIライブラリはありますか？ (PHP AIの自動計測機能はまだありません — 必要な場合は手動で文書化します。)
• フロントエンド関連はありますか？ (フェーズ 4 での相互リンクのトリガーになります。)

---

フェーズ 2: 推奨

検出内容に基づいて、具体的な提案を提示します。開かれた質問をしないでください — 推奨で主導してください。

常に推奨 (コアカバレッジ):

• ✅ エラー監視 — ハンドルされていない例外とPHPエラーをキャプチャ
• ✅ ログ — Monolog統合 (Laravel/Symfony自動設定、単純なPHPは MonologHandler を使用)

検出時に推奨:

• ✅ トレーシング — Webフレームワークが検出されている場合 (Laravel/Symfony HTTP、DB、Twig/Blade、キャッシュを自動計測)
• ⚡ プロファイリング — パフォーマンスが重要な本番アプリケーション (excimer PHP拡張機能が必要、Linux/macOSのみ)
• ⚡ Crons — スケジューラーパターンが検出された場合 (Laravel Scheduler、Symfony Scheduler、カスタムcronジョブ)
• ⚡ メトリクス — ビジネスKPIまたはSLO追跡 (TraceMetrics APIを使用)

推奨マトリックス:

機能	推奨するタイミング	リファレンス
エラー監視	常に — 交渉不可能なベースライン	${SKILL_ROOT}/references/error-monitoring.md
トレーシング	Laravel/Symfony検出時、または手動スパンが必要な場合	${SKILL_ROOT}/references/tracing.md
プロファイリング	本番環境 + excimer 拡張機能が利用可能	${SKILL_ROOT}/references/profiling.md
ログ	常に; Laravel/SymfonyではMonolog	${SKILL_ROOT}/references/logging.md
メトリクス	ビジネスイベントまたはSLO追跡が必要	${SKILL_ROOT}/references/metrics.md
Crons	スケジューラーまたはcronパターンが検出された場合	${SKILL_ROOT}/references/crons.md

提案: 「エラー監視 + トレーシング [+ ログ] を推奨します。プロファイリング、Crons、メトリクスは必要ですか？」

---

フェーズ 3: ガイド

インストール

# 単純なPHP
composer require sentry/sentry "^4.0"

# Laravel
composer require sentry/sentry-laravel "^4.0"

# Symfony
composer require sentry/sentry-symfony "^5.0"

システム要件:

• PHP 7.2以降
• 拡張機能: ext-json、ext-mbstring、ext-curl (すべて必須)
• excimer PECL拡張機能 (Linux/macOSのみ — プロファイリングに必須)

フレームワーク固有の初期化

単純なPHP

\Sentry\init() をエントリーポイント (index.php、bootstrap.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

ステップ 1 — 例外ハンドラーを登録 (``bootstrap/app.php` で):

use Sentry\Laravel\Integration;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        Integration::handles($exceptions);
    })->create();

ステップ 2 — 設定を公開し、DSNを設定:

php artisan sentry:publish --dsn=YOUR_DSN

これにより config/sentry.php が作成され、SENTRY_LARAVEL_DSN が .env に追加されます。

ステップ 3 — .env を設定:

SENTRY_LARAVEL_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

Laravel設定オプションの詳細については、${SKILL_ROOT}/references/laravel.md を参照してください。

Symfony

ステップ 1 — バンドルを登録 (Symfony Flexにより自動実行):

Sentry\SentryBundle\SentryBundle::class => ['all' => true],

ステップ 2 — 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

ステップ 3 — .env でDSNを設定:

SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

Symfony設定オプションの詳細については、${SKILL_ROOT}/references/symfony.md を参照してください。

クイックスタート — 推奨init (単純なPHP)

最も多くの機能を有効にし、合理的なデフォルト値を持つ完全なinit:

\Sentry\init([
    'dsn'                     => $_SERVER['SENTRY_DSN'] ?? '',
    'environment'             => $_SERVER['SENTRY_ENVIRONMENT'] ?? 'production',
    'release'                 => $_SERVER['SENTRY_RELEASE'] ?? null,
    'send_default_pii'        => true,

    // トレーシング (高トラフィック本番環境では 0.1–0.2 に下げます)
    'traces_sample_rate'      => 1.0,

    // プロファイリング — excimer拡張機能が必要 (Linux/macOSのみ)
    'profiles_sample_rate'    => 1.0,

    // 構造化ログ (sentry/sentry >=4.12.0)
    'enable_logs'             => true,
]);

合意した各機能について

機能を1つずつウォークスルーします。リファレンスを読み込み、その手順に従い、次に進む前に検証します。

機能	リファレンスファイル	読み込むタイミング
エラー監視	${SKILL_ROOT}/references/error-monitoring.md	常に (ベースライン)
トレーシング	${SKILL_ROOT}/references/tracing.md	HTTPハンドラー / 分散トレーシング
プロファイリング	${SKILL_ROOT}/references/profiling.md	パフォーマンス重視の本番環境
ログ	${SKILL_ROOT}/references/logging.md	常に; Laravel/SymfonyではMonolog
メトリクス	${SKILL_ROOT}/references/metrics.md	ビジネスKPI / SLO追跡
Crons	${SKILL_ROOT}/references/crons.md	スケジューラー / cronパターンが検出された場合

各機能について: ${SKILL_ROOT}/references/<feature>.md を読み、手順に正確に従い、動作を検証します。

---

設定リファレンス

キー \Sentry\init() オプション (単純なPHP)

オプション	型	デフォルト	目的
dsn	string|bool|null	$_SERVER['SENTRY_DSN']	空または false の場合、SDKは無効化
environment	string|null	$_SERVER['SENTRY_ENVIRONMENT']	例: "staging"
release	string|null	$_SERVER['SENTRY_RELEASE']	例: "myapp@1.0.0"
send_default_pii	bool	false	リクエストヘッダー、クッキー、IPを含める
sample_rate	float	1.0	エラーイベントサンプルレート (0.0–1.0)
traces_sample_rate	float|null	null	トランザクションサンプルレート; null はトレーシング無効化
traces_sampler	callable|null	null	カスタムトランザクション別サンプリング (レートをオーバーライド)
profiles_sample_rate	float|null	null	トレースに対するプロファイリングレート; excimer が必要
enable_logs	bool	false	構造化ログをSentryに送信 (>=4.12.0)
max_breadcrumbs	int	100	イベントあたりの最大breadcrumb数
attach_stacktrace	bool	false	captureMessage() 時のスタックトレース
in_app_include	string[]	[]	アプリケーションに属するパスプレフィックス
in_app_exclude	string[]	[]	サードパーティコードのパスプレフィックス (トレース内で非表示)
ignore_exceptions	string[]	[]	レポートしない例外FQCN
ignore_transactions	string[]	[]	レポートしないトランザクション名
error_types	int|null	error_reporting()	PHPエラービットマスク (例: E_ALL & ~E_NOTICE)
capture_silenced_errors	bool	false	@ オペレーターで抑制されたエラーをキャプチャ
max_request_body_size	string	"medium"	"none" / "small" / "medium" / "always"
before_send	callable	identity	fn(Event $event, ?EventHint $hint): ?Event — ドロップするには null を返す
before_breadcrumb	callable	identity	fn(Breadcrumb $b): ?Breadcrumb — 破棄するには null を返す
trace_propagation_targets	string[]|null	null	sentry-trace ヘッダーを挿入する下流ホスト; null = すべて、[] = なし
strict_trace_continuation	bool	false	受信した分散トレースを継続するのは、sentry-org_id baggage がSDKの組織IDと一致する場合のみ。サードパーティのSentry計測サービスからのトレース汚染を防止 (>=4.21.0)
debug	bool	false	冗長なSDK出力 (構造化出力にはPSR-3 logger オプションを代わりに使用)

環境変数

変数	マップ先	注記
SENTRY_DSN	dsn	また $_SERVER['SENTRY_DSN']
SENTRY_ENVIRONMENT	environment
SENTRY_RELEASE	release	また $_SERVER['AWS_LAMBDA_FUNCTION_VERSION'] を読み取ります
SENTRY_SPOTLIGHT	spotlight

Laravel注記: SENTRY_LARAVEL_DSN を使用 (フォールバック: SENTRY_DSN)。その他のオプションは SENTRY_TRACES_SAMPLE_RATE、SENTRY_PROFILES_SAMPLE_RATE などに従います。

---

検証

Sentryがイベントを受け取っていることをテストします。

// 実際のエラーイベントをトリガー — 数秒以内にSentryダッシュボードで確認
throw new \Exception('Sentry PHP SDK test');

または、クラッシュしない確認:

\Sentry\captureMessage('Sentry PHP SDK test');

Laravel:

php artisan sentry:test

何も表示されない場合:

1. デバッグ出力を有効化:

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

2. DSNが正しいことを確認 (形式: https://<key>@o<org>.ingest.sentry.io/<project>)
3. SENTRY_DSN (または SENTRY_LARAVEL_DSN) 環境変数が実行中のプロセスで設定されていることを確認
4. キューワーカーの場合: Sentryがwebプロセスだけでなくワーカープロセス内部で初期化されていることを確認

---

フェーズ 4: 相互リンク

PHPセットアップ完了後、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"'

Sentryなしのフロントエンドが存在する場合、対応するスキルを提案:

検出されたフロントエンド	提案スキル
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue / Nuxt	@sentry/vue を使用 — docs.sentry.io/platforms/javascript/guides/vue/ を参照
その他のJS/TS	sentry-react-sdk (ジェネリックブラウザJSパターンをカバー)

---

トラブルシューティング

問題	解決方法
イベントが表示されない	logger オプション (DebugStdOutLogger) を有効化、DSNを確認、実行中のプロセス内の環境変数をチェック
形式が不正なDSNエラー	形式: https://<key>@o<org>.ingest.sentry.io/<project>
Laravelの例外がキャプチャされない	bootstrap/app.php に Integration::handles($exceptions) があることを確認
Symfonyの例外がキャプチャされない	config/bundles.php に SentryBundle が登録されていることを確認
トレースが表示されない	traces_sample_rate を設定 (null ではなく); 自動計測が有効になっていることを確認
プロファイリングが機能しない	excimer 拡張機能が必要 (Linux/macOSのみ、Windows では利用不可); traces_sample_rate > 0 が必要
enable_logs が機能しない	sentry/sentry >= 4.12.0、sentry/sentry-laravel >= 4.15.0、または sentry/sentry-symfony >= 5.4.0 が必要
キューワーカーのエラーが不足している	ワーカープロセス内でSentryを初期化します。webプロセスだけでなく; Laravelの場合、ワーカー .env で SENTRY_LARAVEL_DSN を使用
トランザクション数が多すぎる	traces_sample_rate を下げるか、traces_sampler を使用してヘルスチェックルートをドロップ
PIIがキャプチャされない	send_default_pii: true を設定; Laravelの場合、config/sentry.php で send_default_pii: true を設定
@ 抑制エラーが不足している	capture_silenced_errors: true を設定
クロスサービストレースが破損している	trace_propagation_targets をチェック; 下流サービスがSentryをインストールしていることを確認
サードパーティサービスからのトレース汚染	strict_trace_continuation: true を設定して、受信した sentry-org_id baggage がSDKの組織IDと一致する場合のみトレースを継続 (>=4.21.0)