feat(Hook): Improved and standardized interfaces

Author: seebeen

Accessible_Hook_Methods.php

@@ -2,7 +2,7 @@
 /**
  * Accessible_Hook_Methods trait file.
  *
- * @package XWP
+ * @package eXtended WordPress
  * @subpackage Contracts\Hook
  */
 

Context.php

@@ -64,6 +64,26 @@ public function display_name(): string {
         };
     }
 
+    /**
+     * Create a context from a slug.
+     *
+     * @param  string $ctx_slug The context slug.
+     * @return Context
+     */
+    public static function fromSlug( string $ctx_slug ): Context {
+        return match ( $ctx_slug ) {
+            'front', 'frontend',
+            'public', 'website'   => self::Frontend,
+            'admin', 'dashboard',
+            'administration'      => self::Admin,
+            'ajax'                => self::Ajax,
+            'cron'                => self::Cron,
+            'rest'                => self::REST,
+            'cli'                 => self::CLI,
+            'global'              => self::Global,
+        };
+    }
+
     /**
      * Check if the current context is valid.
      *

Context_Interface.php

@@ -2,7 +2,7 @@
 /**
  * Context_Interface interface file.
  *
- * @package XWP
+ * @package eXtended WordPress
  * @subpackage Contracts\Hook
  */
 

Hook_Interface.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * Hookable interface file.
+ *
+ * @package eXtended WordPress
+ * @subpackage Contracts\Hook
+ */
+
+namespace XWP\Contracts\Hook;
+
+/**
+ * Hook decorator functionality.
+ *
+ * @template T
+ *
+ * ! Global properties shared among hooks and handlers
+ *
+ * @property-read string                    $tag           Hook name. Can use the `vsprinf` format in combination with `$modifiers`.
+ * @property-read array|int|string|callable $priority      Hook priority. Can be a number, callable, or a string. Strings are treated as filters, which will be applied to the default priority.
+ * @property-read int                       $context       Context bitmask determining where the hook can be invoked.
+ * @property-read string|false              $requires      Prerequisite hook that must be invoked before this hook. Handler classname, or Classname, method array.
+ * @property-read string|array|false        $modifiers     Replacement pairs for the tag name.
+ * @property-read int                       $real_priority Actual priority of the hook.
+ * @property-read array|callable|false      $conditional   Hook conditional. Callable which will be invoked to determine if the hook should be invoked.
+ */
+interface Hookable {
+    /**
+     * Indicates that a hook can be invoked in user-facing pages.
+     *
+     * @var int
+     */
+    public const CTX_FRONTEND = 1;  // 0000001
+
+    /**
+     * Indicates that a hook can be invoked in the admin area.
+     *
+     * @var int
+     */
+    public const CTX_ADMIN = 2;  // 0000010
+
+    /**
+     * Indicates that a hook can be invoked on AJAX requests.
+     *
+     * @var int
+     */
+    public const CTX_AJAX = 4;  // 0000100
+
+    /**
+     * Indicates that a hook can be invoked when a cron job is running.
+     *
+     * @var int
+     */
+    public const CTX_CRON = 8;  // 0001000
+
+    /**
+     * Indicates that a hook can be invoked on REST API requests.
+     *
+     * @var int
+     */
+    public const CTX_REST = 16; // 0010000
+
+    /**
+     * Indicates that a hook can be invoked when WP CLI is running.
+     *
+     * @var int
+     */
+    public const CTX_CLI = 32; // 0100000
+
+    /**
+     * Indicates that a hook can be invoked in any context.
+     *
+     * @var int
+     */
+    public const CTX_GLOBAL = 63; // 0111111
+
+    /**
+     * Hook type. Can be `handler`, `action` or `filter`.
+     *
+     * @var string
+     */
+    public const HOOK_TYPE = self::HOOK_TYPE;
+
+    /**
+     * Set the reflector
+     *
+     * @param  \Reflector $reflector Reflector instance.
+     * @return static
+     */
+    public function set_reflector( \Reflector $reflector ): static;
+
+    /**
+     * Set the hook target.
+     *
+     * @param  array|T $target Hook target.
+     * @return static
+     */
+    public function set_target( array|object $target ): static;
+}

Hookable.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * Handler interface file.
+ *
+ * @package eXtended WordPress
+ * @subpackage Contracts
+ */
+
+namespace XWP\Contracts\Hook;
+
+/**
+ * Handler interface.
+ *
+ * @template<T>
+ *
+ * @property-read Initialize          $strategy    Invocation strategy.
+ * @property-read class-string>T>     $classname   Handler classname.
+ * @property-read bool                $initialized Indicates if the handler has been initialized.
+ * @property-read T|null              $target      Handler target.
+ * @property-read \ReflectionClass<T> $reflector   Reflector instance.
+ */
+interface Initializable extends Hookable {
+    /**
+     * Set the classname.
+     *
+     * @param  class-string<T> $classname Handler classname.
+     * @return static
+     */
+    public function set_classname( string $classname ): static;
+
+    /**
+     * Initializes the handler.
+     *
+     * @return static
+     */
+    public function initialize(): static;
+
+    /**
+     * Check if the handler can be initialized.
+     *
+     * @return bool
+     */
+    public function can_initialize(): bool;
+}

Initializable.php

@@ -0,0 +1,87 @@
+<?php // phpcs:disable PHPCompatibility.Variables.ForbiddenThisUseContexts
+/**
+ * Invoke enum file.
+ *
+ * @package eXtended WordPress
+ * @subpackage Contracts\Hook
+ */
+
+namespace XWP\Contracts\Hook;
+
+/**
+ * Determines initialization strategy for a Handler.
+ */
+enum Initialize: string {
+    /**
+     * Indicates that the handler should be initialized unconditionally.
+     */
+    case Unconditionally = 'unconditional';
+
+    /**
+     * Indicates that the handler should be initialized immediately.
+     */
+    case Immediately = 'immediate';
+
+    /**
+     * Indicates that the handler should be initialized on registration.
+     */
+    case Early = 'early';
+
+    /**
+     * Indicates that the handler should be initialized on demand.
+     *
+     * On demand will initialize the handler when the hook is registered.
+     */
+    case OnDemand = 'on-demand';
+
+    /**
+     * Indicates that the handler should be initialized on specified action.
+     */
+    case Deferred = 'deferred';
+
+    /**
+     * Special case for manually initialized handlers.
+     */
+    case Dynamically = 'dynamic';
+
+    /**
+     * Indicates that the handler should be initialized just in time.
+     *
+     * Just in time will initialize the handler just before the hook is invoked.
+     */
+    case JustInTime = 'just-in-time';
+
+    /**
+     * Check if the tag is valid for the initialization strategy.
+     *
+     * @param  string|null $tag Tag to check.
+     * @return bool
+     */
+    public function is_tag_valid( ?string $tag ): bool {
+        return match ( $this ) {
+            self::OnDemand,
+            self::JustInTime,
+            self::Dynamically,
+            self::Immediately => ! $tag,
+            default => ! ! $tag,
+        };
+    }
+
+    /**
+     * Check if the handler is initialized on demand.
+     *
+     * @return bool
+     */
+    public function is_ondemand(): bool {
+        return self::OnDemand === $this;
+    }
+
+    /**
+     * Check if the handler is initialized just in time.
+     *
+     * @return bool
+     */
+    public function is_just_in_time(): bool {
+        return self::JustInTime === $this;
+    }
+}