API: The Handler Class

at\exceptable\Handler

Manages a registry of callback functions ("handlers") for errors, uncaught exceptions, and shutdown.

instance methods

• Handler::__construct()

  public __construct( at\exceptable\Handler\Options $options, Logger $logger = null )
  

  • parameters:
    • Options $options: Runtime options for the Handler.
      • bool $debug: Enable debug mode? Defaults to false.
      • bool $scream: Ignore the error control operator? Defaults to false.
      • int $throw: Error types which should be re-thrown as ErrorExceptions. Defaults to 0 (none).
    • Psr\Log\LoggerInterface $logger: A logger object.

• Handler::debugLog()

  public debugLog() : LogEntry[]
  

  Gets a log of errors/exceptions encountered while debug mode was active.

  • returns LogEntry[]: Each entry is one of:
    • at\exceptable\Handler\ErrorLogEntry
      • int $code: Error code.
      • bool $controlled: Was this error suppressed by the error control operator?
      • string $file: Filename.
      • bool $handled: Was this error handled by a registered handler?
      • int $line: Line number.
      • string $message: Human-readable error message.
      • float $time: Unixtime error was logged, with microsecond precision.
      • array|null $trace: Stack trace, if logged.
    • at\exceptable\Handler\ExceptionLogEntry
      • int $code: Error code.
      • at\exceptable\Error|null $error: The Error case used by the exception, if Exceptable.
      • Throwable $exception: The exception object.
      • string $file: Filename.
      • bool $handled: Was this error handled by a registered handler?
      • int $line: Line number.
      • string $message: Human-readable error message.
      • float $time: Unixtime error was logged, with microsecond precision.

• Handler::handleError()

  public handleError( int $c, string $m, string $f, int $l ) : bool
  

  Uses registered handlers to handle the given php error.

• Handler::handleException()

  public handleException( Throwable $t ) : void
  

  Uses registered handlers to handle the given exception.

  • parameters;
    • Throwable $t: The exception to handle
  • throws at\exceptable\Spl\RuntimeException at\exceptable\ExceptableError::UncaughtException If no registered handler handles the exception.

• Handler::handleShutdown()

  public handleShutdown() : void
  

  Invokes registered handlers on shutdown. Invokes handleError() if shutdown was due to a fatal error.

• Handler::onError()

  public Handler onError( at\exceptable\Handler\ErrorHandler $handler, int $types = -1 ) : $this
  

  Adds a handler for php errors.

  • parameters:
    • ErrorHandler $handler: The handler to add.
      • run( int $c, string $m, string $f, int $l ) : bool: @see set_error_handler() $callback
    • int $types: The error types the handler should be invoked for (a bitmask of E_* constants). Defaults to -1 (any error type).
  • returns $this

• Handler::onException()

  public Handler onException( at\exceptable\Handler\ExceptionHandler $handler ) : $this
  

  Adds a handler for uncaught exceptions.

  • parameters:
    • ExceptionHandler $handler: The handler to add.
      • run( Throwable $t ) : bool: return true if exception handled successfully; false otherwise
  • returns $this

• Handler::onShutdown()

  public Handler onShutdown( at\exceptable\Handler\ShutdownHandler $handler ) : $this
  

  Adds a shutdown handler.

  Note, shutdown handlers should not be registered to handle fatal errors. If the shutdown is due to a fatal error, the appropriate registered error handlers will be invoked automatically.

  • parameters:
    • callable $handler: The handler to add.
      • run() : void: @see register_shutdown_function() $callback
  • returns $this

• Handler::register()

  public Handler register() : $this
  

  Starts the Handler (makes its registered handlers "active").

  • returns $this

• Handler::try()

  public try( callable $callback ) : mixed
  

  Tries invoking a callback, using the registered exception handler(s) to handle any uncaught exceptions.

  • parameters:
    • callable $callback: The callback to invoke.
  • throws RuntimeException ExceptableError::UncaughtException if callback throws and no registered Handler handles it.
  • returns mixed: The handled exception on failure; the value returned from the callback otherwise

• Handler::unregister()

  public Handler unregister() : $this
  

  Stops the Handler (makes its registered handlers "inactive").

  • returns $this