README

A WebFiori framework extension that logs exceptions to a database with optional per-portal tracking. Currently supports SQL Server only.

Requirements

• PHP 8.1 or later
• WebFiori Framework v3.0.0-RC
• SQL Server with ODBC Driver 18

Installation

composer require oshco/db-exceptions-logger

Setup

1. Create the database table

Run the migration to create the system_exceptions table:

php webfiori migrations:ini --connection=<your-connection>
php webfiori migrations:run --connection=<your-connection>

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

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

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

Each SystemException entity exposes:

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

Classes

Running Tests

Requires a running SQL Server instance:

SA_SQL_SERVER_PASSWORD='<your-password>' composer test

License

MIT

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');