README

Opinionated Sentry bootstrap for plain PHP apps, legacy codebases, CLI scripts, cron jobs, workers, and custom apps that are NOT running on the Nette framework.

Requires: PHP ^7.2 || ^8.0 (tested up to PHP 8.4) · sentry/sentry ^4.0

Table of Contents

• What this package provides
• Installation
• Required environment variables
• Quick start
  • Web apps (plain PHP / non-Nette)
  • CLI jobs / cron (always use flush)
• Configuration reference
  • Identification tags
  • Sentry runtime control
  • Sampling
  • Privacy / PII
  • Ignoring exceptions
  • Sanitization / filtering
  • Advanced SDK options
  • Context hook
• Helper methods
• Recommended tag standard
• Troubleshooting
• Versioning (SemVer)
• Contributing

What this package provides

• One unified Bootstrap::init() for web + CLI (non-Nette only).
• 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 overrides in code.
• Safe context_provider hook (never breaks reporting if it throws).
• flush() helper for short-lived processes (CLI jobs, cron, workers).

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

Installation

composer require esportscz/sentry

Required environment variables

Minimum required:

• SENTRY_DSN — DSN from Sentry project settings

Recommended:

• SENTRY_ENABLED — 1 / 0 (default: 1)
• APP_ENV — production / staging / dev (fallback: SENTRY_ENVIRONMENT)
• SENTRY_SAMPLE_RATE — error event sampling (0..1, default: 1.0)
• SENTRY_TRACES_SAMPLE_RATE — tracing sampling (0..1, optional; enable only if you want performance monitoring)
• SENTRY_SEND_DEFAULT_PII — true/false (default: false)
• APP_VERSION or BITBUCKET_COMMIT — used for release autodetection
• SENTRY_HTTP_TIMEOUT — total HTTP request timeout in seconds (default: 5)
• SENTRY_HTTP_CONNECT_TIMEOUT — TCP connection timeout in seconds (default: 2)

Quick start

Web apps (plain PHP / non-Nette)

Initialize as early as possible (e.g., public/index.php, bootstrap.php):

use eSportsCZ\Sentry\Bootstrap;

require __DIR__ . '/../vendor/autoload.php';

Bootstrap::init([
	'service' => 'my-service', // recommended as company standard (treat as required)
	'project' => 'my-project', // recommended
	'stack'   => 'php',        // e.g. "php", "legacy", "cli", "worker"
]);

If SENTRY_DSN is missing or SENTRY_ENABLED=0, init() returns null and does nothing.

CLI jobs / cron (always use flush)

Short-lived processes can exit before Sentry sends events. Always flush:

use eSportsCZ\Sentry\Bootstrap;

Bootstrap::init([
	'service' => 'my-service',
	'stack'   => 'cli',
]);

try {
	// job logic...
} catch (\Throwable $e) {
	\Sentry\captureException($e);
	Bootstrap::flush(2);
	throw $e;
}

Bootstrap::flush(2);

Configuration reference

Bootstrap::init(array $config) supports these keys:

Automatically set tags

These tags are set on every event without any configuration:

Identification tags (recommended)

• service (string) — application/service name (recommended as required)
• project (string) — project/module name (recommended)
• stack (string) — app type (e.g., php, legacy, cli, worker)

Sentry runtime control

• enabled (bool) — explicit on/off (fallback: SENTRY_ENABLED)
• dsn (string) — DSN override (fallback: SENTRY_DSN)
• environment (string) — override (fallback: APP_ENV / SENTRY_ENVIRONMENT)
• release (string) — override (fallback: autodetect)
• server_name (string) — override (fallback: HOSTNAME / SENTRY_SERVER_NAME)
• log_url (bool) — whether to log the request URL as a url tag (default: true)
• trust_proxy_headers (bool) — whether to read URL from X-Forwarded-Proto / X-Forwarded-Host headers (default: false)
  • Enable only when the app runs behind a trusted reverse proxy (Nginx, load balancer, CDN).
  • Do not enable on apps exposed directly to the internet — clients could spoof these headers.
  • When enabled: scheme is taken from X-Forwarded-Proto, host from X-Forwarded-Host (falls back to HTTP_HOST).
