PHPackages                             sturents/sentry-light - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. sturents/sentry-light

ActiveLibrary[Logging & Monitoring](/categories/logging)

sturents/sentry-light
=====================

Lightweight alternative to the official Sentry client for PHP. Forked from kodus/sentry

3.1.0(1y ago)148.5k↓21.1%1[1 issues](https://github.com/sturents/sentry-light/issues)[1 PRs](https://github.com/sturents/sentry-light/pulls)MITPHPPHP >=8.0CI passing

Since Feb 28Pushed 1y ago7 watchersCompare

[ Source](https://github.com/sturents/sentry-light)[ Packagist](https://packagist.org/packages/sturents/sentry-light)[ RSS](/packages/sturents-sentry-light/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (6)Versions (5)Used By (0)

`sturents/sentry-light`
=======================

[](#sturentssentry-light)

Lightweight [Sentry](https://sentry.io/welcome/) client with no dependencies. Forked from `kodus/sentry` as that package is no longer maintained and is causing breaks in newer PHP versions.

[![PHP Version](https://camo.githubusercontent.com/487804500a039aee09e5d93e41b745b4cd68dcc0fdf801e67d26d30b93f83358/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e302532422d626c75652e737667)](https://packagist.org/packages/sturents/sentry-light)[![Build Status](https://github.com/sturents/sentry-light/actions/workflows/test.yml/badge.svg)](https://github.com/sturents/sentry-light/actions/workflows/test.yml/badge.svg)

### About

[](#about)

This package is an alternative to the [official PHP client](https://github.com/getsentry/sentry-php) for Sentry.

The library consists of a client class, an event-model model that matches the shape of the Sentry API, and an interface for extensions.

The API deviates from the [Unified API](https://docs.sentry.io/clientdev/unified-api/) recommendation - our goal is to log detailed exceptions, and capture log-entries leading up to those exceptions, with as little coupling and dependency on the client as possible.

With most members declared as `protected`, you can further extend and override/enhance various aspects of exception/error/request-processing with simple code that modifies the (fully type-hinted) model.

### Features

[](#features)

This client has most of the features of the official client plus some extras.

All features are opt-in, and the package ships with the following extensions:

- `EnvironmentReporter`: Reports PHP and OS versions, server name, site name, etc.
- `RequestReporter`: Reports details about the (PSR-7) HTTP Request.
- `ExceptionReporter`: Provides detailed stack-traces with source-code context, paths/filenames, line-numbers, etc.
- `ClientSniffer`: Parses `User-Agent` for client (browser or bot) name/version/OS and adds useful tags.
- `ClientIPDetector`: Parses `X-Forwarded-For` and `Forwarded` headers for User IP logging behind proxies.
- `BreadcrumbLogger`: Reports [PSR-3](https://www.php-fig.org/psr/psr-3/) log-events as "[breadcrumbs](https://docs.sentry.io/clientdev/interfaces/breadcrumbs/)".

Non-features:

- No built-in error-handler: your framework/stack/app probably has one, and this client should be very easy to integrate just about anywhere.
- No post-data recording: scrubbing/sanitization is unreliable. (if you're willing to take the risk, the fields are there in the model, and you can implement your own extension.)

### Usage

[](#usage)

Most modern frameworks by now have some sort of DI container and an error-handler.

To avoid getting caught up in the specifics of various frameworks, in this section, we'll demonstrate how to bootstrap and integrate the client independently of any specific framework.

To bootstrap the client itself, you need a [Sentry DSN](https://docs.sentry.io/learn/configuration/?platform=node#dsn), an `EventCapture` implementation, and a your choice of extensions - this example uses `DirectEventCapture`and most of the built-in extensions:

```
$client = new SentryClient(
    new DirectEventCapture(
        new DSN("https://0123456789abcdef0123456789abcdef@sentry.io/1234567"),
        "tcp://proxy.example.com:5100" // optional: required if you're behind a proxy
    ),
    [
        new EnvironmentReporter(),
        new RequestReporter(),
        new ExceptionReporter(),
        new ClientSniffer(),
        new ClientIPDetector(),
    ]
);

$client->sample_rate = 50; // optional: percentage of calls to `captureException()` to actually capture
```

Some extensions support additional options, which will be described in the [Configuration](#configuration) section.

To capture PHP errors, we'll need to add an error-handler that maps errors to instances of the built-in [`ErrorException`](http://php.net/manual/en/class.errorexception.php) class.

Note that most frameworks and error-handlers already have something like this built-in - an existing error-handler likely is designed to be the only global error-handler, and will likely offer an abstraction and some sort of API over `set_error_handler()`.

The following simplified error-handler throws for all error-levels except `E_NOTICE` and `E_WARNING`, which it silently captures to the `$client` instance we created above:

```
set_error_handler(
    function ($severity, $message, $file, $line) use ($client) {
        $error = new ErrorException($message, 0, $severity, $file, $line);

        if ($severity & (E_ALL & ~E_NOTICE & ~E_WARNING)) {
            throw $error;
        } else {
            $client->captureException($error);
        }
    },
);
```

Now that we have `ErrorException` being thrown for PHP errors, we can handle any error/exception consistently with a `try`/`catch`-statement surrounding any statements in the top-level script:

```
try {
    // ... dispatch your router or middleware-stack, etc. ...
} catch (Throwable $error) {
    $client->captureException($error);

    // ... render an apology page for disappointed users ...
}
```

We now have basic error-handling and silent capture of warnings and notices.

In a [PSR-15](https://www.php-fig.org/psr/psr-7/) middleware context, we can capture useful additional information about the `ServerRequestInterface` instance that initiated the error - typically, we'll do this with a middleware at the top of the middleware-stack, which will delegate to the next middleware from a `try`/`catch`-block.

Here's a basic example of an anonymous middleware being added to an array of middlewares:

```
$middlewares = [
    new class ($client) implements MiddlewareInterface {
        /**
         * @var SentryClient
         */
        private $client;

        public function __construct(SentryClient $client)
        {
            $this->client = $client;
        }

        public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
        {
            try {
                return $handler->handle($request);
            } catch (Throwable $error) {
                $this->client->captureException($error, $request);

                // ... return an apology response for disappointed users ...
            }
        }
    },
    // ... the rest of your middleware stack ...
];
```

Any error caught by this middleware *won't* bubble to our first `try`/`catch`-statement in the top-level script - instead, the call to `captureException()` from the middleware includes both the `$error` and the `$request` (which doesn't exist yet in the top-level script) from which the client can capture a lot more detail.

In addition, your application may log incidental useful information (such as database queries) during normal operation - on failure, this information can help you diagnose the events leading up to an error.

These log entries can be captured as so-called "breadcrumbs" using the provided `BreadcrumbLogger`, which is both a [PSR-3](https://www.php-fig.org/psr/psr-3/) `LoggerInterface` implementation and a `SentryClientExtension`.

You *might* want to bootstrap this as your primary logger - maybe you only care about log-entries that lead to an error condition. However, it's more likely you'll want another logger to send log-events to a persisted log, as well as recording them as breadcrumbs. (For example, you may try the [`monolog/monolog`](https://packagist.org/packages/monolog/monolog) package, which allows you to log to any combination of PSR-3 and monolog-handlers, filter the log-entries, and so on - or [`mouf/utils.log.psr.multi-logger`](https://github.com/thecodingmachine/utils.log.psr.multi-logger), if you prefer something simple.)

Note that log-entries will buffer *in the logger* until you capture an exception - if your application is a CLI script handling many requests, you will need to manually call `clear()`on the logger instance at the end of a successful request, since otherwise log-entries will accumulate across requests.

Notice: PHP 7.4 introduced a new [ini setting](https://www.php.net/manual/en/ini.core.php#ini.zend.exception-ignore-args) (`zend.exception_ignore_args`) for excluding arguments from stack traces. If you want arguments to be passed on to Sentry you will need to turn this setting off.

#### Configuration

[](#configuration)

A few of the extensions support optional constructor arguments to configure some optional features.

##### `ExceptionReporter`

[](#exceptionreporter)

The constructor accepts two optional argument:

- `$root_path` - if specified, the project root-path will be removed from visible filenames in stack-traces.
- `$max_string_length` - specifies the maximum length at which reported PHP values will be truncated.
- `$filters` - specifies one or more filename patterns to be filtered from stack-traces.

In addition, the public `$error_levels` property lets you customize how PHP error-levels map to Sentry severity-levels. The default configuration matches that of the official 2.0 client.

##### `ClientSniffer`

[](#clientsniffer)

If your client base uses rare or exotic clients, you can add your own regular expression patterns to to the public `$browser_patterns` and `$os_patterns` properties to enhance the browser classifications. The default configuration will recognize most common browsers and versions, operating systems and bots.

##### `ClientIPDetector`

[](#clientipdetector)

Replace or add to `$user_ip_headers` to detect client IP addresses in unusual environments. The built-in patterns support most ordinary cache/proxy-servers.

##### `BreadcrumbLogger`

[](#breadcrumblogger)

The default `$log_levels` match those of the official (2.0) client - if needed, you can override with custom mappings from PSR-5 log-level to Sentry severity-level.

#### `BufferedEventCapture`

[](#bufferedeventcapture)

A buffered `EventCapture` implementation is available.

If you're capturing exceptions/errors only, you probably don't need this - but if you're mapping warnings and notices to `ErrorException` with an error-handler, you may wish to avoid blocking the response while posting to Sentry.

You can accomplish this using the `BufferedEventCapture` decorator, which allows you to defer the actual HTTP request(s) until after you've sent the response to the user.

In this case, you will need to bootstrap the capture and client instances separately:

```
$buffer = new BufferedEventCapture(
   new DirectEventCapture(
       new DSN("https://0123456789abcdef0123456789abcdef@sentry.io/1234567")
   ),
);

$client = new SentryClient($buffer);
```

Since Events will now get buffered rather than directly posted to Sentry, you will need to manually flush the Events at the of the request.

In a typical PHP FCGI SAPI-environment, you can accomplish this by explicitly closing the HTTP response immediately before flushing the events to Sentry - for example, from an `index.php` file:

```
register_shutdown_function(function () use ($buffer) {
    fastcgi_finish_request();

    $buffer->flush();
});
```

#### Customization

[](#customization)

The client class and extensions were designed with project-specific extensions in mind and contain many `protected` methods designed for you to extend and override their behavior.

Using `protected` overrides, you can customize how events get created and captured, how exceptions and requests get processed, client IP detection and filtering, how PHP values are formatted in stack-traces, and many other details.

Please refer to the source-code for available `protected` methods - and note that we're committed to versioning this package semantically: any breaking changes to `protected` methods will be versioned as major releases.

### Why?

[](#why)

*Openly opinionated fluff:*

Version 1.x of the official Sentry PHP client is dated, and not a good fit for a modern (PSR-7/15) application stack.

Version 2.0 (currently in development) is an architectural masterpiece - which is not what we need/want from something that's going to essentially collect some data and perform a simple JSON POST request.

Specifically:

- We don't need an error-handler - every modern application stack has one already.
- We don't want a complex architecture and custom middleware - simple functions will do.
- We don't want to record post-data - there are too many risks.
- Fewer lines of code ~> fewer bugs (hopefully; you don't want the error-logger itself to break down.)
- No dependencies: no conflicts, no fuss.

We want something simple, fast and transparent.

We also insist on code with good IDE support, which provides better insight for someone reading/modifying the code, and reduces the potential for silent errors - the official client juggles `array` values, whereas our model formally describes the JSON body-shape with a plain PHP class-hierarchy that implements `JsonSerializable`.

Note that we only model the portion of the JSON body shape that makes sense in a PHP context - if you find something to be missing or incorrect, pull-requests are more than welcome.

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance26

Infrequent updates — may be unmaintained

Popularity32

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~197 days

Total

3

Last Release

417d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6e13cb42c1a004c15c986cc3ac59424757dd04b25ed4068146e41812f0410338?d=identicon)[m1ke](/maintainers/m1ke)

---

Top Contributors

[![mindplay-dk](https://avatars.githubusercontent.com/u/103348?v=4)](https://github.com/mindplay-dk "mindplay-dk (60 commits)")[![M1ke](https://avatars.githubusercontent.com/u/1226123?v=4)](https://github.com/M1ke "M1ke (5 commits)")[![craig-mcmahon](https://avatars.githubusercontent.com/u/5879594?v=4)](https://github.com/craig-mcmahon "craig-mcmahon (3 commits)")[![vortrixs](https://avatars.githubusercontent.com/u/15426116?v=4)](https://github.com/vortrixs "vortrixs (2 commits)")[![thomasnordahl-dk](https://avatars.githubusercontent.com/u/5709900?v=4)](https://github.com/thomasnordahl-dk "thomasnordahl-dk (1 commits)")

###  Code Quality

TestsCodeception

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sturents-sentry-light/health.svg)

```
[![Health](https://phpackages.com/badges/sturents-sentry-light/health.svg)](https://phpackages.com/packages/sturents-sentry-light)
```

###  Alternatives

[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2322.9M248](/packages/open-telemetry-sdk)[pagemachine/typo3-formlog

Form log for TYPO3

23225.3k6](/packages/pagemachine-typo3-formlog)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[illuminated/console-logger

Logging and Notifications for Laravel Console Commands.

8674.9k](/packages/illuminated-console-logger)[scoutapp/scout-apm-php

Scout Application Performance Monitoring Agent - https://scoutapm.com

17877.0k5](/packages/scoutapp-scout-apm-php)[open-telemetry/opentelemetry-auto-wordpress

OpenTelemetry auto-instrumentation for Wordpress

17166.0k](/packages/open-telemetry-opentelemetry-auto-wordpress)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)