feat(Hook): Improved and standardized interfaces

Author: seebeen

Hook/Hookable.php

@@ -8,20 +8,25 @@
 
 namespace XWP\Contracts\Hook;
 
+use ReflectionClass;
+use ReflectionMethod;
+
 /**
  * Hook decorator functionality.
  *
- * @template T
- *
  * ! Global properties shared among hooks and handlers
  *
+ * @template THndlr of object
+ * @template TRflct of ReflectionClass<THndlr>|ReflectionMethod
+ *
  * @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        $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.
+ * @property-read TRflct                    $reflector     Reflector instance.
  */
 interface Hookable {
     /**
@@ -83,16 +88,8 @@ interface Hookable {
     /**
      * 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.
+     * @param  TRflct $reflector Reflector instance.
      * @return static
      */
-    public function set_target( array|object $target ): static;
+    public function set_reflector( ReflectionClass|ReflectionMethod $reflector ): static;
 }

Hook/Initializable.php

@@ -8,25 +8,43 @@
 
 namespace XWP\Contracts\Hook;
 
+use ReflectionClass;
+
 /**
  * Handler interface.
  *
- * @template<T>
+ * @template THndlr of object
+ *
+ * @property-read Initialize              $strategy    Invocation strategy.
+ * @property-read class-string<THndlr>    $classname   Handler classname.
+ * @property-read bool                    $initialized Indicates if the handler has been initialized.
+ * @property THndlr|null                  $target      Handler target.
  *
- * @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.
+ * @extends Hookable<THndlr,ReflectionClass<THndlr>>
  */
 interface Initializable extends Hookable {
     /**
      * Set the classname.
      *
-     * @param  class-string<T> $classname Handler classname.
+     * @param  class-string<THndlr> $classname Handler classname.
      * @return static
      */
-    public function set_classname( string $classname ): static;
+    public function with_classname( string $classname ): static;
+
+    /**
+     * Set the handler instance.
+     *
+     * @param  THndlr $instance Handler instance.
+     * @return static
+     */
+    public function with_target( object $instance ): static;
+
+    /**
+     * Get the handler instance.
+     *
+     * @return THndlr
+     */
+    public function get_target(): ?object;
 
     /**
      * Initializes the handler.

Hook/Invokable.php

@@ -8,25 +8,36 @@
 
 namespace XWP\Contracts\Hook;
 
+use ReflectionMethod;
+
 /**
  * Invokable interface. Used by actions and filters.
  *
- * @template T
+ * @template THndlr of object
+ *
+ * @property-read Invoke                $strategy Invocation strategy.
+ * @property-read Initializable<THndlr> $handler  Handler instance.
+ * @property-read bool                  $invoked  Flag indicating if the hook has been invoked.
+ * @property-read int                   $args     Number of arguments the hook accepts.
  *
- * @property-read Invoke               $strategy Invocation strategy.
- * @property-read Initializable        $handler  Handler instance.
- * @property-read bool                 $invoked  Flag indicating if the hook has been invoked.
- * @property-read int                  $args     Number of arguments the hook accepts.
- * @property-read \ReflectionMethod<T> $reflector Reflector instance.
+ * @extends Hookable<THndlr,ReflectionMethod>
  */
 interface Invokable extends Hookable {
     /**
      * Set the hook handler.
      *
-     * @param  Initializable<T> $handler Handler instance.
+     * @param  Initializable<THndlr> $handler Handler instance.
+     * @return static
+     */
+    public function with_handler( Initializable $handler ): static;
+
+    /**
+     * Set the hook target.
+     *
+     * @param  string $method Method name.
      * @return static
      */
-    public function set_handler( Initializable $handler ): static;
+    public function with_target( string $method ): static;
 
     /**
      * Check if the hook can be invoked.