PHPackages                             oshco/db-exceptions-logger - 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. [Framework](/categories/framework)
4. /
5. oshco/db-exceptions-logger

ActiveLibrary[Framework](/categories/framework)

oshco/db-exceptions-logger
==========================

A component which is used to log exceptions to database.

v2.1.0(3w ago)01.1kMITPHPPHP >=8.1CI passing

Since May 20Pushed 3w ago1 watchersCompare

[ Source](https://github.com/OSHCO/db-exceptions-logger)[ Packagist](https://packagist.org/packages/oshco/db-exceptions-logger)[ RSS](/packages/oshco-db-exceptions-logger/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (9)Versions (13)Used By (0)

Database Exceptions Logger
==========================

[](#database-exceptions-logger)

A [WebFiori](https://webfiori.com) framework extension that logs exceptions to a database with optional per-portal tracking. Currently supports SQL Server only.

Requirements
------------

[](#requirements)

- PHP 8.1 or later
- [WebFiori Framework](https://github.com/WebFiori/framework) v3.0.0-RC
- SQL Server with ODBC Driver 18

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

[](#installation)

```
composer require oshco/db-exceptions-logger
```

Setup
-----

[](#setup)

### 1. Create the database table

[](#1-create-the-database-table)

Run the migration to create the `system_exceptions` table:

```
php webfiori migrations:ini --connection=
php webfiori migrations:run --connection=
```

### 2. Register the error handler

[](#2-register-the-error-handler)

```
use Oshco\ErrHandler\DatabaseErrHandler;
use Oshco\Infrastructure\Repository\ExceptionsRepository;
use WebFiori\Database\Database;
use WebFiori\Error\Handler;
use WebFiori\Framework\App;

$db = new Database(App::getConfig()->getDBConnection('your-connection'));
$repo = new ExceptionsRepository($db);
Handler::registerHandler(new DatabaseErrHandler($repo));
```

### 3. (Optional) Configure portal tracking

[](#3-optional-configure-portal-tracking)

To associate exceptions with a specific portal, set a resolver callable:

```
use Oshco\ErrHandler\DatabaseErrHandler;
use WebFiori\Framework\Session\SessionsManager;

DatabaseErrHandler::setPortalIdResolver(function () {
    $session = SessionsManager::getActiveSession();
    return $session?->get('portal-id');
});
```

The resolver is called when an exception occurs. It should return an `int` (portal ID) or `null`.

Usage
-----

[](#usage)

### Querying logged exceptions

[](#querying-logged-exceptions)

```
use Oshco\Infrastructure\Repository\ExceptionsRepository;
use WebFiori\Database\Database;
use WebFiori\Framework\App;

$db = new Database(App::getConfig()->getDBConnection('your-connection'));
$repo = new ExceptionsRepository($db);

// Get total count
$count = $repo->count();

// Get paginated list (page 1, 10 per page)
$exceptions = $repo->getAll(1, 10);

// Get by ID
$exception = $repo->getById(1);

// Get the most recent exception
$latest = $repo->getLast();

// Check if an exception with a given hash exists
$exists = $repo->existsByHash($hashString);

// Filter by portal
$portalExceptions = $repo->getByPortal(portalId: 1, page: 1, size: 10);
$portalCount = $repo->countByPortal(portalId: 1);
```

### Entity properties

[](#entity-properties)

Each `SystemException` entity exposes:

MethodDescription`getId()`Auto-increment ID`getHash()`SHA-256 hash for deduplication`getDate()`Timestamp when the exception was logged`getCode()`Exception code`getClass()`Class where the exception was thrown`getExceptionClass()`The exception's fully-qualified class name`getMessage()`Exception message`getLine()`Line number`getUrl()`Request URL`getParameters()`Request parameters`getTrace()`Stack trace`getPortalId()`Portal ID (null if not set)How It Works
------------

[](#how-it-works)

When an exception occurs, `DatabaseErrHandler`:

1. Captures exception details (code, class, message, file, line, stack trace)
2. Captures request context (URL, parameters)
3. Resolves the portal ID via the configured resolver (if set)
4. Computes a SHA-256 hash for deduplication
5. Stores everything in the `system_exceptions` table via `ExceptionsRepository`

Database Schema
---------------

[](#database-schema)

ColumnTypeNullableDescription`id`INT (PK, identity)NoAuto-increment ID`hash`NVARCHAR(128)NoSHA-256 hash for deduplication`date`DATETIME2NoTimestamp (defaults to now)`code`INTNoException code`class`VARCHAR(128)NoClass where exception was thrown`exception_class`VARCHAR(128)NoException class name`message`NVARCHAR(256)NoException message`line`INTNoLine number`url`NVARCHAR(256)YesRequest URL`parameters`NVARCHAR(1024)YesRequest parameters`trace`NVARCHAR(1024)NoStack trace`portal_id`INTYesPortal where exception occurredClasses
-------

[](#classes)

ClassDescription`DatabaseErrHandler`Error handler that captures exceptions and delegates storage to the repository. Supports a configurable portal ID resolver.`ExceptionsRepository`Repository providing CRUD and filtering operations on the `system_exceptions` table.`SystemExceptionsTable`Attribute-based MSSQL table schema definition.`SystemException`Entity representing a logged exception record.`CreateSystemExceptionsTable`Migration that creates the base table.`AlterSystemExceptionsAddPortalId`Migration that adds the `portal_id` column (safe for existing tables).Running Tests
-------------

[](#running-tests)

Requires a running SQL Server instance:

```
SA_SQL_SERVER_PASSWORD='' composer test
```

License
-------

[](#license)

MIT

### Statistics Methods

[](#statistics-methods)

All statistics methods accept optional `$from` and `$to` date parameters (ISO format) for filtering by date range.

```
// Count by exception class
$stats = $repo->getStatsByExceptionClass('2026-01-01', '2026-12-31', limit: 10);

// Count by class + line (pinpoints exact code location)
$stats = $repo->getStatsByClassAndLine();

// Count by portal
$stats = $repo->getStatsByPortal();

// Count by URL (which endpoints fail most)
$stats = $repo->getStatsByUrl();

// Daily error trend
$stats = $repo->getStatsByDay('2026-06-01', '2026-06-30');

// Top recurring errors (grouped by hash)
$stats = $repo->getTopRecurring();

// Total count in date range
$count = $repo->countInRange('2026-06-01', '2026-06-30');
```

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance94

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

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

Recently: every ~14 days

Total

10

Last Release

26d ago

Major Versions

v1.3.1 → v2.0.02026-05-10

PHP version history (2 changes)v1.0PHP >=8.0

v1.3.1PHP >=8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/92792203?v=4)[Olayan Saudi Holding Company (OSHCO)](/maintainers/oshco)[@OSHCO](https://github.com/OSHCO)

---

Top Contributors

[![usernane](https://avatars.githubusercontent.com/u/12120015?v=4)](https://github.com/usernane "usernane (65 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")

---

Tags

frameworkdatabaseloggerwebfiori

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/oshco-db-exceptions-logger/health.svg)

```
[![Health](https://phpackages.com/badges/oshco-db-exceptions-logger/health.svg)](https://phpackages.com/packages/oshco-db-exceptions-logger)
```

PHPackages © 2026

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