From 07105970622c9e1ac4f48dfa05601b1f94e897be Mon Sep 17 00:00:00 2001
From: flashwave <me@flash.moe>
Date: Thu, 7 Sep 2023 22:22:41 +0000
Subject: [PATCH] Added abstract RouteHandler and documentation.

---
 VERSION                           |  2 +-
 src/Routing/IRouteHandler.php     | 10 +++++++++-
 src/Routing/Route.php             | 20 ++++++++++++++++++++
 src/Routing/RouteHandler.php      | 14 ++++++++++++++
 src/Routing/RouteHandlerTrait.php |  4 ++++
 tests/RouterTest.php              |  5 ++---
 6 files changed, 50 insertions(+), 5 deletions(-)
 create mode 100644 src/Routing/RouteHandler.php

diff --git a/VERSION b/VERSION
index f7b18b5..6d1d662 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.2309.72158
+0.2309.72221
diff --git a/src/Routing/IRouteHandler.php b/src/Routing/IRouteHandler.php
index 3122c4d..adadb91 100644
--- a/src/Routing/IRouteHandler.php
+++ b/src/Routing/IRouteHandler.php
@@ -1,10 +1,18 @@
 <?php
 // IRouteHandler.php
 // Created: 2023-09-06
-// Updated: 2023-09-06
+// Updated: 2023-09-07
 
 namespace Index\Routing;
 
+/**
+ * Provides the interface for IRouter::register().
+ */
 interface IRouteHandler {
+    /**
+     * Registers routes on a given IRouter instance.
+     *
+     * @param IRouter $router Target router.
+     */
     public function registerRoutes(IRouter $router): void;
 }
diff --git a/src/Routing/Route.php b/src/Routing/Route.php
index 678d454..c2a95d2 100644
--- a/src/Routing/Route.php
+++ b/src/Routing/Route.php
@@ -9,21 +9,41 @@ use Attribute;
 use ReflectionObject;
 use UnexpectedValueException;
 
+/**
+ * Provides an attribute for marking methods in a class as routes.
+ */
 #[Attribute]
 class Route {
+    /** @internal */
     public function __construct(
         private string $method,
         private string $path
     ) {}
 
+    /**
+     * Returns the target method name.
+     *
+     * @return string
+     */
     public function getMethod(): string {
         return $this->method;
     }
 
+    /**
+     * Returns the target path.
+     *
+     * @return string
+     */
     public function getPath(): string {
         return $this->path;
     }
 
+    /**
+     * Reads attributes from methods in a IRouteHandler instance and registers them to a given IRouter instance.
+     *
+     * @param IRouter $router Router instance.
+     * @param IRouteHandler $handler Handler instance.
+     */
     public static function handleAttributes(IRouter $router, IRouteHandler $handler): void {
         $objectInfo = new ReflectionObject($handler);
         $methodInfos = $objectInfo->getMethods();
diff --git a/src/Routing/RouteHandler.php b/src/Routing/RouteHandler.php
new file mode 100644
index 0000000..5b6ed52
--- /dev/null
+++ b/src/Routing/RouteHandler.php
@@ -0,0 +1,14 @@
+<?php
+// RouteHandler.php
+// Created: 2023-09-07
+// Updated: 2023-09-07
+
+namespace Index\Routing;
+
+/**
+ * Provides an abstract class version of IRouteHandler that already includes the trait as well,
+ *  letting you only have to use one use statement rather than two!
+ */
+abstract class RouteHandler implements IRouteHandler {
+    use RouteHandlerTrait;
+}
diff --git a/src/Routing/RouteHandlerTrait.php b/src/Routing/RouteHandlerTrait.php
index 3593fd5..6e669bb 100644
--- a/src/Routing/RouteHandlerTrait.php
+++ b/src/Routing/RouteHandlerTrait.php
@@ -5,6 +5,10 @@
 
 namespace Index\Routing;
 
+/**
+ * Provides an implementation of IRouteHandler::registerRoutes that uses the attributes.
+ * For more advanced use, everything can be use'd separately and Route::handleAttributes called manually.
+ */
 trait RouteHandlerTrait {
     public function registerRoutes(IRouter $router): void {
         Route::handleAttributes($router, $this);
diff --git a/tests/RouterTest.php b/tests/RouterTest.php
index c804378..6fbfcdd 100644
--- a/tests/RouterTest.php
+++ b/tests/RouterTest.php
@@ -8,6 +8,7 @@ declare(strict_types=1);
 use PHPUnit\Framework\TestCase;
 use Index\Routing\IRouteHandler;
 use Index\Routing\Route;
+use Index\Routing\RouteHandler;
 use Index\Routing\RouteHandlerTrait;
 use Index\Routing\Router;
 
@@ -145,9 +146,7 @@ final class RouterTest extends TestCase {
         $this->assertEquals('avatar', $router->resolve('POST', '/avatar')->run());
         $this->assertEquals('static', $router->resolve('PUT', '/static')->run());
 
-        $badHandler = new class implements IRouteHandler {
-            use RouteHandlerTrait;
-
+        $badHandler = new class extends RouteHandler {
             #[Route('GET', '/')]
             #[Route('POST', '/meow')]
             public function getPostBad() {