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

What this package provides
Installation
Required environment variables
Quick start
- Web apps (plain PHP / non-Nette)
- CLI jobs / cron (always use flush)
Configuration reference
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

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:

Tag	Value
`php.version`	PHP version string
`sapi`	PHP SAPI (fpm-fcgi, cli, …)
`php.memory_limit`	Value of `memory_limit` from php.ini
`git.commit`	First non-empty value from `BITBUCKET_COMMIT` → `GIT_COMMIT` → `CI_COMMIT_SHA`; omitted if none is set
`url`	Full request URL (scheme + host + path + query); omitted in CLI

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.

esportscz / sentry

Maintainers

Package info

Statistics

Security