Merge pull request #5713 from kenjis/feat-route-add-callable

feat: can add route handler as callable

Author: kenjis

system/Router/RouteCollection.php

@@ -1137,6 +1137,11 @@ protected function create(string $verb, string $from, $to, ?array $options = nul
             $from = trim($from, '/');
         }
 
+        // When redirecting to named route, $to is an array like `['zombies' => '\Zombies::index']`.
+        if (is_array($to) && count($to) === 2) {
+            $to = $this->processArrayCallableSyntax($from, $to);
+        }
+
         $options = array_merge($this->currentOptions ?? [], $options ?? []);
 
         // Route priority detect
@@ -1227,6 +1232,47 @@ protected function create(string $verb, string $from, $to, ?array $options = nul
         }
     }
 
+    private function processArrayCallableSyntax(string $from, array $to): string
+    {
+        // [classname, method]
+        // eg, [Home::class, 'index']
+        if (is_callable($to, true, $callableName)) {
+            // If the route has placeholders, add params automatically.
+            $params = $this->getMethodParams($from);
+
+            return '\\' . $callableName . $params;
+        }
+
+        // [[classname, method], params]
+        // eg, [[Home::class, 'index'], '$1/$2']
+        if (
+            isset($to[0], $to[1])
+            && is_callable($to[0], true, $callableName)
+            && is_string($to[1])
+        ) {
+            $to = '\\' . $callableName . '/' . $to[1];
+        }
+
+        return $to;
+    }
+
+    /**
+     * Returns the method param string like `/$1/$2` for placeholders
+     */
+    private function getMethodParams(string $from): string
+    {
+        preg_match_all('/\(.+?\)/', $from, $matches);
+        $count = is_countable($matches[0]) ? count($matches[0]) : 0;
+
+        $params = '';
+
+        for ($i = 1; $i <= $count; $i++) {
+            $params .= '/$' . $i;
+        }
+
+        return $params;
+    }
+
     /**
      * Compares the subdomain(s) passed in against the current subdomain
      * on this page request.

tests/system/Router/RouteCollectionTest.php

@@ -15,6 +15,7 @@
 use CodeIgniter\Router\Exceptions\RouterException;
 use CodeIgniter\Test\CIUnitTestCase;
 use Config\Modules;
+use Tests\Support\Controllers\Hello;
 
 /**
  * @backupGlobals enabled
@@ -58,6 +59,45 @@ public function testBasicAdd()
         $this->assertSame($expects, $routes);
     }
 
+    public function testBasicAddCallable()
+    {
+        $routes = $this->getCollector();
+
+        $routes->add('home', [Hello::class, 'index']);
+
+        $routes  = $routes->getRoutes();
+        $expects = [
+            'home' => '\Tests\Support\Controllers\Hello::index',
+        ];
+        $this->assertSame($expects, $routes);
+    }
+
+    public function testBasicAddCallableWithParamsString()
+    {
+        $routes = $this->getCollector();
+
+        $routes->add('product/(:num)/(:num)', [[Hello::class, 'index'], '$2/$1']);
+
+        $routes  = $routes->getRoutes();
+        $expects = [
+            'product/([0-9]+)/([0-9]+)' => '\Tests\Support\Controllers\Hello::index/$2/$1',
+        ];
+        $this->assertSame($expects, $routes);
+    }
+
+    public function testBasicAddCallableWithParamsWithoutString()
+    {
+        $routes = $this->getCollector();
+
+        $routes->add('product/(:num)/(:num)', [Hello::class, 'index']);
+
+        $routes  = $routes->getRoutes();
+        $expects = [
+            'product/([0-9]+)/([0-9]+)' => '\Tests\Support\Controllers\Hello::index/$1/$2',
+        ];
+        $this->assertSame($expects, $routes);
+    }
+
     public function testAddPrefixesDefaultNamespaceWhenNoneExist()
     {
         $routes = $this->getCollector();

user_guide_src/source/incoming/routing.rst

@@ -145,6 +145,31 @@ routes. With the examples URLs from above:
 
 will only match **product/123** and generate 404 errors for other example.
 
+
+Array Callable Syntax
+=====================
+
+Since v4.2.0, you can use array callable syntax to specify the controller:
+
+.. literalinclude:: routing/004_1.php
+   :lines: 2-
+
+Or using ``use`` keyword:
+
+.. literalinclude:: routing/004_2.php
+   :lines: 2-
+
+If there are placeholders, it will automatically set the parameters in the specified order:
+
+.. literalinclude:: routing/004_3.php
+   :lines: 2-
+
+But the auto-configured parameters may not be correct if you use regular expressions in routes.
+In such a case, you can specify the parameters manually:
+
+.. literalinclude:: routing/004_4.php
+   :lines: 2-
+
 Custom Placeholders
 ===================
 

user_guide_src/source/incoming/routing/004_1.php

@@ -0,0 +1,3 @@
+<?php
+
+$routes->get('/', [\App\Controllers\Home::class, 'index']);

user_guide_src/source/incoming/routing/004_2.php

@@ -0,0 +1,5 @@
+<?php
+
+use App\Controllers\Home;
+
+$routes->get('/', [Home::class, 'index']);

user_guide_src/source/incoming/routing/004_3.php

@@ -0,0 +1,8 @@
+<?php
+
+use App\Controllers\Product;
+
+$routes->get('product/(:num)/(:num)', [Product::class, 'index']);
+
+// The above code is the same as the following:
+$routes->get('product/(:num)/(:num)', 'Product::index/$1/$2');

user_guide_src/source/incoming/routing/004_4.php

@@ -0,0 +1,8 @@
+<?php
+
+use App\Controllers\Product;
+
+$routes->get('product/(:num)/(:num)', [[Product::class, 'index'], '$2/$1']);
+
+// The above code is the same as the following:
+$routes->get('product/(:num)/(:num)', 'Product::index/$2/$1');