NEW RouteMatcher can now be extended in user code

- Created a `RouteMatcherInterface` to describe the required API of a route matcher
- Created `Match` to provide better type saftey for the return value of the route matcher
- The `RouteMatcher` is now resolved through the application container

Author: ScopeyNZ

config/apidoc.php

@@ -242,4 +242,11 @@
      *
      */
     'faker_seed' => null,
+
+    /**
+     * If you would like to customize how routes are matched beyond the route configuration you may
+     * declare your own implementation of RouteMatcherInterface
+     *
+     */
+    'routeMatcher' => \Mpociot\ApiDoc\Matching\RouteMatcher::class,
 ];

src/ApiDocGeneratorServiceProvider.php

@@ -5,6 +5,8 @@
 use Illuminate\Support\ServiceProvider;
 use Mpociot\ApiDoc\Commands\GenerateDocumentation;
 use Mpociot\ApiDoc\Commands\RebuildDocumentation;
+use Mpociot\ApiDoc\Matching\RouteMatcher;
+use Mpociot\ApiDoc\Matching\RouteMatcherInterface;
 
 class ApiDocGeneratorServiceProvider extends ServiceProvider
 {
@@ -33,6 +35,9 @@ public function boot()
                 RebuildDocumentation::class,
             ]);
         }
+
+        // Bind the route matcher implementation
+        $this->app->bind(RouteMatcherInterface::class, $this->app['config']['apidoc']['routeMatcher']);
     }
 
     /**
@@ -42,6 +47,5 @@ public function boot()
      */
     public function register()
     {
-        //
     }
 }

src/Commands/GenerateDocumentation.php

@@ -7,7 +7,8 @@
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\URL;
 use Mpociot\ApiDoc\Extracting\Generator;
-use Mpociot\ApiDoc\Matching\RouteMatcher;
+use Mpociot\ApiDoc\Matching\RouteMatcher\Match;
+use Mpociot\ApiDoc\Matching\RouteMatcherInterface;
 use Mpociot\ApiDoc\Tools\DocumentationConfig;
 use Mpociot\ApiDoc\Tools\Flags;
 use Mpociot\ApiDoc\Tools\Utils;
@@ -44,8 +45,15 @@ class GenerateDocumentation extends Command
      */
     private $baseUrl;
 
-    public function __construct()
+    /**
+     * @var RouteMatcherInterface
+     */
+    private $routeMatcher;
+
+    public function __construct(RouteMatcherInterface $routeMatcher)
     {
+        $this->routeMatcher = $routeMatcher;
+
         parent::__construct();
     }
 
@@ -65,8 +73,7 @@ public function handle()
 
         URL::forceRootUrl($this->baseUrl);
 
-        $routeMatcher = new RouteMatcher($this->docConfig->get('routes'), $this->docConfig->get('router'));
-        $routes = $routeMatcher->getRoutes();
+        $routes = $this->routeMatcher->getRoutes($this->docConfig->get('routes'), $this->docConfig->get('router'));
 
         $generator = new Generator($this->docConfig);
         $parsedRoutes = $this->processRoutes($generator, $routes);
