PHPackages                             olusodotdev/oluso-php - 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. olusodotdev/oluso-php

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

olusodotdev/oluso-php
=====================

AI-powered error monitoring for PHP applications: automatic error reporting, breadcrumb tracking, and intelligent error grouping.

v1.1.0(3w ago)02MITPHPPHP ^8.1CI passing

Since Jul 17Pushed 3w agoCompare

[ Source](https://github.com/olusodotdev/oluso-php)[ Packagist](https://packagist.org/packages/olusodotdev/oluso-php)[ Docs](https://github.com/olusodotdev/oluso-php)[ RSS](/packages/olusodotdev-oluso-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (8)Versions (5)Used By (0)

oluso-php
=========

[](#oluso-php)

AI-powered error monitoring for PHP applications: automatic error reporting, breadcrumb tracking, and intelligent error grouping.

Installation
------------

[](#installation)

```
composer require olusodotdev/oluso-php
```

Laravel auto-discovers the package's service provider — no manual registration needed.

Usage with Laravel
------------------

[](#usage-with-laravel)

```
// config/oluso.php (or just set OLUSO_API_KEY in .env — the package ships a sensible default config)
return [
    'api_key' => env('OLUSO_API_KEY'),
    'environment' => env('APP_ENV', 'production'),
];
```

```
// bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php (Laravel 10)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Oluso\Laravel\OlusoMiddleware::class);
})
```

```
// routes/web.php
Route::get('/', function () {
    throw new RuntimeException('something went wrong'); // captured and reported automatically
});
```

`OlusoMiddleware` scopes breadcrumbs to each request and auto-reports 5xx responses. Unhandled exceptions are reported separately via Laravel's `reportable()` exception hook (registered automatically by the service provider), since Laravel's own exception handler intercepts them before they'd ever reach the middleware's response check — this is what gets you the real exception (type, message, trace) instead of a generic "server error: 500". Both paths mark the request so a single exception is never double-reported.

By default, reports are queued during the request and only sent from the middleware's `terminate()` hook — called by Laravel *after* the response has already been sent to the client, so error reporting never adds latency to the response. Set `'defer_send' => false` in `config/oluso.php` to send synchronously instead.

Breadcrumbs & User Context
------------------------------

[](#breadcrumbs--user-context)

```
use Oluso\UserContext;
use function Oluso\add_breadcrumb;
use function Oluso\set_user;

Route::get('/checkout', function () {
    add_breadcrumb('user started checkout', category: 'action');
    set_user(new UserContext(id: 'user_456'));

    try {
        doCheckout();
    } catch (\Throwable $e) {
        app(\Oluso\Client::class)->captureException($e, ['cartId' => 'cart_123']);
    }
});
```

For non-request work (a queued job, an Artisan command) where you still want a scope, open one yourself:

```
use Oluso\Scope;
use function Oluso\add_breadcrumb;

Scope::start();
add_breadcrumb('job started');
$client->captureException($e);
Scope::clear();
```

Classic PHP-FPM is shared-nothing per request, so `Scope` is just a static holder — there's no cross-request leakage to guard against the way Node/Python/Go need `AsyncLocalStorage`/`contextvars`/`context.Context` for. The one thing this doesn't handle is true *concurrent* requests sharing one PHP process via coroutines (Swoole specifically) — that needs coroutine-local storage, out of scope for this first pass.

Manual Reporting (framework-agnostic)
-------------------------------------

[](#manual-reporting-framework-agnostic)

The core client has no framework dependency and works in any PHP script:

```
use Oluso\Client;
use Oluso\Options;

$client = new Client(new Options(apiKey: 'your-api-key'));

try {
    doWork();
} catch (\Throwable $e) {
    $client->captureException($e, ['customMeta' => 'extra-info']);
}
```

Plain PHP has no background thread or event loop to send on, so `captureException()` sends **synchronously by default** — nothing to forget, correct by default for a script that exits right after. Set `Options::$deferSend = true` if you have your own "after the response" hook and want to call `$client->flush()` from it (this is what the Laravel integration does automatically).

Advanced Configuration
----------------------

[](#advanced-configuration)

```
use Oluso\Options;
use Oluso\Severity;

$options = new Options(
    apiKey: 'your-api-key',
    endpoint: Options::DEFAULT_ENDPOINT, // override for self-hosting
    environment: 'staging',
    defaultSeverity: Severity::Medium,
    maxBreadcrumbs: 50,
    maxErrorsPerMinute: 100,
    sensitiveKeys: ['ssn', 'internal_id'],
    shouldReport: fn (\Throwable $e) => !str_contains($e->getMessage(), 'expected'),
);
```

Monitor outcomes, heartbeats, and workflows
-------------------------------------------

[](#monitor-outcomes-heartbeats-and-workflows)

Create the matching monitor under **Project → Monitors**, then use the existing client:

```
use Oluso\AssertionOptions;
use Oluso\HeartbeatOptions;
use Oluso\MonitorReference;
use Oluso\WorkflowEventOptions;

$client->heartbeat(
    $_ENV['OLUSO_BACKUP_HEARTBEAT_URL'],
    new HeartbeatOptions(context: ['job' => 'nightly-backup', 'rows' => 12_402]),
);

$client->assertOutcome(new AssertionOptions(
    monitor: MonitorReference::byName('checkout-total'),
    passed: $chargedAmount === $expectedAmount,
    expected: $expectedAmount,
    actual: $chargedAmount,
    durationMs: $durationMs,
    context: ['order_id' => $orderId],
));

$deployment = $client->workflow(MonitorReference::byName('production-deployment'));
$deployment->checkpoint('queued', new WorkflowEventOptions(context: ['commit_sha' => $commitSha]));
$deployment->checkpoint('built', new WorkflowEventOptions(context: ['artifact' => $artifact]));
$deployment->checkpoint('deployed', new WorkflowEventOptions(context: ['region' => 'lon1']));
$deployment->complete(options: new WorkflowEventOptions(context: ['release' => $artifact]));
```

Use `MonitorReference::byId('...')` for an immutable reference. The heartbeat URL is a monitor-specific secret shown once at creation. Evidence is recursively redacted and bounded; transient failures retry with exponential backoff, permanent 4xx responses do not, and the project connection string is never attached to a heartbeat request.

Error Report Structure
----------------------

[](#error-report-structure)

Reports sent to the API include:

- **Metadata**: Title, message, stack trace, severity, tags.
- **Context**: Request details (URL, method, headers, etc.), server details (hostname, PHP version, memory).
- **History**: Breadcrumbs leading up to the error.
- **Identification**: Fingerprint for deduplication and user ID.

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance95

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~7 days

Total

4

Last Release

22d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7c23d359cbff09f541fe0f68797ccdad27a6bbfec725ed3f59fd06d964856fdd?d=identicon)[oluso](/maintainers/oluso)

---

Top Contributors

[![KingDavidsHub](https://avatars.githubusercontent.com/u/117018237?v=4)](https://github.com/KingDavidsHub "KingDavidsHub (3 commits)")

---

Tags

laravelloggingmonitoringaidebuggingerrorreportingerror-monitoringcrash-reportingerror-tracking

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/olusodotdev-oluso-php/health.svg)

```
[![Health](https://phpackages.com/badges/olusodotdev-oluso-php/health.svg)](https://phpackages.com/packages/olusodotdev-oluso-php)
```

###  Alternatives

[rollbar/rollbar-laravel

Rollbar error monitoring integration for Laravel projects

14311.3M11](/packages/rollbar-rollbar-laravel)[jenssegers/rollbar

Rollbar error monitoring integration for Laravel projects

3301.1M2](/packages/jenssegers-rollbar)[jenssegers/raven

Sentry (Raven) error monitoring integration for Laravel projects

90197.4k1](/packages/jenssegers-raven)[iazaran/trace-replay

Enterprise-ready process tracking, replay, and AI-assisted debugging for Laravel applications.

1032.8k](/packages/iazaran-trace-replay)

PHPackages © 2026

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