esportscz/sentry

Opinionated Sentry bootstrap for PHP apps, CLI scripts, workers & Nette framework - consistent tags, async flush, Tracy bridge with debug panel, env-based config.

2.1.2 2026-04-23 14:31 UTC

Requires

• php: ^7.2 || ^8.0
• ext-json: *
• sentry/sentry: ^4.0

Requires (Dev)

• nette/tester: ^2.4
• orisai/coding-standard: ^3.0
• phpstan/phpstan: ^1.0

Suggests

• nette/application: Required for Nette Application presenter context integration
• nette/di: Required to use SentryExtension for neon-based configuration
• nette/http: Required for Nette Session integration (session ID tag enrichment)
• nette/security: Required for Nette Security user identity integration
• tracy/tracy: Required to use SentryLogger and MultiLogger Tracy bridge

MIT

• eSports.cz, s.r.o.
• Michal Pospiech

• php
• cli
• bootstrap
• monitoring
• nette
• sentry
• tracy
• error-reporting
• error-tracking
• debug-panel
• async-flush
• glitchtip
• tracy-bar

README

Opinionated Sentry bootstrap for plain PHP apps, legacy codebases, CLI scripts, cron jobs, workers, and Nette Framework applications.

If DSN is missing or Sentry is disabled, initialization becomes a safe no-op.

What This Package Provides

• One unified Bootstrap::init() for web + CLI (non-Nette).
• Common, consistent tags and metadata (service, project, stack, PHP info, git commit, memory limit).
• Non-blocking async flush by default - on PHP-FPM the HTTP response is sent before Sentry flushes, so errors never add latency to the user-facing request.
• Configuration via environment variables, with optional per-key overrides in code.
• Safe context_provider hook - never blocks reporting if it throws.
• flush() helper for short-lived processes (CLI jobs, cron, workers).
• Nette Framework integration - DI extension, Tracy bridge, presenter/user/session enrichment, performance monitoring.
• Tracy Bar panel - real-time Sentry status, configuration overview, and captured events in the Tracy debug bar. Fully configurable via neon.

Installation

composer require esportscz/sentry

Quick Start

Plain PHP

use eSportsCZ\Sentry\Bootstrap;

Bootstrap::init([
    'service' => 'my-service', // treat as required
    'project' => 'my-project',
    'stack'   => 'php',
]);

Nette

extensions:
    sentry: eSportsCZ\Sentry\Nette\SentryExtension

sentry:
    dsn: %env.SENTRY_DSN%
    service: my-service
    project: my-project
    stack: php

No PHP bootstrap changes needed - the extension handles initialization automatically.

Documentation

• Configuration Reference - all config keys, env vars, defaults, automatic tags
• Nette Integration - DI extension, Tracy bridge, Application/Security/Session integrations, performance monitoring
• Helper Methods - setUser, tag, flush, configureScope, context_provider
• Troubleshooting - common issues, server saturation, timeout tuning
• Examples - full implementation examples for web, CLI, Nette, and worker

Requirements

• PHP ^7.2 || ^8.0 (tested up to PHP 8.4)
• sentry/sentry ^4.0

Nette integration requires PHP ^8.1 and nette/di ^3.2.

Versioning (SemVer)

• MAJOR - breaking API changes and/or a PHP version bump
• MINOR - backward-compatible features
• PATCH - backward-compatible bug fixes

See CHANGELOG.md for a full history of changes.

Contributing

Anyone can open a Pull Request. Please tag @michalpospiech as reviewer.