timefrontiers/php-instance-error

PHP Instance Error handler with access-based filtering

dev-master 2026-04-14 21:56 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

Suggests

• timefrontiers/php-error-log: ^1.0
• timefrontiers/php-session: ^1.0

MIT

• Ikechukwu Okalia
• Time Frontiers Ltd

• php
• error
• class
• instance
• tym
• frontiers

README

A flexible PHP error handler that retrieves and filters errors from any object instance based on user access rank.

Features

• Extracts errors from any object that implements getErrors() or has a public $errors property.
• Filters errors by access rank – only shows errors appropriate for the current user.
• Override filtering – force display of all errors or use a custom rank.
• Optional logging – integrates with ErrorLog to write errors to file.
• Strict typing and modern PHP (8.1+).
• PSR‑4 autoloading.

Installation

composer require timefrontiers/php-instance-error

Requirements

• PHP 8.1 or higher
• timefrontiers/php-error-log ^1.0 (optional, for logging)

Basic Usage

Retrieve Errors

Assume you have a class that collects errors internally:

use TimeFrontiers\InstanceError;

$location = new Location('invalid-ip');
$location->refresh();

// Get all errors (filtered by current user's rank)
$errors = (new InstanceError($location))->get();

// Get errors for a specific context
$errors = (new InstanceError($location))->get('refresh');

Override Rank Filtering

// Show all errors regardless of rank
$all_errors = (new InstanceError($location, true))->get();

// Use a specific rank for filtering (e.g., developer rank = 7)
$dev_errors = (new InstanceError($location, 7))->get();

Get Error Messages Only

// Return only the error message strings
$messages = (new InstanceError($location))->get('refresh', true);

Log Errors to File

// Log all errors to a file
(new InstanceError($location))->log();

// Log only errors from a specific context
(new InstanceError($location))->log('refresh', '/path/to/error.log');

How It Works

1. The constructor accepts an object instance.
2. It extracts errors using:
   • $instance->getErrors() (preferred modern pattern)
   • Falls back to $instance->errors (legacy public property)
3. When get() is called, it determines the user's rank from:
   • Override value (if true or an integer was passed)
   • Global $session->access_rank() or $session->access_rank (if available)
   • Defaults to 0 (guest)
4. Only errors where min_rank <= user_rank are returned.

Error Array Format

Errors are expected to be stored as an array with the following structure:

[
  'context_name' => [
    [$min_rank, $code, $message, $file, $line],
    // ...
  ],
  // ...
]

Index	Description
0	Minimum access rank required to view this error
1	Error code (e.g., HTTP status or custom)
2	Human‑readable error message
3	File where error occurred (use __FILE__)
4	Line number (use __LINE__)

Integration with Other Packages

This package is designed to work seamlessly with other TimeFrontiers libraries:

• Session – provides the access_rank property for filtering.
• Location – collects errors using getErrors().
• ErrorLog – writes errors to file when log() is called.

License

MIT License. See LICENSE for details.