• async_flush (bool) — send HTTP response before flushing to Sentry (default: true)
  • On PHP-FPM: calls fastcgi_finish_request() in a shutdown handler so errors never add latency to the user-facing request.
  • On CLI: shutdown handler runs normally after the script exits — no effect on behavior.
  • Set to false only if you need synchronous flushing (e.g. custom shutdown order).
• flush_timeout (int) — seconds the shutdown handler waits for Sentry to deliver queued events (default: 2)
  • Lower values free PHP-FPM workers faster when the Sentry endpoint is slow or rate-limiting. Some events may be dropped if the endpoint is too slow.
• http_connect_timeout (int) — TCP connect timeout in seconds (fallback: SENTRY_HTTP_CONNECT_TIMEOUT, default: 2)
• http_timeout (int) — total HTTP request timeout in seconds (fallback: SENTRY_HTTP_TIMEOUT, default: 5)

Sampling

• sample_rate (float 0..1) — error event sampling (fallback: SENTRY_SAMPLE_RATE, default 1.0)
• traces_sample_rate (float 0..1) — tracing sampling (fallback: SENTRY_TRACES_SAMPLE_RATE, optional)

Privacy / PII

• send_default_pii (bool) — whether PII is sent (default false)
  • Recommendation: keep disabled by default and enable only when explicitly needed.

Ignoring exceptions

• ignore_exceptions (array) — exception classes to ignore

Sanitization / filtering

• redact_keys (string[]) — keys to mask in request data (password, token, authorization, etc.)
• drop_environments (string[]) — environments where events should be dropped (e.g., ['dev'])

Advanced SDK options (use carefully)

• options (array) — raw merge into Sentry SDK options - Sentry docs - options
  • ⚠️ Use only keys that sentry/sentry supports.

Context hook

• context_provider (callable) — receives Sentry\State\Scope to enrich tags/extras

Example:

Bootstrap::init([
	'service' => 'my-service',
	'context_provider' => function (\Sentry\State\Scope $scope): void {
		$scope->setTag('workspace_id', '123');
		$scope->setExtra('request_id', 'abc-xyz');
	},
]);

If context_provider throws, it is swallowed to ensure error reporting is never blocked.

Helper methods

Set user

Bootstrap::setUser([
	'id' => '123',
	'email' => 'user@example.com',
]);

Only use this when PII is allowed (send_default_pii=true) and you have the proper legal/security justification.

Add a tag

Bootstrap::tag('request_id', 'abc-123');

Flush events

Bootstrap::flush(2);

Use in CLI / workers / anything that may terminate quickly.

Recommended tag standard

• service — service/application name (required)
• project — project/module name
• stack — php / legacy / cli / worker
• environment — production / staging / dev
• release — commit hash / version identifier

Troubleshooting

Nothing is being sent

Check:

• SENTRY_DSN is set and non-empty
• SENTRY_ENABLED is not 0
• you are not in an environment listed in drop_environments
• for CLI jobs, you call Bootstrap::flush()

Server saturation / PHP-FPM workers occupied by error reporting

If your Sentry/GlitchTip endpoint is slow, overloaded, or rate-limiting requests, PHP-FPM workers can be occupied by the post-response flush even though the HTTP response was already sent via async_flush. Tune these knobs:

Bootstrap::init([
    'service'         => 'my-service',
    // Drop to 1 s: fail fast if GlitchTip can't accept a connection
    'http_connect_timeout' => 1,
    // Drop to 3 s: give up on slow responses sooner
    'http_timeout'         => 3,
    // Give up flushing after 2 s — workers are freed quickly even under load
    'flush_timeout'        => 2,
    // Only send 20 % of errors — reduces volume to Sentry/GlitchTip
    'sample_rate'          => 0.2,
]);

Or via environment variables (no code change required):

SENTRY_HTTP_CONNECT_TIMEOUT=1
SENTRY_HTTP_TIMEOUT=3
SENTRY_SAMPLE_RATE=0.2

Note: flush_timeout is not an SDK option and cannot be set via env var — set it in Bootstrap::init().

I need a specific Sentry SDK option

Use the options key:

Bootstrap::init([
	'service' => 'my-service',
	'options' => [
		'max_breadcrumbs' => 50,
	],
]);

Only include options supported by sentry/sentry (Sentry options).

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.