chore: added documentation (#16)

Reviewed-on: #16
Co-authored-by: Ron Rise <ron@siteworxpro.com>
Co-committed-by: Ron Rise <ron@siteworxpro.com>

src/Http/Middleware/Middleware.php

@@ -9,30 +9,60 @@ use League\Route\Route;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+/**
+ * Base middleware helper for extracting route callables.
+ *
+ * This abstract middleware provides a utility method to inspect a League\Route
+ * dispatcher and obtain the underlying route callable as a [class, method] tuple.
+ *
+ * @package Siteworxpro\App\Http\Middleware
+ */
 abstract class Middleware implements MiddlewareInterface
 {
-
-    protected function extractRouteCallable($request, RequestHandlerInterface | Dispatcher $handler): array|null
-    {
+    /**
+     * Extract the route callable [class, method] from a League\Route dispatcher.
+     *
+     * When the provided handler is a League\Route\Dispatcher, this inspects its
+     * middleware stack, looks at the last segment (the resolved Route), and
+     * attempts to normalize its callable into a [class, method] pair.
+     *
+     * Supported callable forms:
+     * - array callable: [object|class-string, method-string]
+     * - string callable: "ClassName::methodName"
+     *
+     * Returns null when the handler is not a Dispatcher, the stack is empty,
+     * or the callable cannot be parsed.
+     *
+     * @param RequestHandlerInterface|Dispatcher $handler The downstream handler or dispatcher.
+     *
+     * @return array{0: class-string|object|null, 1: string|null}|null Tuple of [class|object, method] or null.
+     */
+    protected function extractRouteCallable(
+        RequestHandlerInterface|Dispatcher $handler
+    ): array|null {
+        // Only proceed if this is a League\Route dispatcher.
         if (!$handler instanceof Dispatcher) {
             return null;
         }
 
         /** @var Route | null $lastSegment */
+        // Retrieve the last middleware in the stack, which should be the Route.
         $lastSegment = array_last($handler->getMiddlewareStack());
 
         if ($lastSegment === null) {
             return null;
         }
 
+        // Obtain the callable associated with the route.
         $callable = $lastSegment->getCallable();
         $class = null;
         $method = null;
 
+        // Handle array callable: [object|class-string, 'method']
         if (is_array($callable) && count($callable) === 2) {
             [$class, $method] = $callable;
         } elseif (is_string($callable)) {
-            // Handle the case where the callable is a string (e.g., 'ClassName::methodName')
+            // Handle string callable: 'ClassName::methodName'
             [$class, $method] = explode('::', $callable);
         }