README.md

PHP ExceptionHandler library

Traducciones: English

Biblioteca PHP para manejar excepciones.

---

• Instalación
• Requisitos
• Clases disponibles
  • Clase ExceptionHandler
• Excepciones utilizadas
• Uso
• Tests
• Tareas pendientes
• Registro de Cambios
• Contribuir
• Patrocinar
• Licencia

---

Requisitos

• Sistema operativo: Linux | Windows.

• Versiones de PHP: 8.1 | 8.2.

Instalación

La mejor forma de instalar esta extensión es a través de Composer.

Para instalar PHP ExceptionHandler library, simplemente escribe:

composer require Josantonius/exception-handler

El comando anterior sólo instalará los archivos necesarios, si prefieres descargar todo el código fuente puedes utilizar:

composer require josantonius/exception-handler --prefer-source

También puedes clonar el repositorio completo con Git:

git clone https://github.com/josantonius/php-exception-handler.git

Clases disponibles

Clase ExceptionHandler

Josantonius\ExceptionHandler\ExceptionHandler

Establece un manejador de excepciones:

/**
 * Sets a exception handler.
 *
 * @param callable $callback          Exception handler function.
 * @param string[] $runBeforeCallback Method names to call in the exception before run callback.
 * @param string[] $runAfterCallback  Method names to call in the exception after run callback.
 * 
 * @throws NotCallableException     if the callback is not callable.
 * @throws WrongMethodNameException if the method names are not string or are empty.
 * 
 * @see https://www.php.net/manual/en/functions.first_class_callable_syntax.php
 */
public function __construct(
    private callable $callback,
    private array $runBeforeCallback = [],
    private array $runAfterCallback = []
);

Excepciones utilizadas

use Josantonius\ExceptionHandler\Exceptions\NotCallableException;
use Josantonius\ExceptionHandler\Exceptions\WrongMethodNameException;

Uso

Ejemplo de uso para esta biblioteca:

Establece un manejador de excepciones básico

use Josantonius\ExceptionHandler\ExceptionHandler;

function handler(\Throwable $exception) { /* hacer algo */ }

new ExceptionHandler(
    callback: handler(...)
);

/**
 * Si se lanza una excepción, se ejecuta lo siguiente:
 *
 * handler($exception)
 */

Establece los métodos a llamar antes de ejecutar el callback

use Josantonius\ExceptionHandler\ExceptionHandler;

class FooException extends \Exception
{
    public function context(): void { /* hacer algo */ }
}

class Handler {
    public function exceptions(Throwable $exception): void
    {
        if ($exception instanceof FooException) {
            /* hacer algo */
        }
    }
}

new ExceptionHandler(
    callback: (new Handler())->exceptions(...),
    runBeforeCallback: ['context']
);

/**
 * Si se lanza FooException(), se ejecuta lo siguiente:
 * 
 * FooException->context()
 * Handler->exceptions($exception)
 */

Establece los métodos a ejecutar después de llamar al callback

use Josantonius\ExceptionHandler\ExceptionHandler;

class FooException extends \Exception
{
    public function report(): void { /* hacer algo */ }

    public function render(): void { /* hacer algo */ }
}

class Handler {
    public static function exceptions(Throwable $exception): void
    {
        if ($exception instanceof FooException) {
            /* hacer algo */
        }
    }
}

new ExceptionHandler(
    callback: Handler::exceptions(...),
    runAfterCallback: ['report', 'render']
);

/**
 * Si se lanza FooException(), se ejecuta lo siguiente:
 * 
 * Handler::exceptions($exception)
 * FooException->report()
 * FooException->render()
 */

Sets methods to execute before and after calling the callback

use Josantonius\ExceptionHandler\ExceptionHandler;

class FooException extends \Exception
{
    public function context(): void { /* do something */ }

    public function report(): void { /* do something */ }

    public function render(): void { /* do something */ }
}

function exceptionHandler(Throwable $exception) { /* do something */ }

new ExceptionHandler(
    callback: exceptionHandler(...),
    runBeforeCallback: ['context', 'logger'],
    runAfterCallback: ['report', 'render']
);

/**
 * If FooException() is thrown, the following is executed:
 * 
 * FooException->context()
 * exceptionHandler($exception)
 * FooException->report()
 * FooException->render()
 * 
 * Se ignora FooException->logger(), no existe en la excepción.
 */

Tests

Para ejecutar las pruebas necesitarás Composer y seguir los siguientes pasos:

git clone https://github.com/josantonius/php-exception-handler.git

cd php-exception-handler

composer install

Ejecutar pruebas unitarias con PHPUnit:

composer phpunit

Ejecutar pruebas de estándares de código con PHPCS:

composer phpcs

Ejecutar pruebas con PHP Mess Detector para detectar inconsistencias en el estilo de codificación:

composer phpmd

Ejecutar todas las pruebas anteriores:

composer tests

Tareas pendientes

• Añadir nueva funcionalidad
• Mejorar pruebas
• Mejorar documentación
• Mejorar la traducción al inglés en el archivo README
• Refactorizar código para las reglas de estilo de código deshabilitadas (ver phpmd.xml y phpcs.xml)

Registro de Cambios

Los cambios detallados de cada versión se documentan en las notas de la misma.

Contribuir

Por favor, asegúrate de leer la Guía de contribución antes de hacer un pull request, comenzar una discusión o reportar un issue.

¡Gracias por colaborar! ❤️

Patrocinar

Si este proyecto te ayuda a reducir el tiempo de desarrollo, puedes patrocinarme para apoyar mi trabajo 😊

Licencia

Este repositorio tiene una licencia MIT License.

Copyright © 2022-actualidad, Josantonius