Adds optional Wheres attribute on class and method level

README.md

@@ -256,6 +256,50 @@ Route::get('my-get-route', [MyController::class, 'myGetMethod'])->domain('my-sub
 Route::post('my-post-route', [MyController::class, 'myPostMethod'])->domain('my-subdomain.localhost');
 ```
 
+
+### Specifying wheres
+
+You can use the `Where` annotation on a class or method to constrain the format of your route parameters.
+
+
+```php
+use Spatie\RouteAttributes\Attributes\Get;
+use Spatie\RouteAttributes\Attributes\Post;
+use Spatie\RouteAttributes\Attributes\Where;
+use Spatie\RouteAttributes\Attributes\WhereAlphaNumeric;
+
+#[Where('my-where', '[0-9]+')]
+class MyController
+{
+    #[Get('my-get-route/{my-where}')]
+    public function myGetMethod()
+    {
+    }
+
+    #[Post('my-post-route/{my-where}/{my-alpha-numeric}')]
+    #[WhereAlphaNumeric('my-alpha-numeric')]
+    public function myPostMethod()
+    {
+    }
+}
+```
+
+These annotations will automatically register these routes:
+
+```php
+Route::get('my-get-route/{my-where}', [MyController::class, 'myGetMethod'])->where(['my-where' => '[0-9]+']);
+Route::post('my-post-route/{my-where}/{my-alpha-numeric}', [MyController::class, 'myPostMethod'])->where(['my-where' => '[0-9]+', 'my-alpha-numeric' => '[a-zA-Z0-9]+']);
+```
+
+For convenience, some commonly used regular expression patterns have helper attributes that allow you to quickly add pattern constraints to your routes.
+
+```php 
+#[WhereAlpha('alpha')]
+#[WhereAlphaNumeric('alpha-numeric')]
+#[WhereNumber('number')]
+#[WhereUuid('uuid')]
+```
+
 ## Testing
 
 ``` bash

src/Attributes/Where.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Spatie\RouteAttributes\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class Where implements WhereAttribute
+{
+    public function __construct(
+        public string $param,
+        public string $constraint,
+    ) {
+    }
+}

src/Attributes/WhereAlpha.php

@@ -0,0 +1,16 @@
+<?php
+
+
+namespace Spatie\RouteAttributes\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class WhereAlpha extends Where
+{
+    public function __construct(string $param)
+    {
+        $this->param = $param;
+        $this->constraint = '[a-zA-Z]+';
+    }
+}

src/Attributes/WhereAlphaNumeric.php

@@ -0,0 +1,16 @@
+<?php
+
+
+namespace Spatie\RouteAttributes\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class WhereAlphaNumeric extends Where
+{
+    public function __construct(string $param)
+    {
+        $this->param = $param;
+        $this->constraint = '[a-zA-Z0-9]+';
+    }
+}

src/Attributes/WhereAttribute.php

@@ -0,0 +1,10 @@
+<?php
+
+
+namespace Spatie\RouteAttributes\Attributes;
+
+
+interface WhereAttribute
+{
+
+}

src/Attributes/WhereNumber.php

@@ -0,0 +1,16 @@
+<?php
+
+
+namespace Spatie\RouteAttributes\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class WhereNumber extends Where
+{
+    public function __construct(string $param)
+    {
+        $this->param = $param;
+        $this->constraint = '[0-9]+';
+    }
+}

src/Attributes/WhereUuid.php

@@ -0,0 +1,16 @@
+<?php
+
+
+namespace Spatie\RouteAttributes\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class WhereUuid extends Where
+{
+    public function __construct(string $param)
+    {
+        $this->param = $param;
+        $this->constraint = '[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}';
+    }
+}

src/ClassRouteAttributes.php

@@ -7,6 +7,7 @@
 use Spatie\RouteAttributes\Attributes\Middleware;
 use Spatie\RouteAttributes\Attributes\Prefix;
 use Spatie\RouteAttributes\Attributes\RouteAttribute;
+use Spatie\RouteAttributes\Attributes\Where;
 
 class ClassRouteAttributes
 {
@@ -56,6 +57,21 @@ public function middleware(): array
         return $attribute->middleware;
     }
 
+    /**
+     * @psalm-suppress NoInterfaceProperties
+     */
+    public function wheres(): array
+    {
+        $wheres = [];
+        /** @var ReflectionClass[] $attributes */
+        $attributes = $this->class->getAttributes(Where::class);
+        foreach ($attributes as $attribute) {
+            $attributeClass = $attribute->newInstance();
+            $wheres[$attributeClass->param] = $attributeClass->constraint;
+        }
+        return $wheres;
+    }
+
     protected function getAttribute(string $attributeClass): ?RouteAttribute
     {
         $attributes = $this->class->getAttributes($attributeClass);

src/RouteRegistrar.php

@@ -9,6 +9,8 @@
 use ReflectionClass;
 use Spatie\RouteAttributes\Attributes\Route;
 use Spatie\RouteAttributes\Attributes\RouteAttribute;
+use Spatie\RouteAttributes\Attributes\Where;
+use Spatie\RouteAttributes\Attributes\WhereAttribute;
 use SplFileInfo;
 use Symfony\Component\Finder\Finder;
 use Throwable;
@@ -113,6 +115,7 @@ protected function registerRoutes(ReflectionClass $class, ClassRouteAttributes $
     {
         foreach ($class->getMethods() as $method) {
             $attributes = $method->getAttributes(RouteAttribute::class, ReflectionAttribute::IS_INSTANCEOF);
+            $wheresAttributes = $method->getAttributes(WhereAttribute::class, ReflectionAttribute::IS_INSTANCEOF);
 
             foreach ($attributes as $attribute) {
                 try {
@@ -140,6 +143,18 @@ protected function registerRoutes(ReflectionClass $class, ClassRouteAttributes $
                     $route->domain($domain);
                 }
 
+                $wheres = $classRouteAttributes->wheres();
+                foreach ($wheresAttributes as $wheresAttribute) {
+                    /** @var Where $wheresAttributeClass */
+                    $wheresAttributeClass = $wheresAttribute->newInstance();
+
+                    // This also overrides class wheres if the same param is used
+                    $wheres[$wheresAttributeClass->param] = $wheresAttributeClass->constraint;
+                }
+                if (!empty($wheres)) {
+                    $route->setWheres($wheres);
+                }
+
                 $classMiddleware = $classRouteAttributes->middleware();
                 $methodMiddleware = $attributeClass->middleware;
                 $route->middleware([...$this->middleware, ...$classMiddleware, ...$methodMiddleware]);

tests/AttributeTests/WhereAttributeTest.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Spatie\RouteAttributes\Tests\AttributeTests;
+
+use Spatie\RouteAttributes\Tests\TestCase;
+use Spatie\RouteAttributes\Tests\TestClasses\Controllers\MiddlewareTestController;
+use Spatie\RouteAttributes\Tests\TestClasses\Controllers\WhereTestController;
+use Spatie\RouteAttributes\Tests\TestClasses\Middleware\OtherTestMiddleware;
+use Spatie\RouteAttributes\Tests\TestClasses\Middleware\TestMiddleware;
+
+class WhereAttributeTest extends TestCase
+{
+    /** @test */
+    public function it_can_apply_where_on_each_method_of_a_controller()
+    {
+        $this->routeRegistrar->registerClass(WhereTestController::class);
+
+        $this
+            ->assertRegisteredRoutesCount(4)
+            ->assertRouteRegistered(
+                WhereTestController::class,
+                controllerMethod: 'myGetMethod',
+                uri: 'my-get-method/{param}',
+                wheres: ['param' => '[0-9]+']
+            )
+            ->assertRouteRegistered(
+                WhereTestController::class,
+                controllerMethod: 'myPostMethod',
+                httpMethods: 'post',
+                uri: 'my-post-method/{param}/{param2}',
+                wheres: ['param' => '[0-9]+', 'param2' => '[a-zA-Z]+']
+            );
+    }
+
+    /** @test */
+    public function it_can_apply_where_on_a_method()
+    {
+        $this->routeRegistrar->registerClass(WhereTestController::class);
+
+        $this
+            ->assertRegisteredRoutesCount(4)
+            ->assertRouteRegistered(
+                WhereTestController::class,
+                controllerMethod: 'myWhereMethod',
+                uri: 'my-where-method/{param}/{param2}/{param3}',
+                wheres: ['param' => '[0-9]+', 'param2' => '[a-zA-Z]+', 'param3' => 'test']
+            );
+    }
+
+    /** @test */
+    public function it_can_apply_shorthand_where()
+    {
+        $this->routeRegistrar->registerClass(WhereTestController::class);
+
+        $this
+            ->assertRegisteredRoutesCount(4)
+            ->assertRouteRegistered(
+                WhereTestController::class,
+                controllerMethod: 'myShorthands',
+                uri: 'my-shorthands',
+                wheres: [
+                    'param' => '[0-9]+',
+                    'alpha' => '[a-zA-Z]+',
+                    'alpha-numeric' => '[a-zA-Z0-9]+',
+                    'number' => '[0-9]+',
+                    'uuid' => '[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}'
+                ]
+            );
+    }
+}

tests/TestCase.php

@@ -55,13 +55,14 @@ public function assertRouteRegistered(
         string | array $middleware = [],
         ?string $name = null,
         ?string $domain = null,
+        ?array $wheres = []
     ): self {
         if (! is_array($middleware)) {
             $middleware = Arr::wrap($middleware);
         }
 
         $routeRegistered = collect($this->getRouteCollection()->getRoutes())
-            ->contains(function (Route $route) use ($name, $middleware, $controllerMethod, $controller, $uri, $httpMethods, $domain) {
+            ->contains(function (Route $route) use ($name, $middleware, $controllerMethod, $controller, $uri, $httpMethods, $domain, $wheres) {
                 foreach (Arr::wrap($httpMethods) as $httpMethod) {
                     if (! in_array(strtoupper($httpMethod), $route->methods)) {
                         return false;
@@ -92,6 +93,10 @@ public function assertRouteRegistered(
                     return false;
                 }
 
+                if($wheres !== $route->wheres){
+                    return false;
+                }
+
                 return true;
             });
 

tests/TestClasses/Controllers/WhereTestController.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Spatie\RouteAttributes\Tests\TestClasses\Controllers;
+
+use Spatie\RouteAttributes\Attributes\Get;
+use Spatie\RouteAttributes\Attributes\Post;
+use Spatie\RouteAttributes\Attributes\Prefix;
+use Spatie\RouteAttributes\Attributes\Where;
+use Spatie\RouteAttributes\Attributes\WhereAlpha;
+use Spatie\RouteAttributes\Attributes\WhereAlphaNumeric;
+use Spatie\RouteAttributes\Attributes\WhereNumber;
+use Spatie\RouteAttributes\Attributes\WhereUuid;
+
+#[Where('param','[0-9]+')]
+class WhereTestController
+{
+    #[Get('my-get-method/{param}')]
+    public function myGetMethod()
+    {
+    }
+
+    #[Post('my-post-method/{param}/{param2}')]
+    #[Where('param2','[a-zA-Z]+')]
+    public function myPostMethod()
+    {
+    }
+
+    #[Get('my-where-method/{param}/{param2}/{param3}')]
+    #[Where('param2','[a-zA-Z]+')]
+    #[Where('param3','test')]
+    public function myWhereMethod()
+    {
+
+    }
+
+    #[Get('my-shorthands')]
+    #[WhereAlpha('alpha')]
+    #[WhereAlphaNumeric('alpha-numeric')]
+    #[WhereNumber('number')]
+    #[WhereUuid('uuid')]
+    public function myShorthands()
+    {
+    }
+}