@@ -87,15 +94,15 @@ public function handle()
 
     /**
      * @param \Mpociot\ApiDoc\Extracting\Generator $generator
-     * @param array $routes
+     * @param Match[] $routes
      *
      * @return array
      */
     private function processRoutes(Generator $generator, array $routes)
     {
         $parsedRoutes = [];
         foreach ($routes as $routeItem) {
-            $route = $routeItem['route'];
+            $route = $routeItem->getRoute();
             /** @var Route $route */
             $messageFormat = '%s route: [%s] %s';
             $routeMethods = implode(',', $generator->getMethods($route));
@@ -107,7 +114,7 @@ private function processRoutes(Generator $generator, array $routes)
             }
 
             try {
-                $parsedRoutes[] = $generator->processRoute($route, $routeItem['apply'] ?? []);
+                $parsedRoutes[] = $generator->processRoute($route, $routeItem->getRules());
                 $this->info(sprintf($messageFormat, 'Processed', $routeMethods, $routePath));
             } catch (\Exception $exception) {
                 $this->warn(sprintf($messageFormat, 'Skipping', $routeMethods, $routePath).' - '.$exception->getMessage());

src/Matching/RouteMatcher.php

@@ -6,35 +6,21 @@
 use Illuminate\Routing\Route;
 use Illuminate\Support\Facades\Route as RouteFacade;
 use Illuminate\Support\Str;
+use Mpociot\ApiDoc\Matching\RouteMatcher\Match;
 
-class RouteMatcher
+class RouteMatcher implements RouteMatcherInterface
 {
-    /**
-     * @var string
-     */
-    protected $router;
-
-    /**
-     * @var array
-     */
-    protected $routeRules;
-
-    public function __construct(array $routeRules = [], string $router = 'laravel')
+    public function getRoutes(array $routeRules = [], string $router = 'laravel')
     {
-        $this->router = $router;
-        $this->routeRules = $routeRules;
-    }
+        $usingDingoRouter = strtolower($router) == 'dingo';
 
-    public function getRoutes()
-    {
-        $usingDingoRouter = strtolower($this->router) == 'dingo';
-
-        return $this->getRoutesToBeDocumented($this->routeRules, $usingDingoRouter);
+        return $this->getRoutesToBeDocumented($routeRules, $usingDingoRouter);
     }
 
-    protected function getRoutesToBeDocumented(array $routeRules, bool $usingDingoRouter = false)
+    private function getRoutesToBeDocumented(array $routeRules, bool $usingDingoRouter = false)
     {
         $allRoutes = $this->getAllRoutes($usingDingoRouter);
+
         $matchedRoutes = [];
 
         foreach ($routeRules as $routeRule) {
@@ -50,11 +36,7 @@ protected function getRoutesToBeDocumented(array $routeRules, bool $usingDingoRo
                 }
 
                 if ($this->shouldIncludeRoute($route, $routeRule, $includes, $usingDingoRouter)) {
-                    $matchedRoutes[] = [
-                        'route' => $route,
-                        'apply' => $routeRule['apply'] ?? [],
-                    ];
-                    continue;
+                    $matchedRoutes[] = new Match($route, $routeRule['apply'] ?? []);
                 }
             }
         }

src/Matching/RouteMatcher/Match.php

@@ -0,0 +1,76 @@
+<?php
+namespace Mpociot\ApiDoc\Matching\RouteMatcher;
+
+use Illuminate\Routing\Route;
+
+class Match implements \ArrayAccess
+{
+    /**
+     * @var Route
+     */
+    protected $route;
+
+    /**
+     * @var array
+     */
+    protected $rules;
+
+    /**
+     * Match constructor.
+     * @param Route $route
+     * @param array $applyRules
+     */
+    public function __construct(Route $route, array $applyRules)
+    {
+        $this->route = $route;
+        $this->rules = $applyRules;
+    }
+
+    /**
+     * @return Route
+     */
+    public function getRoute()
+    {
+        return $this->route;
+    }
+
+    /**
+     * @return array
+     */
+    public function getRules()
+    {
+        return $this->rules;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetExists($offset)
+    {
+        return is_callable([$this, 'get' . ucfirst($offset)]);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetGet($offset)
+    {
+        return call_user_func([$this, 'get' . ucfirst($offset)]);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetSet($offset, $value)
+    {
+        return $this->$offset = $value;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetUnset($offset)
+    {
+        $this->$offset = null;
+    }
+}

src/Matching/RouteMatcherInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Mpociot\ApiDoc\Matching;
+
+use Mpociot\ApiDoc\Matching\RouteMatcher\Match;
+
+interface RouteMatcherInterface
+{
+    /**
+     * Resolve matched routes that should be documented
+     * 
+     * @param array $routeRules Route rules defined under the "routes" section in config
+     * @param string $router
+     * @return Match[]
+     */
+    public function getRoutes(array $routeRules = [], string $router = 'laravel');
+}