README

Thin wrapper around the Sentry PHP SDK with a clean interface, typed value objects, and a NullSentryClient for environments where Sentry is disabled.

Installation

composer require compono-kit/sentry-client

Quick start

use ComponoKit\SentryClient\SentryClient;
use ComponoKit\SentryClient\SentryClientConfig;

$client = new SentryClient(new SentryClientConfig([
    'dsn'             => 'https://key@o123.ingest.sentry.io/456',
    'environment'     => 'production',
    'release'         => 'my-app@2.1.0',
    'error-reporting' => E_ALL,
    'display-errors'  => false,
]));

$client->install(); // applies error_reporting + display_errors

Dependency injection

Depend on the interface, not the concrete class:

use ComponoKit\SentryClient\Interfaces\InformsSentry;

class OrderService
{
    public function __construct(private InformsSentry $sentry) {}

    public function place(Order $order): void
    {
        try {
            // ...
        } catch (\Throwable $exception) {
            $this->sentry->captureException($exception);
            throw $exception;
        }
    }
}

In tests or CLI tools where Sentry should be silent, pass a NullSentryClient instead:

use ComponoKit\SentryClient\NullSentryClient;

$service = new OrderService(new NullSentryClient());

Capturing events

Exception

use ComponoKit\SentryClient\Models\Types\Severity;

$client->captureException($exception);

// with severity
$client->captureException($exception, Severity::fatal());

Message

use ComponoKit\SentryClient\Models\Types\Message;
use ComponoKit\SentryClient\Models\Types\Severity;

$client->captureMessage(new Message('Queue depth exceeded threshold'), Severity::warning());

Last PHP error

@file_get_contents('/missing/file');

$client->captureLastError();                       // severity defaults to error
$client->captureLastError(Severity::warning());

Enriching events

Tags

Tags are global — they appear on every event sent after useTags() is called.

use ComponoKit\SentryClient\Models\Tags;

$client->useTags(Tags::fromKeyValueArray([
    'app'     => 'checkout-service',
    'version' => '2.1.0',
]));

User

Like tags, the user context sticks until changed.

use ComponoKit\SentryClient\Models\User;

$client->setUser(new User(
    id:        (string) $user->id,
    email:     $user->email,
    username:  $user->name,
));

Context

Context is per-event — it does not leak into subsequent captures.

use ComponoKit\SentryClient\Models\Context;
use ComponoKit\SentryClient\Models\ContextEntry;
use ComponoKit\SentryClient\Models\ContextGroup;

$context = new Context([
    new ContextGroup('order', [
        new ContextEntry('id',     '#1042'),
        new ContextEntry('amount', '149.90 EUR'),
    ]),
]);

$client->captureException($exception, Severity::error(), $context);
$client->captureMessage(new Message('Payment declined'), Severity::warning(), $context);

You can also build context from a plain array:

$context = Context::fromKeyValueArray([
    'order'   => ['id' => '#1042', 'amount' => '149.90 EUR'],
    'payment' => ['provider' => 'stripe', 'status' => 'declined'],
]);

Breadcrumbs

Breadcrumbs recorded before a capture appear as a trail in the Sentry issue.

use ComponoKit\SentryClient\Models\Breadcrumb;

$client->addBreadcrumb(new Breadcrumb('User clicked checkout',    'ui',   'info'));
$client->addBreadcrumb(new Breadcrumb('Sending payment request',  'http', 'debug', ['url' => '/pay']));
$client->addBreadcrumb(new Breadcrumb('Payment gateway timeout',  'http', 'error'));

$client->captureException($exception);

Breadcrumb signature: (message, category = 'default', level = 'info', data = [])

Fingerprint

Controls how Sentry groups events. Two events with the same fingerprint become one issue.

use ComponoKit\SentryClient\Models\Fingerprint;

$client->captureException(
    $exception,
    Severity::error(),
    null,
    new Fingerprint('PaymentService', 'timeout'),
);

Custom config via interface

Implement ConfiguresSentryClient to load credentials from any source (env vars, config files, secrets manager, …):

use ComponoKit\SentryClient\Interfaces\ConfiguresSentryClient;
use ComponoKit\SentryClient\Models\Types\Dsn;
use ComponoKit\SentryClient\Models\Types\Environment;
use ComponoKit\SentryClient\Models\Types\Release;

class EnvSentryConfig implements ConfiguresSentryClient
{
    public function getDsn(): Dsn                   { return new Dsn($_ENV['SENTRY_DSN']); }
    public function getEnvironment(): Environment   { return new Environment($_ENV['APP_ENV']); }
    public function getRelease(): Release           { return new Release($_ENV['APP_VERSION']); }
    public function getErrorReporting(): int        { return E_ALL; }
    public function shouldDisplayErrors(): bool     { return false; }
    public function getExtraOptions(): array        { return []; }
}

Extra SDK options

Pass any Sentry PHP SDK option via extra-options (or getExtraOptions()):

new SentryClientConfig([
    // ...required keys...
    'extra-options' => [
        'traces_sample_rate' => 0.2,
        'before_send'        => function (\Sentry\Event $event): ?\Sentry\Event {
            // drop events from bots
            if (str_contains((string) $event->getRequest()?->getHeaders()['User-Agent'] ?? '', 'bot')) {
                return null;
            }
            return $event;
        },
    ],
]);

Running tests

composer test