feature symfony#38354 [RateLimiter] add Limit::ensureAccepted() which throws RateLimitExceededException if not accepted (kbond)

This PR was merged into the 5.2-dev branch.

Discussion
----------

[RateLimiter] add Limit::ensureAccepted() which throws RateLimitExceededException if not accepted

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Ref symfony#38241 (comment)
| License       | MIT
| Doc PR        | todo

Example:

```php
try {
    $limit = $limiter->consume()->ensureAccepted();
} catch (RateLimitExceededException $e) {
    $limit = $e->getLimit();
}
```

Commits
-------

a7ecd0e [RateLimiter] add Limit::ensureAccepted() and RateLimitExceededException

Author: fabpot

src/Symfony/Component/RateLimiter/Exception/RateLimitExceededException.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\RateLimiter\Exception;
+
+use Symfony\Component\RateLimiter\Limit;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental in 5.2
+ */
+class RateLimitExceededException extends \RuntimeException
+{
+    private $limit;
+
+    public function __construct(Limit $limit, $code = 0, \Throwable $previous = null)
+    {
+        parent::__construct('Rate Limit Exceeded', $code, $previous);
+
+        $this->limit = $limit;
+    }
+
+    public function getLimit(): Limit
+    {
+        return $this->limit;
+    }
+
+    public function getRetryAfter(): \DateTimeImmutable
+    {
+        return $this->limit->getRetryAfter();
+    }
+
+    public function getRemainingTokens(): int
+    {
+        return $this->limit->getRemainingTokens();
+    }
+}

src/Symfony/Component/RateLimiter/Limit.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\RateLimiter;
 
+use Symfony\Component\RateLimiter\Exception\RateLimitExceededException;
+
 /**
  * @author Valentin Silvestre <[email protected]>
  *
@@ -34,6 +36,18 @@ public function isAccepted(): bool
         return $this->accepted;
     }
 
+    /**
+     * @throws RateLimitExceededException if not accepted
+     */
+    public function ensureAccepted(): self
+    {
+        if (!$this->accepted) {
+            throw new RateLimitExceededException($this);
+        }
+
+        return $this;
+    }
+
     public function getRetryAfter(): \DateTimeImmutable
     {
         return $this->retryAfter;

src/Symfony/Component/RateLimiter/Tests/LimitTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\RateLimiter\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\RateLimiter\Exception\RateLimitExceededException;
+use Symfony\Component\RateLimiter\Limit;
+
+class LimitTest extends TestCase
+{
+    public function testEnsureAcceptedDoesNotThrowExceptionIfAccepted()
+    {
+        $limit = new Limit(10, new \DateTimeImmutable(), true);
+
+        $this->assertSame($limit, $limit->ensureAccepted());
+    }
+
+    public function testEnsureAcceptedThrowsRateLimitExceptionIfNotAccepted()
+    {
+        $limit = new Limit(10, $retryAfter = new \DateTimeImmutable(), false);
+
+        try {
+            $limit->ensureAccepted();
+        } catch (RateLimitExceededException $exception) {
+            $this->assertSame($limit, $exception->getLimit());
+            $this->assertSame(10, $exception->getRemainingTokens());
+            $this->assertSame($retryAfter, $exception->getRetryAfter());
+
+            return;
+        }
+
+        $this->fail('RateLimitExceededException not thrown.');
+    }
+}