README

Extract and filter errors from objects based on user access rank.

Installation

composer require timefrontiers/php-instance-error

Overview

InstanceError extracts errors from any object that has:

• A getErrors() method (recommended, used by HasErrors trait), or
• A public $errors property (legacy)

Errors are filtered based on the user's access rank, so sensitive system errors only appear to developers/admins.

Error Format

Errors must follow this format:

[min_rank, code, message, file, line]
// Example:
[0, 256, 'Invalid email format', '/app/User.php', 42]

Where min_rank is the minimum AccessRank value required to see this error.

Usage

Basic Usage

use TimeFrontiers\InstanceError;

// Extract errors visible to current user (uses global $session)
$extractor = new InstanceError($userObject);
$errors = $extractor->get();

// Get errors for a specific context
$loginErrors = $extractor->get('login');

// Get only error messages (strings)
$messages = $extractor->get('login', true);

Override Rank

use TimeFrontiers\InstanceError;
use TimeFrontiers\AccessRank;

// Show ALL errors regardless of rank
$extractor = new InstanceError($object, true);

// Show errors visible to DEVELOPER rank
$extractor = new InstanceError($object, AccessRank::DEVELOPER);

// Show errors visible to rank 5
$extractor = new InstanceError($object, 5);

Helper Methods

$extractor = new InstanceError($object);

// Check if errors exist
if ($extractor->has('validation')) {
  // ...
}

// Count visible errors
$count = $extractor->count();
$validationCount = $extractor->count('validation');

// Get first error message
$first = $extractor->first();

// Get all messages as flat array
$allMessages = $extractor->messages();

Logging Errors

If timefrontiers/php-error-log is installed:

$extractor = new InstanceError($object, true);

// Log all errors
$extractor->log();

// Log specific context
$extractor->log('database');

// Log to specific file
$extractor->log('database', '/var/log/app/db-errors.log');

Adding Errors

$extractor = new InstanceError($object);

// Add an error to the collection
$extractor->put('custom', [
  AccessRank::GUEST->value,  // min_rank
  400,                        // code
  'Something went wrong',     // message
  __FILE__,                   // file
  __LINE__                    // line
]);

Rank Resolution

When no override is provided, rank is resolved in this order:

1. Global $session->access_rank property
2. Global $session->access_rank() method
3. Default: AccessRank::GUEST (0)

Integration with HasErrors Trait

Objects using the HasErrors trait work seamlessly:

use TimeFrontiers\Helper\HasErrors;

class MyService {
  use HasErrors;

  public function process():bool {
    if ($error) {
      $this->_userError('process', 400, 'Processing failed');
      return false;
    }
    return true;
  }
}

// Extract errors
$service = new MyService();
$service->process();

$extractor = new InstanceError($service);
$errors = $extractor->get('process');

Access Rank Levels

Dependencies

• timefrontiers/php-core - For AccessRank enum
• timefrontiers/php-has-errors - For error handling trait

License

MIT