Merge pull request #20 from leMaur/feature/max-redirects-guard

Add maxRedirects guard to UrlChecker

Author: leMaur

README.md

@@ -39,6 +39,9 @@ composer require lemaur/php-url-checker
 The class `Lemaur\UrlChecker\UrlChecker` provides a static method `check` where accepts the URL to check as first parameter
 and the user agent string as a second parameter.  
 
+Redirects (`301`, `302`, `307`, `308`) are followed automatically, up to `maxRedirects` hops
+(default `5`). Set `maxRedirects: 0` to return the redirect response without following it.
+
 Here you can see how to use it 👇
 
 ```php
@@ -49,6 +52,7 @@ $response = UrlChecker::check(
     userAgent: 'MyApp/1.0 (UrlChecker)',
     connectTimeout: 5,
     timeout: 10,
+    maxRedirects: 5,
 );
 // \Lemaur\UrlChecker\DataTransferObject\CheckData
 

src/UrlChecker.php

@@ -16,6 +16,13 @@
 
 final class UrlChecker
 {
+    /**
+     * Default maximum number of redirect hops to follow before giving up
+     * and returning the last redirect response as-is. Guards against
+     * redirect loops causing unbounded recursion.
+     */
+    public const DEFAULT_MAX_REDIRECTS = 5;
+
     /**
      * @var array<Response>
      */
@@ -29,10 +36,10 @@ public static function fake(array $queue): void
         self::$queue = $queue;
     }
 
-    public static function check(string $url, ?string $userAgent = null, ?int $connectTimeout = null, ?int $timeout = null): CheckData
+    public static function check(string $url, ?string $userAgent = null, ?int $connectTimeout = null, ?int $timeout = null, ?int $maxRedirects = null): CheckData
     {
         try {
-            $response = (new self())->getResponse($url, $userAgent, $connectTimeout, $timeout);
+            $response = (new self())->getResponse($url, $userAgent, $connectTimeout, $timeout, $maxRedirects ?? self::DEFAULT_MAX_REDIRECTS);
 
             if (!$response instanceof ResponseInterface) {
                 return new CheckData(
@@ -81,7 +88,7 @@ private function getConfig(): array
     /**
      * @throws GuzzleException
      */
-    private function getResponse(string $url, ?string $userAgent = null, ?int $connectTimeout = null, ?int $timeout = null): ?ResponseInterface
+    private function getResponse(string $url, ?string $userAgent = null, ?int $connectTimeout = null, ?int $timeout = null, int $redirectsLeft = self::DEFAULT_MAX_REDIRECTS): ?ResponseInterface
     {
         $response = null;
 
@@ -111,8 +118,14 @@ private function getResponse(string $url, ?string $userAgent = null, ?int $conne
             }
         }
 
-        if (in_array($response?->getStatusCode(), [301, 302, 307, 308], strict: true)) {
-            return $this->getResponse($response->getHeader('Location')[0] ?? '');
+        if ($redirectsLeft > 0 && in_array($response?->getStatusCode(), [301, 302, 307, 308], strict: true)) {
+            return $this->getResponse(
+                $response->getHeader('Location')[0] ?? '',
+                $userAgent,
+                $connectTimeout,
+                $timeout,
+                $redirectsLeft - 1,
+            );
         }
 
         return $response;

tests/UnitTest.php

@@ -25,3 +25,24 @@
     'status code 502' => [502, 'Bad Gateway'],
     'status code 503' => [503, 'Service Unavailable'],
 ]);
+
+it('stops following redirects after the maximum number of hops', function (int $statusCode): void {
+    // In fake mode every hop re-serves the same queued response, so a redirect
+    // status code recurses indefinitely unless the maxRedirects guard stops it.
+    UrlChecker::fake([new Response($statusCode, ['Location' => 'https://foo.bar/loop'])]);
+
+    expect(UrlChecker::check('https://foo.bar'))
+        ->statusCode->toBe($statusCode);
+})->with([
+    'moved permanently 301' => [301],
+    'found 302' => [302],
+    'temporary redirect 307' => [307],
+    'permanent redirect 308' => [308],
+]);
+
+it('does not follow redirects when maxRedirects is zero', function (): void {
+    UrlChecker::fake([new Response(301, ['Location' => 'https://foo.bar/elsewhere'])]);
+
+    expect(UrlChecker::check('https://foo.bar', maxRedirects: 0))
+        ->statusCode->toBe(301);
+});