Skip to content

README.md

Latest commit

 

History

History
executable file
·
575 lines (386 loc) · 11.8 KB

README.md

File metadata and controls

executable file
·
575 lines (386 loc) · 11.8 KB

PHP Hook library

Latest Stable Version License Total Downloads CI CodeCov PSR1 PSR4 PSR12

Traducciones: English

Biblioteca para manejo de hooks en PHP.

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 Hook library, simplemente escribe:

composer require josantonius/hook

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

composer require josantonius/hook --prefer-source

También puedes clonar el repositorio completo con Git:

git clone https://github.com/josantonius/php-hook.git

Clases disponibles

Instancia Action

Josantonius\Hook\Action

Obtener el nivel de prioridad de la acción:

public function getPriority(): int;

Obtener el resultado de la llamada a la acción:

public function getResult(): mixed;

Comprueba si la acción se realiza solo una vez:

public function isOnce(): bool;

Comprueba si la acción ya se ha realizado:

public function wasDone(): bool;

Clase Hook

Josantonius\Hook\Hook

Registrar nuevo gancho:

public function __construct(private string $name);

Agregar acción en el gancho:

/**
 * La acción se mantendrá después de realizar las acciones y estará disponible si se hacen de nuevo.
 * 
 * @see https://www.php.net/manual/en/functions.first_class_callable_syntax.php
 * 
 * @return Action Acción agregada.
 */
public function addAction(callable $callback, int $priority = Priority::NORMAL): Action;

Agregar acción en el gancho una vez:

/**
 * La acción solo se realizará una vez y se borrará una vez realizada.
 * 
 * Se recomienda utilizar este método para liberar las acciones de la
 * memoria si las acciones del gancho solo se van a realizar una vez.
 * 
 * @return Action Acción agregada.
 */
public function addActionOnce(callable $callback, int $priority = Priority::NORMAL): Action;

Ejecutar las acciones agregadas al gancho:

/**
 * @throws HookException si las acciones ya se han realizado.
 * @throws HookException si no se han añadido acciones para el gancho.
 * 
 * @return Action[] Acciones hechas.
 */
public function doActions(mixed ...$arguments): array;

Comprueba si el gancho tiene acciones:

/**
 * Verdadero si el gancho tiene alguna acción incluso si la acción
 * se ha hecho antes (acciones recurrentes creadas con addAction).
 */
public function hasActions(): bool;

Comprueba si el gancho tiene acciones sin realizar:

/**
 * Verdadero si el gancho tiene alguna acción sin realizar.
 */
public function hasUndoneActions(): bool;

Comprueba si las acciones se han realizado al menos una vez:

/**
 * Si doActions fue ejecutado al menos una vez.
 */
public function hasDoneActions(): bool;

Obtener el nombre del hook:

public function getName(): string;

Clase Priority

Josantonius\Hook\Priority

Constantes disponibles:

public const HIGHEST = 50;
public const HIGH    = 100;
public const NORMAL  = 150;
public const LOW     = 200;
public const LOWEST  = 250;

Excepciones utilizadas

use Josantonius\Hook\Exceptions\HookException;

Uso

Ejemplos de uso de esta biblioteca:

Registrar nuevo gancho

$hook = new Hook('foo');

Agregar acciones en el gancho

use Josantonius\Hook\Hook;

class Foo {
    public static function bar() { /* hacer algo */ }
    public static function baz() { /* hacer algo */ }
}

$hook = new Hook('name');

$hook->addAction(Foo::bar(...));
$hook->addAction(Foo::baz(...));

Agregar acciones con prioridad personalizada en el gancho

use Josantonius\Hook\Hook;
use Josantonius\Hook\Priority;

class Foo {
    public static function bar() { /* hacer algo */ }
    public static function baz() { /* hacer algo */ }
}

$hook = new Hook('name');

$hook->addAction(Foo::bar(...), Priority::LOW);
$hook->addAction(Foo::baz(...), Priority::HIGH);

Agregar acciones en el gancho una vez

use Josantonius\Hook\Hook;

class Foo {
    public function bar() { /* hacer algo */ }
    public function baz() { /* hacer algo */ }
}

