README

Phalcon Exception Handler

Adds Preset throwable exceptions along with a built in handler with included logging.

Explore the docs »

Report Bug · Request Feature

Table of Contents
About The Project
- Built With
Installation
Usage
Roadmap
Contributing
License
Contact

About The Project

Built With

vscode
php 8.1.1
Phalcon 5 (Micro Framework)

Installation

Git:

git clone https://github.com/SageITSolutions/phalcon-exception-handler.git

Composer:

composer require sageit/phalcon-exception-handler

Usage

This project consists of an included Exception Handler which is supported by both Full suite Phalcon Applications and Micro Apps. The intent is to integrate logging and presentation to generic exceptions.

This should not be used in lieu of Phalcon\Support\Debug functionality. The exception-handler is intended for production handling of known events

Full Application

new Phalcon\Exception\Handler(true,'Error');

This action would instantiation a new Exception Handler which is set globally (true) as the exception_handler. 'Error' Can be replaced with any CSS Class used by a flash service for displaying exceptions.

if Logger is present, and log level is greater than or equal to the LOG_LEVEL defined in the exception, an event will be logged according to the level specified. This is useful for auditing failed authentication attempts.

if Flash is present, a flash alert will be displayed when an Exception is thrown. Exceptions not included in this lib will be automagically converted to a generic "Unknown Exception".

if Flash is not present, a simple echo with Exception encountered: {error message} will return.

Micro Application

Add the following within the Micro class

$this->error(function ($exception) {
  $handler = new \Phalcon\Exception\Handler(false);
  $this
    ->response
    ->setStatusCode($code)
    ->setJsonContent($handler->getJSON($exception))
    ->send();
  die;
});

The same logging action of the Full Application takes place if a Logger Service is present in dependancy injection

Custom Exceptions

You are not limited to the provided Exceptions. Any custom Exception can be created by extending \Phalcon\Exception\Exception

class MyCustomException extends Phalcon\Exception\Exception {
    protected const ERROR_MESSAGE = 'I\'ve created a new custom Exceptions #reasons';
    protected const ERROR_CODE    = 401;
    protected const LOG_MESSAGE = 'My custom exception was activated';
    protected const LOG_LEVEL = 'alert';

LOG_LEVEL Corresponds to the levels utilized by \Phalcon\Logger\Logger

Log Levels

Emergency
Critical
Alert
Error
Warning
Notice
Info
Debug
Custom

Additional Methods

setDisplay

the CSS displayClass used by flash can be altered before an exception is thrown so the default exception handler can apply the correct styling

$handler->setDisplay('Notification');

display

if global error catching is not in place, and you need to utilize the flash display service with a custom class, this can bbe called directly

$handler->display($exception,'Notification');

The exception provided can be any Throwable \Exception

log

if there is a need to log an exception without displaying it, this can be called directly. This will do nothing if no Logger Service is present

$handler->log($exception,'Notification');

getJSON

_as demonstrated in the MicroApp the method getJSON returns a named array with the elements of the exception.

$handler->getJSON($exception);

result

[
  'code' => 500,  //$this->getCode()
  'status' => 'error',
  'message' => 'Exception Encountered' //$this->getMessage()
]

convertException

this static method is called within several other methds but can be used externally to transpose a generic exception into the \Phalcon\Exception\Exception utilized by this handler

\Phalcon\Exception\Handler::convertException($exception);

there is no returned value, as this action is completed as a variable reference

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Sage IT Solutions - Email

Project Link: https://github.com/SageITSolutions/phalcon-exception-handler

sageit / phalcon-exception-handler

Maintainers

Details