[9.x] Adds implicit Enum route binding (#40281)

* Adds implicit Backed Enum route binding

* Fixes tests on PHP 8.0

* Only accepts backed enums with `string` backing type

* Refactors name of `isParameterBackedEnum`

* Rewords docs

* formatting

* fix variable

Co-authored-by: Taylor Otwell <[email protected]>

Author: nunomaduro

src/Illuminate/Foundation/Exceptions/Handler.php

@@ -17,6 +17,7 @@
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Response;
+use Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException;
 use Illuminate\Routing\Router;
 use Illuminate\Session\TokenMismatchException;
 use Illuminate\Support\Arr;
@@ -85,6 +86,7 @@ class Handler implements ExceptionHandlerContract
     protected $internalDontReport = [
         AuthenticationException::class,
         AuthorizationException::class,
+        BackedEnumCaseNotFoundException::class,
         HttpException::class,
         HttpResponseException::class,
         ModelNotFoundException::class,
@@ -352,6 +354,7 @@ public function render($request, Throwable $e)
     protected function prepareException(Throwable $e)
     {
         return match (true) {
+            $e instanceof BackedEnumCaseNotFoundException => new NotFoundHttpException($e->getMessage(), $e),
             $e instanceof ModelNotFoundException => new NotFoundHttpException($e->getMessage(), $e),
             $e instanceof AuthorizationException => new AccessDeniedHttpException($e->getMessage(), $e),
             $e instanceof TokenMismatchException => new HttpException(419, $e->getMessage(), $e),

src/Illuminate/Routing/Exceptions/BackedEnumCaseNotFoundException.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Illuminate\Routing\Exceptions;
+
+use RuntimeException;
+
+class BackedEnumCaseNotFoundException extends RuntimeException
+{
+    /**
+     * Create a new exception instance.
+     *
+     * @param  string  $backedEnumClass
+     * @param  string  $case
+     * @return void
+     */
+    public function __construct($backedEnumClass, $case)
+    {
+        parent::__construct("Case [{$case}] not found on Backed Enum [{$backedEnumClass}].");
+    }
+}

src/Illuminate/Routing/ImplicitRouteBinding.php

@@ -5,6 +5,7 @@
 use Illuminate\Contracts\Routing\UrlRoutable;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException;
 use Illuminate\Support\Reflector;
 use Illuminate\Support\Str;
 
@@ -18,12 +19,15 @@ class ImplicitRouteBinding
      * @return void
      *
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     * @throws \Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException
      */
     public static function resolveForRoute($container, $route)
     {
         $parameters = $route->parameters();
 
-        foreach ($route->signatureParameters(UrlRoutable::class) as $parameter) {
+        $route = static::resolveBackedEnumsForRoute($route, $parameters);
+
+        foreach ($route->signatureParameters(['subClass' => UrlRoutable::class]) as $parameter) {
             if (! $parameterName = static::getParameterName($parameter->getName(), $parameters)) {
                 continue;
             }
@@ -60,6 +64,38 @@ public static function resolveForRoute($container, $route)
         }
     }
 
+    /**
+     * Resolve the Backed Enums route bindings for the route.
+     *
+     * @param  \Illuminate\Routing\Route  $route
+     * @param  array  $parameters
+     * @return \Illuminate\Routing\Route
+     *
+     * @throws \Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException
+     */
+    protected static function resolveBackedEnumsForRoute($route, $parameters)
+    {
+        foreach ($route->signatureParameters(['backedEnum' => true]) as $parameter) {
+            if (! $parameterName = static::getParameterName($parameter->getName(), $parameters)) {
+                continue;
+            }
+
+            $parameterValue = $parameters[$parameterName];
+
+            $backedEnumClass = (string) $parameter->getType();
+
+            $backedEnum = $backedEnumClass::tryFrom((string) $parameterValue);
+
+            if (is_null($backedEnum)) {
+                throw new BackedEnumCaseNotFoundException($backedEnumClass, $parameterValue);
+            }
+
+            $route->setParameter($parameterName, $backedEnum);
+        }
+
+        return $route;
+    }
+
     /**
      * Return the parameter name if it exists in the given parameters.
      *

src/Illuminate/Routing/Route.php

@@ -505,12 +505,16 @@ protected function compileParameterNames()
     /**
      * Get the parameters that are listed in the route / controller signature.
      *
-     * @param  string|null  $subClass
+     * @param  array  $conditions
      * @return array
      */
-    public function signatureParameters($subClass = null)
+    public function signatureParameters($conditions = [])
     {
-        return RouteSignatureParameters::fromAction($this->action, $subClass);
+        if (is_string($conditions)) {
+            $conditions = ['subClass' => $conditions];
+        }
+
+        return RouteSignatureParameters::fromAction($this->action, $conditions);
     }
 
     /**

src/Illuminate/Routing/RouteSignatureParameters.php

@@ -13,10 +13,10 @@ class RouteSignatureParameters
      * Extract the route action's signature parameters.
      *
      * @param  array  $action
-     * @param  string|null  $subClass
+     * @param  array  $conditions
      * @return array
      */
-    public static function fromAction(array $action, $subClass = null)
+    public static function fromAction(array $action, $conditions = [])
     {
         $callback = RouteAction::containsSerializedClosure($action)
                         ? unserialize($action['uses'])->getClosure()
@@ -26,9 +26,11 @@ public static function fromAction(array $action, $subClass = null)
                         ? static::fromClassMethodString($callback)
                         : (new ReflectionFunction($callback))->getParameters();
 
-        return is_null($subClass) ? $parameters : array_filter($parameters, function ($p) use ($subClass) {
-            return Reflector::isParameterSubclassOf($p, $subClass);
-        });
+        return match (true) {
+            ! empty($conditions['subClass']) => array_filter($parameters, fn ($p) => Reflector::isParameterSubclassOf($p, $conditions['subClass'])),
+            ! empty($conditions['backedEnum']) => array_filter($parameters, fn ($p) => Reflector::isParameterBackedEnumWithStringBackingType($p)),
+            default => $parameters,
+        };
     }
 
     /**

src/Illuminate/Routing/Router.php

@@ -818,6 +818,7 @@ public static function toResponse($request, $response)
      * @return \Illuminate\Routing\Route
      *
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     * @throws \Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException
      */
     public function substituteBindings($route)
     {
@@ -831,12 +832,13 @@ public function substituteBindings($route)
     }
 
     /**
-     * Substitute the implicit Eloquent model bindings for the route.
+     * Substitute the implicit route bindings for the given route.
      *
      * @param  \Illuminate\Routing\Route  $route
      * @return void
      *
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     * @throws \Illuminate\Routing\Exceptions\BackedEnumCaseNotFoundException
      */
     public function substituteImplicitBindings($route)
     {

src/Illuminate/Support/Reflector.php

@@ -3,6 +3,7 @@
 namespace Illuminate\Support;
 
 use ReflectionClass;
+use ReflectionEnum;
 use ReflectionMethod;
 use ReflectionNamedType;
 use ReflectionUnionType;
@@ -139,4 +140,24 @@ public static function isParameterSubclassOf($parameter, $className)
             && class_exists($paramClassName)
             && (new ReflectionClass($paramClassName))->isSubclassOf($className);
     }
+
+    /**
+     * Determine if the parameter's type is a Backed Enum with a string backing type.
+     *
+     * @param  \ReflectionParameter  $parameter
+     * @return bool
+     */
+    public static function isParameterBackedEnumWithStringBackingType($parameter)
+    {
+        $backedEnumClass = (string) $parameter->getType();
+
+        if (function_exists('enum_exists') && enum_exists($backedEnumClass)) {
+            $reflectionBackedEnum = new ReflectionEnum($backedEnumClass);
+
+            return $reflectionBackedEnum->isBacked()
+                && $reflectionBackedEnum->getBackingType()->getName() == 'string';
+        }
+
+        return false;
+    }
 }

tests/Integration/Routing/Enums.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Illuminate\Tests\Integration\Routing;
+
+enum CategoryBackedEnum: string
+{
+    case People = 'people';
+    case Fruits = 'fruits';
+}

tests/Integration/Routing/ImplicitBackedEnumRouteBindingTest.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Illuminate\Tests\Integration\Routing;
+
+use Illuminate\Support\Facades\Route;
+use Orchestra\Testbench\TestCase;
+
+if (PHP_VERSION_ID >= 80100) {
+    include 'Enums.php';
+}
+
+/**
+ * @requires PHP 8.1
+ */
+class ImplicitBackedEnumRouteBindingTest extends TestCase
+{
+    public function testWithRouteCachingEnabled()
+    {
+        $this->defineCacheRoutes(<<<PHP
+<?php
+
+use Illuminate\Tests\Integration\Routing\CategoryBackedEnum;
+
+Route::get('/categories/{category}', function (CategoryBackedEnum \$category) {
+    return \$category->value;
+})->middleware('web');
+PHP);
+
+        $response = $this->get('/categories/fruits');
+        $response->assertSee('fruits');
+
+        $response = $this->get('/categories/people');
+        $response->assertSee('people');
+
+        $response = $this->get('/categories/cars');
+        $response->assertNotFound(404);
+    }
+
+    public function testWithoutRouteCachingEnabled()
+    {
+        config(['app.key' => str_repeat('a', 32)]);
+
+        Route::post('/categories/{category}', function (CategoryBackedEnum $category) {
+            return $category->value;
+        })->middleware(['web']);
+
+        $response = $this->post('/categories/fruits');
+        $response->assertSee('fruits');
+
+        $response = $this->post('/categories/people');
+        $response->assertSee('people');
+
+        $response = $this->post('/categories/cars');
+        $response->assertNotFound(404);
+    }
+}

tests/Integration/Routing/ImplicitRouteBindingTest.php renamed to tests/Integration/Routing/ImplicitModelRouteBindingTest.php

@@ -10,7 +10,7 @@
 use Orchestra\Testbench\Concerns\InteractsWithPublishedFiles;
 use Orchestra\Testbench\TestCase;
 
-class ImplicitRouteBindingTest extends TestCase
+class ImplicitModelRouteBindingTest extends TestCase
 {
     use InteractsWithPublishedFiles;