feat: Add #[UsePolicy] attribute for declarative policy binding

src/auth/src/Access/Gate.php

@@ -13,6 +13,7 @@
 use Hypervel\Auth\Access\Events\GateEvaluated;
 use Hypervel\Auth\Contracts\Authenticatable;
 use Hypervel\Auth\Contracts\Gate as GateContract;
+use Hypervel\Database\Eloquent\Attributes\UsePolicy;
 use InvalidArgumentException;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use ReflectionClass;
@@ -504,13 +505,38 @@ public function getPolicyFor(object|string $class)
             return $this->resolvePolicy($this->policies[$class]);
         }
 
+        $policy = $this->getPolicyFromAttribute($class);
+
+        if (! is_null($policy)) {
+            return $this->resolvePolicy($policy);
+        }
+
         foreach ($this->policies as $expected => $policy) {
             if (is_subclass_of($class, $expected)) {
                 return $this->resolvePolicy($policy);
             }
         }
     }
 
+    /**
+     * Get the policy class from the UsePolicy attribute.
+     *
+     * @param class-string $class
+     * @return null|class-string
+     */
+    protected function getPolicyFromAttribute(string $class): ?string
+    {
+        if (! class_exists($class)) {
+            return null;
+        }
+
+        $attributes = (new ReflectionClass($class))->getAttributes(UsePolicy::class);
+
+        return $attributes !== []
+            ? $attributes[0]->newInstance()->class
+            : null;
+    }
+
     /**
      * Build a policy class instance of the given type.
      *

src/core/src/Database/Eloquent/Attributes/UsePolicy.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Database\Eloquent\Attributes;
+
+use Attribute;
+
+/**
+ * Declare the policy class for a model using an attribute.
+ *
+ * When placed on a model class, the Gate will use the specified policy
+ * class for authorization checks. This takes precedence over policy
+ * name guessing but not over explicitly registered policies.
+ *
+ * @example
+ * ```php
+ * #[UsePolicy(PostPolicy::class)]
+ * class Post extends Model {}
+ * ```
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+class UsePolicy
+{
+    /**
+     * Create a new attribute instance.
+     *
+     * @param class-string $class
+     */
+    public function __construct(
+        public string $class
+    ) {
+    }
+}

tests/Auth/Access/GateTest.php

@@ -33,6 +33,10 @@
 use Hypervel\Tests\Auth\Stub\AccessGateTestResource;
 use Hypervel\Tests\Auth\Stub\AccessGateTestStaticClass;
 use Hypervel\Tests\Auth\Stub\AccessGateTestSubDummy;
+use Hypervel\Tests\Auth\Stub\DummyWithoutUsePolicy;
+use Hypervel\Tests\Auth\Stub\DummyWithUsePolicy;
+use Hypervel\Tests\Auth\Stub\DummyWithUsePolicyPolicy;
+use Hypervel\Tests\Auth\Stub\SubDummyWithUsePolicy;
 use Hypervel\Tests\TestCase;
 use InvalidArgumentException;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -1011,6 +1015,61 @@ public function testClassesCanBeDefinedAsCallbacksUsingAtNotationForGuests()
         $this->assertFalse($gate->check('absent_invokable'));
     }
 
+    public function testPolicyCanBeResolvedFromUsePolicyAttribute(): void
+    {
+        $gate = $this->getBasicGate();
+
+        $this->assertInstanceOf(
+            DummyWithUsePolicyPolicy::class,
+            $gate->getPolicyFor(DummyWithUsePolicy::class)
+        );
+    }
+
+    public function testPolicyFromUsePolicyAttributeWorksWithObjectInstance(): void
+    {
+        $gate = $this->getBasicGate();
+
+        $this->assertInstanceOf(
+            DummyWithUsePolicyPolicy::class,
+            $gate->getPolicyFor(new DummyWithUsePolicy())
+        );
+    }
+
+    public function testExplicitPolicyTakesPrecedenceOverUsePolicyAttribute(): void
+    {
+        $gate = $this->getBasicGate();
+
+        // Register an explicit policy that should take precedence
+        $gate->policy(DummyWithUsePolicy::class, AccessGateTestPolicy::class);
+
+        $this->assertInstanceOf(
+            AccessGateTestPolicy::class,
+            $gate->getPolicyFor(DummyWithUsePolicy::class)
+        );
+    }
+
+    public function testUsePolicyAttributeTakesPrecedenceOverSubclassFallback(): void
+    {
+        $gate = $this->getBasicGate();
+
+        // Register a policy for the parent class
+        $gate->policy(DummyWithUsePolicy::class, AccessGateTestPolicy::class);
+
+        // SubDummyWithUsePolicy extends DummyWithUsePolicy but has its own #[UsePolicy] attribute
+        // The attribute should take precedence over the subclass fallback
+        $this->assertInstanceOf(
+            DummyWithUsePolicyPolicy::class,
+            $gate->getPolicyFor(SubDummyWithUsePolicy::class)
+        );
+    }
+
+    public function testGetPolicyForReturnsNullForClassWithoutUsePolicyAttribute(): void
+    {
+        $gate = $this->getBasicGate();
+
+        $this->assertNull($gate->getPolicyFor(DummyWithoutUsePolicy::class));
+    }
+
     public function testCanSetDenialResponseInConstructor()
     {
         $gate = $this->getGuestGate();

tests/Auth/Stub/DummyWithUsePolicy.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Auth\Stub;
+
+use Hypervel\Database\Eloquent\Attributes\UsePolicy;
+
+#[UsePolicy(DummyWithUsePolicyPolicy::class)]
+class DummyWithUsePolicy
+{
+}

tests/Auth/Stub/DummyWithUsePolicyPolicy.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Auth\Stub;
+
+use Hypervel\Auth\Access\HandlesAuthorization;
+
+class DummyWithUsePolicyPolicy
+{
+    use HandlesAuthorization;
+
+    public function view($user, DummyWithUsePolicy $dummy): bool
+    {
+        return true;
+    }
+
+    public function update($user, DummyWithUsePolicy $dummy): bool
+    {
+        return true;
+    }
+}

tests/Auth/Stub/DummyWithoutUsePolicy.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Auth\Stub;
+
+class DummyWithoutUsePolicy
+{
+}

tests/Auth/Stub/SubDummyWithUsePolicy.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Auth\Stub;
+
+use Hypervel\Database\Eloquent\Attributes\UsePolicy;
+
+/**
+ * Extends DummyWithUsePolicy but has its own UsePolicy attribute.
+ * Used to test that the attribute takes precedence over subclass fallback.
+ */
+#[UsePolicy(DummyWithUsePolicyPolicy::class)]
+class SubDummyWithUsePolicy extends DummyWithUsePolicy
+{
+}