$foo  = new Foo();
$hook = new Hook('name');

$hook->addActionOnce($foo->bar(...));
$hook->addActionOnce($foo->baz(...));

Agregar acciones una vez con prioridad personalizada en el gancho

use Josantonius\Hook\Hook;
use Josantonius\Hook\Priority;

class Foo {
    public function bar() { /* hacer algo */ }
    public function baz() { /* hacer algo */ }
}

$foo  = new Foo();
$hook = new Hook('name');

$hook->addActionOnce($foo->bar(...), Priority::LOW);
$hook->addActionOnce($foo->baz(...), Priority::HIGH);

Realizar acciones con la misma prioridad

use Josantonius\Hook\Hook;

function one() { /* hacer algo */ }
function two() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(one(...));
$hook->addAction(two(...));

/**
 * Las acciones se ejecutarán según su orden natural:
 * 
 *  one(), two()...
 */
$hook->doActions();

Realizar acciones con diferente prioridad

use Josantonius\Hook\Hook;
use Josantonius\Hook\Priority;

function a() { /* hacer algo */ }
function b() { /* hacer algo */ }
function c() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(a(...), priority::LOW);
$hook->addAction(b(...), priority::NORMAL);
$hook->addAction(c(...), priority::HIGHEST);

/**
 * Las acciones se ejecutarán según su prioridad:
 * 
 * c(), b(), a()...
 */
$hook->doActions();

Realizar acciones con argumentos

use Josantonius\Hook\Hook;

function foo($foo, $bar) { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(foo(...));

$hook->doActions('foo', 'bar');

Realizar acciones de forma recurrente

use Josantonius\Hook\Hook;

function a() { /* hacer algo */ }
function b() { /* hacer algo */ }
function c() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(a(...));
$hook->addAction(b(...));
$hook->addActionOnce(c(...)); // Se hará una sola vez

$hook->doActions(); // a(), b(), c()

$hook->doActions(); // a(), b()

Realizar las acciones solo una vez

use Josantonius\Hook\Hook;

function one() { /* hacer algo */ }
function two() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addActionOnce(one(...));
$hook->addActionOnce(tho(...));

$hook->doActions();

// $hook->doActions(); Lanzaría una excepción ya que no hay acciones que realizar

Comprueba si el gancho tiene acciones

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(foo());

$hook->hasActions(); // Verdadero

$hook->doActions();

$hook->hasActions(); // Verdadero ya que la acción es recurrente y permanece almacenada

Comprueba si el gancho tiene acciones sin realizar

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(foo());

$hook->hasUndoneActions(); // Verdadero

$hook->doActions();

$hook->hasUndoneActions(); // Falso ya que no hay acciones no realizadas

Comprueba si las acciones se han realizado al menos una vez

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$hook->addAction(foo());

$hook->hasDoneActions(); // Falso

$hook->doActions();

$hook->hasDoneActions(); // Verdadero ya que las acciones se hicieron

Obtener el nombre del hook

use Josantonius\Hook\Hook;

$hook = new Hook('foo');

$name = $hook->getName(); // foo

Obtener el nivel de prioridad de la acción

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$action = $hook->addAction(foo());

$action->getPriority();

Obtener el resultado de la llamada a la acción

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$action = $hook->addAction(foo());

$action->getResult();

Comprueba si la acción se realiza solo una vez

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$action = $hook->addAction(foo());

$action->isOnce(); // Falso

$action = $hook->addActionOnce(foo());

$action->isOnce(); // Verdadero

Comprueba si la acción ya se ha realizado

use Josantonius\Hook\Hook;

function foo() { /* hacer algo */ }

$hook = new Hook('name');

$action = $hook->addAction(foo());

$action->wasDone(); // Falso

$hook->doActions();

$action->wasDone(); // Verdadero

Tests

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

git clone https://github.com/josantonius/php-hook.git
cd php-hook
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)
  • Hacer que Action->runCallback() sea accesible sólo para la clase Hook
  • ¿Agregar un método para eliminar una acción?
  • ¿Agregar la opción de añadir ID en las acciones?

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 © 2017-actualidad, Josantonius