From b7d12c8093025482d6aad2031b256e4f1d4659ea Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:04:14 +0100
Subject: [PATCH 01/11] refactor(exceptions): add base exception class

- Add WebUtilityException abstract base class
- All package exceptions now extend WebUtilityException
- Enables catching all package exceptions in one go
- Add tests for exception hierarchy
---
 src/Exceptions/ContentNotFoundException.php   |  4 +-
 src/Exceptions/EmptyUrlException.php          |  4 +-
 .../FiveHundredResponseException.php          |  4 +-
 .../FourHundredResponseException.php          |  4 +-
 src/Exceptions/InvalidUrlException.php        |  4 +-
 .../MaxRedirectsReachedException.php          |  4 +-
 src/Exceptions/NetworkErrorException.php      |  4 +-
 .../UnsupportedCheckMethodException.php       |  4 +-
 src/Exceptions/WebUtilityException.php        |  9 ++++
 src/ResponseUtility.php                       |  3 +-
 tests/Exceptions/WebUtilityExceptionTest.php  | 48 +++++++++++++++++++
 11 files changed, 66 insertions(+), 26 deletions(-)
 create mode 100644 src/Exceptions/WebUtilityException.php
 create mode 100644 tests/Exceptions/WebUtilityExceptionTest.php

diff --git a/src/Exceptions/ContentNotFoundException.php b/src/Exceptions/ContentNotFoundException.php
index eb90113..c05fcd2 100644
--- a/src/Exceptions/ContentNotFoundException.php
+++ b/src/Exceptions/ContentNotFoundException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class ContentNotFoundException extends Exception
+class ContentNotFoundException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/EmptyUrlException.php b/src/Exceptions/EmptyUrlException.php
index efaa034..aceaede 100644
--- a/src/Exceptions/EmptyUrlException.php
+++ b/src/Exceptions/EmptyUrlException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class EmptyUrlException extends Exception
+class EmptyUrlException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/FiveHundredResponseException.php b/src/Exceptions/FiveHundredResponseException.php
index 4f958f8..bfb3c79 100644
--- a/src/Exceptions/FiveHundredResponseException.php
+++ b/src/Exceptions/FiveHundredResponseException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class FiveHundredResponseException extends Exception
+class FiveHundredResponseException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/FourHundredResponseException.php b/src/Exceptions/FourHundredResponseException.php
index d2d3688..0de9b4c 100644
--- a/src/Exceptions/FourHundredResponseException.php
+++ b/src/Exceptions/FourHundredResponseException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class FourHundredResponseException extends Exception
+class FourHundredResponseException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/InvalidUrlException.php b/src/Exceptions/InvalidUrlException.php
index fe6f736..7e49e0c 100644
--- a/src/Exceptions/InvalidUrlException.php
+++ b/src/Exceptions/InvalidUrlException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class InvalidUrlException extends Exception
+class InvalidUrlException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/MaxRedirectsReachedException.php b/src/Exceptions/MaxRedirectsReachedException.php
index 7ae975e..78a005e 100644
--- a/src/Exceptions/MaxRedirectsReachedException.php
+++ b/src/Exceptions/MaxRedirectsReachedException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class MaxRedirectsReachedException extends Exception
+class MaxRedirectsReachedException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/NetworkErrorException.php b/src/Exceptions/NetworkErrorException.php
index f08ddc7..d8d5a20 100644
--- a/src/Exceptions/NetworkErrorException.php
+++ b/src/Exceptions/NetworkErrorException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class NetworkErrorException extends Exception
+class NetworkErrorException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/UnsupportedCheckMethodException.php b/src/Exceptions/UnsupportedCheckMethodException.php
index 810da47..4394285 100644
--- a/src/Exceptions/UnsupportedCheckMethodException.php
+++ b/src/Exceptions/UnsupportedCheckMethodException.php
@@ -2,8 +2,6 @@
 
 namespace Myerscode\Utilities\Web\Exceptions;
 
-use Exception;
-
-class UnsupportedCheckMethodException extends Exception
+class UnsupportedCheckMethodException extends WebUtilityException
 {
 }
diff --git a/src/Exceptions/WebUtilityException.php b/src/Exceptions/WebUtilityException.php
new file mode 100644
index 0000000..002e918
--- /dev/null
+++ b/src/Exceptions/WebUtilityException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Myerscode\Utilities\Web\Exceptions;
+
+use RuntimeException;
+
+abstract class WebUtilityException extends RuntimeException
+{
+}
diff --git a/src/ResponseUtility.php b/src/ResponseUtility.php
index 16cbdeb..4d48529 100644
--- a/src/ResponseUtility.php
+++ b/src/ResponseUtility.php
@@ -2,7 +2,6 @@
 
 namespace Myerscode\Utilities\Web;
 
-use Exception;
 use Curl\Curl;
 use League\Uri\Http;
 use Myerscode\Utilities\Web\Data\ResponseFrom;
@@ -151,7 +150,7 @@ public function fromHttpClient(): Response
             $statusCode = 400;
         } catch (ServerExceptionInterface) {
             $statusCode = 500;
-        } catch (Exception) {
+        } catch (\Exception) {
             throw new InvalidUrlException();
         }
 
diff --git a/tests/Exceptions/WebUtilityExceptionTest.php b/tests/Exceptions/WebUtilityExceptionTest.php
new file mode 100644
index 0000000..89e13ff
--- /dev/null
+++ b/tests/Exceptions/WebUtilityExceptionTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Exceptions;
+
+use Myerscode\Utilities\Web\Exceptions\ContentNotFoundException;
+use Myerscode\Utilities\Web\Exceptions\EmptyUrlException;
+use Myerscode\Utilities\Web\Exceptions\FiveHundredResponseException;
+use Myerscode\Utilities\Web\Exceptions\FourHundredResponseException;
+use Myerscode\Utilities\Web\Exceptions\InvalidUrlException;
+use Myerscode\Utilities\Web\Exceptions\MaxRedirectsReachedException;
+use Myerscode\Utilities\Web\Exceptions\NetworkErrorException;
+use Myerscode\Utilities\Web\Exceptions\UnsupportedCheckMethodException;
+use Myerscode\Utilities\Web\Exceptions\WebUtilityException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use Iterator;
+use RuntimeException;
+
+final class WebUtilityExceptionTest extends TestCase
+{
+    public static function exceptionProvider(): Iterator
+    {
+        yield 'ContentNotFoundException' => [new ContentNotFoundException()];
+        yield 'EmptyUrlException' => [new EmptyUrlException()];
+        yield 'FiveHundredResponseException' => [new FiveHundredResponseException()];
+        yield 'FourHundredResponseException' => [new FourHundredResponseException()];
+        yield 'InvalidUrlException' => [new InvalidUrlException()];
+        yield 'MaxRedirectsReachedException' => [new MaxRedirectsReachedException()];
+        yield 'NetworkErrorException' => [new NetworkErrorException()];
+        yield 'UnsupportedCheckMethodException' => [new UnsupportedCheckMethodException()];
+    }
+
+    #[DataProvider('exceptionProvider')]
+    public function testAllExceptionsExtendWebUtilityException(WebUtilityException $exception): void
+    {
+        $this->assertInstanceOf(WebUtilityException::class, $exception);
+        $this->assertInstanceOf(RuntimeException::class, $exception);
+    }
+
+    public function testCanCatchAllPackageExceptions(): void
+    {
+        $this->expectException(WebUtilityException::class);
+
+        throw new ContentNotFoundException('test');
+    }
+}

From ccf985954bf4c1a9c350620c340779b02e810d02 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:04:48 +0100
Subject: [PATCH 02/11] fix(uri): anchor scheme detection regex

- Anchor regex to start of string with ^
- Prevents false matches on URLs containing schemes
- Applied to both UriUtility and ResponseUtility
---
 src/ResponseUtility.php | 6 ++----
 src/UriUtility.php      | 6 ++----
 2 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/ResponseUtility.php b/src/ResponseUtility.php
index 4d48529..1f1f8fc 100644
--- a/src/ResponseUtility.php
+++ b/src/ResponseUtility.php
@@ -229,10 +229,8 @@ private function setUrl(string|UriUtility $uri): void
     {
         $trimmed = trim($uri instanceof UriUtility ? $uri->value() : $uri);
 
-        // check if a scheme is present, if not we need to give it one
-        preg_match_all('#(https:\/\/)|(http:\/\/)#', $trimmed, $matches, PREG_SET_ORDER, 0);
-
-        if ($matches === []) {
+        // check if a scheme is present at the start, if not we need to give it one
+        if (!preg_match('#^https?://#i', $trimmed)) {
             $trimmed = self::DEFAULT_SCHEME . $trimmed;
         }
 
diff --git a/src/UriUtility.php b/src/UriUtility.php
index 558cfaa..9647465 100644
--- a/src/UriUtility.php
+++ b/src/UriUtility.php
@@ -203,10 +203,8 @@ private function setUrl(string|Http $uri): void
     {
         $trimmed = trim($uri);
 
-        // check if a scheme is present, if not we need to give it one
-        preg_match_all('/(https:\/\/)|(http:\/\/)/', $trimmed, $matches, PREG_SET_ORDER, 0);
-
-        if ($matches === []) {
+        // check if a scheme is present at the start, if not we need to give it one
+        if (!preg_match('#^https?://#i', $trimmed)) {
             $trimmed = 'https://' . $trimmed;
         }
 

From e323d665ef4b2c734debb6f589e3abde5ff85388 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:05:13 +0100
Subject: [PATCH 03/11] fix(ping): fix IPv6 detection and add features

- Fix IPv6 detection running after escapeshellarg
- Consolidate OS detection into detectOs() method
- Add setTimeout() and setTtl() fluent setters
- Add isAlive() and latency() convenience methods
- Add tests for new features
---
 src/PingUtility.php              | 90 ++++++++++++++++++++++++--------
 tests/PingUtility/ConfigTest.php | 72 +++++++++++++++++++++++++
 2 files changed, 139 insertions(+), 23 deletions(-)
 create mode 100644 tests/PingUtility/ConfigTest.php

diff --git a/src/PingUtility.php b/src/PingUtility.php
index d68b7a2..9ae813b 100644
--- a/src/PingUtility.php
+++ b/src/PingUtility.php
@@ -27,7 +27,23 @@ public function __construct(string $url)
     }
 
     /**
-     * Ping a urls host
+     * Check if the host is alive
+     */
+    public function isAlive(): bool
+    {
+        return $this->ping()['alive'];
+    }
+
+    /**
+     * Get the latency in milliseconds, or null if unreachable
+     */
+    public function latency(): ?float
+    {
+        return $this->ping()['latency'];
+    }
+
+    /**
+     * Ping a urls host and return whether it's alive and the latency
      */
     public function ping(): array
     {
@@ -36,20 +52,15 @@ public function ping(): array
             'latency' => null,
         ];
 
-        $ttl = $this->ttl;
-        $timeout = $this->timeout;
-        $host = escapeshellarg($this->uriUtility->host());
-
+        $host = $this->uriUtility->host();
         $pingCmd = $this->getPingCommand($host);
+        $escapedHost = escapeshellarg($host);
 
-        // Construct the ping command
-        if (str_starts_with(strtoupper(PHP_OS), 'WIN')) {
-            $exec_string = sprintf('%s -n 1 -i %d -w %d %s', $pingCmd, $ttl, $timeout * 1000, $host);
-        } elseif (strtoupper(PHP_OS) === 'DARWIN') {
-            $exec_string = sprintf('%s -c 1 -t %d %s', $pingCmd, $ttl, $host);
-        } else {
-            $exec_string = sprintf('%s -c 1 -t %d -w %d %s', $pingCmd, $ttl, $timeout, $host);
-        }
+        $exec_string = match ($this->detectOs()) {
+            'WIN' => sprintf('%s -n 1 -i %d -w %d %s', $pingCmd, $this->ttl, $this->timeout * 1000, $escapedHost),
+            'DARWIN' => sprintf('%s -c 1 -t %d %s', $pingCmd, $this->ttl, $escapedHost),
+            default => sprintf('%s -c 1 -t %d -w %d %s', $pingCmd, $this->ttl, $this->timeout, $escapedHost),
+        };
 
         $output = [];
 
@@ -60,9 +71,9 @@ public function ping(): array
         }
 
         foreach ($output as $line) {
-            if (preg_match('/time[=<]?\\s?(?<time>\\d+(?:\\.\\d+)?)\\s?ms/', $line, $latencyMatches)) {
+            if (preg_match('/time[=<]?\s?(?<time>\d+(?:\.\d+)?)\s?ms/', $line, $latencyMatches)) {
                 $ping['alive'] = true;
-                $ping['latency'] = round((float)$latencyMatches['time']);
+                $ping['latency'] = round((float) $latencyMatches['time']);
                 break;
             }
         }
@@ -70,11 +81,49 @@ public function ping(): array
         return $ping;
     }
 
+    /**
+     * Set the timeout in seconds
+     */
+    public function setTimeout(int $timeout): self
+    {
+        $this->timeout = $timeout;
+
+        return $this;
+    }
+
+    /**
+     * Set the TTL (time to live)
+     */
+    public function setTtl(int $ttl): self
+    {
+        $this->ttl = $ttl;
+
+        return $this;
+    }
+
     public function url(): string
     {
         return $this->uriUtility->value();
     }
 
+    /**
+     * Detect the operating system family
+     */
+    private function detectOs(): string
+    {
+        $os = strtoupper(PHP_OS);
+
+        if (str_starts_with($os, 'WIN')) {
+            return 'WIN';
+        }
+
+        if ($os === 'DARWIN') {
+            return 'DARWIN';
+        }
+
+        return 'LINUX';
+    }
+
     /**
      * Determines the correct ping command and checks if it's available.
      *
@@ -83,16 +132,11 @@ public function url(): string
     private function getPingCommand(string $host): string
     {
         $isIPv6 = filter_var($host, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6);
+        $os = $this->detectOs();
 
-        if (str_starts_with(strtoupper(PHP_OS), 'WIN')) {
-            $pingCmd = 'ping';
-        } elseif (strtoupper(PHP_OS) === 'DARWIN') {
-            $pingCmd = 'ping';
-        } else {
-            $pingCmd = $isIPv6 ? 'ping6' : 'ping';
-        }
+        $pingCmd = ($os !== 'LINUX' || !$isIPv6) ? 'ping' : 'ping6';
 
-        $checkCmd = (str_starts_with(strtoupper(PHP_OS), 'WIN')) ? 'where ' : 'which ';
+        $checkCmd = ($os === 'WIN') ? 'where ' : 'which ';
 
         exec($checkCmd . $pingCmd . ' 2>&1', $output, $returnCode);
 
diff --git a/tests/PingUtility/ConfigTest.php b/tests/PingUtility/ConfigTest.php
new file mode 100644
index 0000000..7ee0066
--- /dev/null
+++ b/tests/PingUtility/ConfigTest.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\PingUtility;
+
+use Tests\BasePingSuite;
+
+final class ConfigTest extends BasePingSuite
+{
+    public function testIsAliveForValidHost(): void
+    {
+        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
+            $this->markTestSkipped('Skipping test on Windows');
+        }
+
+        $this->assertTrue($this->utility('8.8.8.8')->isAlive());
+    }
+
+    public function testIsAliveReturnsBool(): void
+    {
+        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
+            $this->markTestSkipped('Skipping test on Windows');
+        }
+
+        $this->assertIsBool($this->utility('8.8.8.8')->isAlive());
+    }
+
+    public function testLatencyForValidHost(): void
+    {
+        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
+            $this->markTestSkipped('Skipping test on Windows');
+        }
+
+        $latency = $this->utility('8.8.8.8')->latency();
+
+        $this->assertIsFloat($latency);
+    }
+
+    public function testLatencyReturnsNullableFloat(): void
+    {
+        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
+            $this->markTestSkipped('Skipping test on Windows');
+        }
+
+        $latency = $this->utility('https://not.a.real.domain')->latency();
+
+        $this->assertNull($latency);
+    }
+    public function testSetTimeoutReturnsSelf(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->setTimeout(5);
+
+        $this->assertSame($utility, $result);
+    }
+
+    public function testSetTtlReturnsSelf(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->setTtl(128);
+
+        $this->assertSame($utility, $result);
+    }
+
+    public function testUrlReturnsConstructedUrl(): void
+    {
+        $utility = $this->utility('https://example.com');
+
+        $this->assertSame('https://example.com', $utility->url());
+    }
+}

From 31eee6a93137bbfe474163733589e9a069b931fd Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:05:35 +0100
Subject: [PATCH 04/11] fix(content): preserve HTTP status on 4xx

- Use getResponse()->getStatusCode() instead of getCode()
- Preserves actual status code (401, 403, 429, etc.)
---
 src/ContentUtility.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ContentUtility.php b/src/ContentUtility.php
index 6571acb..150b0a0 100644
--- a/src/ContentUtility.php
+++ b/src/ContentUtility.php
@@ -70,7 +70,7 @@ public function response(): Response
         } catch (TransportExceptionInterface $e) {
             throw new NetworkErrorException($e->getMessage(), $e->getCode(), $e);
         } catch (ClientExceptionInterface $e) {
-            throw new FourHundredResponseException($e->getMessage(), $e->getCode(), $e);
+            throw new FourHundredResponseException($e->getMessage(), $e->getResponse()->getStatusCode(), $e);
         } catch (RedirectionExceptionInterface) {
             throw new MaxRedirectsReachedException();
         } catch (ServerExceptionInterface) {

From 5a332dbcb553f3aff585fef58151486633598452 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:06:00 +0100
Subject: [PATCH 05/11] feat(response): add status helpers and methods

- Add isSuccessful(), isRedirect(), isClientError(), isServerError()
- Add header() for single header lookup (case-insensitive)
- Add isJson() and json() for JSON response handling
- Add toArray() for response serialisation
- Add comprehensive tests for all new methods
---
 src/Resource/Response.php       |  99 ++++++++++++++++++++++++++++++
 tests/Resource/ResponseTest.php | 103 ++++++++++++++++++++++++++++++++
 2 files changed, 202 insertions(+)

diff --git a/src/Resource/Response.php b/src/Resource/Response.php
index 749d723..2215f58 100644
--- a/src/Resource/Response.php
+++ b/src/Resource/Response.php
@@ -2,6 +2,8 @@
 
 namespace Myerscode\Utilities\Web\Resource;
 
+use JsonException;
+
 readonly class Response
 {
     public function __construct(private int $code, private string $content = '', private array $headers = [])
@@ -23,8 +25,105 @@ public function dom(): Dom
         return new Dom($this->content());
     }
 
+    /**
+     * Get a single header value by name (case-insensitive)
+     */
+    public function header(string $name): ?string
+    {
+        $name = strtolower($name);
+
+        foreach ($this->headers as $key => $value) {
+            if (strtolower((string) $key) === $name) {
+                if (is_array($value)) {
+                    $first = $value[0] ?? null;
+
+                    return is_string($first) ? $first : null;
+                }
+
+                return is_string($value) ? $value : null;
+            }
+        }
+
+        return null;
+    }
+
     public function headers(): array
     {
         return $this->headers;
     }
+
+    /**
+     * Check if the response is a 4xx client error
+     */
+    public function isClientError(): bool
+    {
+        return $this->code >= 400 && $this->code < 500;
+    }
+
+    /**
+     * Check if the Content-Type header indicates JSON
+     */
+    public function isJson(): bool
+    {
+        $contentType = $this->header('content-type');
+
+        if ($contentType === null) {
+            return false;
+        }
+
+        return str_contains($contentType, 'application/json');
+    }
+
+    /**
+     * Check if the response is a 3xx redirect
+     */
+    public function isRedirect(): bool
+    {
+        return $this->code >= 300 && $this->code < 400;
+    }
+
+    /**
+     * Check if the response is a 5xx server error
+     */
+    public function isServerError(): bool
+    {
+        return $this->code >= 500 && $this->code < 600;
+    }
+
+    /**
+     * Check if the response is a 2xx success
+     */
+    public function isSuccessful(): bool
+    {
+        return $this->code >= 200 && $this->code < 300;
+    }
+
+    /**
+     * Decode the response content as JSON
+     *
+     * @return array<mixed>
+     *
+     * @throws JsonException
+     */
+    public function json(): array
+    {
+        /** @var array<mixed> $decoded */
+        $decoded = json_decode($this->content, true, 512, JSON_THROW_ON_ERROR);
+
+        return $decoded;
+    }
+
+    /**
+     * Get the response as an array
+     *
+     * @return array{code: int, content: string, headers: array<mixed>}
+     */
+    public function toArray(): array
+    {
+        return [
+            'code' => $this->code,
+            'content' => $this->content,
+            'headers' => $this->headers,
+        ];
+    }
 }
diff --git a/tests/Resource/ResponseTest.php b/tests/Resource/ResponseTest.php
index 6386a30..929c225 100644
--- a/tests/Resource/ResponseTest.php
+++ b/tests/Resource/ResponseTest.php
@@ -4,12 +4,28 @@
 
 namespace Tests\Resource;
 
+use JsonException;
 use Myerscode\Utilities\Web\Resource\Dom;
 use Myerscode\Utilities\Web\Resource\Response;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
+use Iterator;
 
 final class ResponseTest extends TestCase
 {
+    public static function statusCodeProvider(): Iterator
+    {
+        yield '200 is successful' => [200, true, false, false, false];
+        yield '201 is successful' => [201, true, false, false, false];
+        yield '299 is successful' => [299, true, false, false, false];
+        yield '301 is redirect' => [301, false, true, false, false];
+        yield '302 is redirect' => [302, false, true, false, false];
+        yield '400 is client error' => [400, false, false, true, false];
+        yield '404 is client error' => [404, false, false, true, false];
+        yield '429 is client error' => [429, false, false, true, false];
+        yield '500 is server error' => [500, false, false, false, true];
+        yield '503 is server error' => [503, false, false, false, true];
+    }
     public function testCodeReturnsStatusCode(): void
     {
         $response = new Response(200);
@@ -41,6 +57,34 @@ public function testDomReturnsDomInstance(): void
         $this->assertSame('Test', $dom->filterXPath('//h1')->text());
     }
 
+    public function testHeaderIsCaseInsensitive(): void
+    {
+        $response = new Response(200, '', ['Content-Type' => ['text/html']]);
+
+        $this->assertSame('text/html', $response->header('content-type'));
+    }
+
+    public function testHeaderReturnsNullWhenMissing(): void
+    {
+        $response = new Response(200);
+
+        $this->assertNull($response->header('x-missing'));
+    }
+
+    public function testHeaderReturnsStringValueDirectly(): void
+    {
+        $response = new Response(200, '', ['x-custom' => 'value']);
+
+        $this->assertSame('value', $response->header('x-custom'));
+    }
+
+    public function testHeaderReturnsValueByName(): void
+    {
+        $response = new Response(200, '', ['content-type' => ['application/json']]);
+
+        $this->assertSame('application/json', $response->header('content-type'));
+    }
+
     public function testHeadersDefaultsToEmptyArray(): void
     {
         $response = new Response(200);
@@ -55,4 +99,63 @@ public function testHeadersReturnsHeaders(): void
 
         $this->assertSame($headers, $response->headers());
     }
+
+    public function testIsJsonReturnsFalseForHtmlContentType(): void
+    {
+        $response = new Response(200, '<html></html>', ['content-type' => ['text/html']]);
+
+        $this->assertFalse($response->isJson());
+    }
+
+    public function testIsJsonReturnsFalseWhenNoContentType(): void
+    {
+        $response = new Response(200);
+
+        $this->assertFalse($response->isJson());
+    }
+
+    public function testIsJsonReturnsTrueForJsonContentType(): void
+    {
+        $response = new Response(200, '{}', ['content-type' => ['application/json']]);
+
+        $this->assertTrue($response->isJson());
+    }
+
+    public function testJsonDecodesContent(): void
+    {
+        $response = new Response(200, '{"foo":"bar","baz":123}');
+
+        $this->assertSame(['foo' => 'bar', 'baz' => 123], $response->json());
+    }
+
+    public function testJsonThrowsExceptionForInvalidJson(): void
+    {
+        $this->expectException(JsonException::class);
+
+        $response = new Response(200, 'not json');
+        $response->json();
+    }
+
+    #[DataProvider('statusCodeProvider')]
+    public function testStatusHelpers(int $code, bool $successful, bool $redirect, bool $clientError, bool $serverError): void
+    {
+        $response = new Response($code);
+
+        $this->assertSame($successful, $response->isSuccessful());
+        $this->assertSame($redirect, $response->isRedirect());
+        $this->assertSame($clientError, $response->isClientError());
+        $this->assertSame($serverError, $response->isServerError());
+    }
+
+    public function testToArrayReturnsAllComponents(): void
+    {
+        $headers = ['content-type' => ['text/html']];
+        $response = new Response(200, '<html></html>', $headers);
+
+        $this->assertSame([
+            'code' => 200,
+            'content' => '<html></html>',
+            'headers' => $headers,
+        ], $response->toArray());
+    }
 }

From 4925d4e552334cb09e1b16ba228852ffff5dc0dc Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:06:25 +0100
Subject: [PATCH 06/11] feat(content): add new content methods

- Add json(), contentType(), headers(), statusCode()
- Add withHeaders() and withTimeout() for request config
- Add post() for POST requests
- Add tests for all new features
---
 src/ContentUtility.php                | 137 +++++++++++++++++++++++++-
 tests/ContentUtility/FeaturesTest.php |  80 +++++++++++++++
 2 files changed, 214 insertions(+), 3 deletions(-)
 create mode 100644 tests/ContentUtility/FeaturesTest.php

diff --git a/src/ContentUtility.php b/src/ContentUtility.php
index 150b0a0..e4afd9a 100644
--- a/src/ContentUtility.php
+++ b/src/ContentUtility.php
@@ -2,11 +2,11 @@
 
 namespace Myerscode\Utilities\Web;
 
-use Myerscode\Utilities\Web\Exceptions\FourHundredResponseException;
 use Myerscode\Utilities\Web\Exceptions\ContentNotFoundException;
+use Myerscode\Utilities\Web\Exceptions\FiveHundredResponseException;
+use Myerscode\Utilities\Web\Exceptions\FourHundredResponseException;
 use Myerscode\Utilities\Web\Exceptions\MaxRedirectsReachedException;
 use Myerscode\Utilities\Web\Exceptions\NetworkErrorException;
-use Myerscode\Utilities\Web\Exceptions\FiveHundredResponseException;
 use Myerscode\Utilities\Web\Resource\Dom;
 use Myerscode\Utilities\Web\Resource\Response;
 use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
@@ -15,9 +15,21 @@
 use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
+use JsonException;
 
 class ContentUtility
 {
+    /**
+     * Custom request headers
+     *
+     * @var array<string, string>
+     */
+    private array $headers = [];
+
+    /**
+     * Request timeout in seconds
+     */
+    private int $timeout = 30;
     /**
      * The url to get content from
      */
@@ -45,6 +57,19 @@ public function content(): string
         return $response->content();
     }
 
+    /**
+     * Get the Content-Type header from the response
+     *
+     * @throws FourHundredResponseException
+     * @throws MaxRedirectsReachedException
+     * @throws NetworkErrorException
+     * @throws FiveHundredResponseException
+     */
+    public function contentType(): ?string
+    {
+        return $this->response()->header('content-type');
+    }
+
     /**
      * Get the content as a content dom
      *
@@ -56,6 +81,70 @@ public function dom(): Dom
         return new Dom($this->content());
     }
 
+    /**
+     * Get the response headers
+     *
+     * @return array<mixed>
+     *
+     * @throws FourHundredResponseException
+     * @throws MaxRedirectsReachedException
+     * @throws NetworkErrorException
+     * @throws FiveHundredResponseException
+     */
+    public function headers(): array
+    {
+        return $this->response()->headers();
+    }
+
+    /**
+     * Decode the response content as JSON
+     *
+     * @return array<mixed>
+     *
+     * @throws ContentNotFoundException
+     * @throws FiveHundredResponseException
+     * @throws JsonException
+     */
+    public function json(): array
+    {
+        return $this->response()->json();
+    }
+
+    /**
+     * Send a POST request with data
+     *
+     * @param array<mixed> $data
+     *
+     * @throws FourHundredResponseException
+     * @throws MaxRedirectsReachedException
+     * @throws NetworkErrorException
+     * @throws FiveHundredResponseException
+     */
+    public function post(array $data = []): Response
+    {
+        try {
+            $options = ['timeout' => $this->timeout];
+
+            if ($this->headers !== []) {
+                $options['headers'] = $this->headers;
+            }
+
+            $options['body'] = $data;
+
+            $response = $this->client()->request('POST', $this->uriUtility->url(), $options);
+
+            return new Response($response->getStatusCode(), $response->getContent(), $response->getHeaders());
+        } catch (TransportExceptionInterface $e) {
+            throw new NetworkErrorException($e->getMessage(), $e->getCode(), $e);
+        } catch (ClientExceptionInterface $e) {
+            throw new FourHundredResponseException($e->getMessage(), $e->getResponse()->getStatusCode(), $e);
+        } catch (RedirectionExceptionInterface) {
+            throw new MaxRedirectsReachedException();
+        } catch (ServerExceptionInterface) {
+            throw new FiveHundredResponseException();
+        }
+    }
+
     /**
      * @throws FourHundredResponseException
      * @throws MaxRedirectsReachedException
@@ -66,6 +155,7 @@ public function response(): Response
     {
         try {
             $response = $this->clientResponse();
+
             return new Response($response->getStatusCode(), $response->getContent(), $response->getHeaders());
         } catch (TransportExceptionInterface $e) {
             throw new NetworkErrorException($e->getMessage(), $e->getCode(), $e);
@@ -78,6 +168,19 @@ public function response(): Response
         }
     }
 
+    /**
+     * Get the HTTP status code
+     *
+     * @throws FourHundredResponseException
+     * @throws MaxRedirectsReachedException
+     * @throws NetworkErrorException
+     * @throws FiveHundredResponseException
+     */
+    public function statusCode(): int
+    {
+        return $this->response()->code();
+    }
+
     /**
      * Get the url that the content is got from
      */
@@ -86,6 +189,28 @@ public function url(): string
         return $this->uriUtility->url();
     }
 
+    /**
+     * Set custom request headers
+     *
+     * @param array<string, string> $headers
+     */
+    public function withHeaders(array $headers): self
+    {
+        $this->headers = array_merge($this->headers, $headers);
+
+        return $this;
+    }
+
+    /**
+     * Set the request timeout in seconds
+     */
+    public function withTimeout(int $seconds): self
+    {
+        $this->timeout = $seconds;
+
+        return $this;
+    }
+
     /**
      * Create a client to send a http request
      */
@@ -96,10 +221,16 @@ protected function client(): HttpClientInterface
 
     protected function clientResponse(): ResponseInterface
     {
+        $options = ['timeout' => $this->timeout];
+
+        if ($this->headers !== []) {
+            $options['headers'] = $this->headers;
+        }
+
         return $this->client()->request(
             'GET',
             $this->uriUtility->url(),
+            $options,
         );
     }
-
 }
diff --git a/tests/ContentUtility/FeaturesTest.php b/tests/ContentUtility/FeaturesTest.php
new file mode 100644
index 0000000..f423487
--- /dev/null
+++ b/tests/ContentUtility/FeaturesTest.php
@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\ContentUtility;
+
+use Mockery;
+use Myerscode\Utilities\Web\ContentUtility;
+use Myerscode\Utilities\Web\Resource\Response;
+use Tests\BaseContentSuite;
+
+final class FeaturesTest extends BaseContentSuite
+{
+    public function testContentTypeReturnsHeader(): void
+    {
+        $legacyMock = Mockery::mock(ContentUtility::class, ['https://localhost'])->makePartial();
+        $legacyMock->shouldReceive('response')->once()->andReturn(
+            new Response(200, '', ['content-type' => ['text/html; charset=utf-8']]),
+        );
+
+        $this->assertSame('text/html; charset=utf-8', $legacyMock->contentType());
+    }
+
+    public function testContentTypeReturnsNullWhenMissing(): void
+    {
+        $legacyMock = Mockery::mock(ContentUtility::class, ['https://localhost'])->makePartial();
+        $legacyMock->shouldReceive('response')->once()->andReturn(
+            new Response(200, ''),
+        );
+
+        $this->assertNull($legacyMock->contentType());
+    }
+
+    public function testHeadersReturnsResponseHeaders(): void
+    {
+        $headers = ['content-type' => ['text/html'], 'x-custom' => ['value']];
+
+        $legacyMock = Mockery::mock(ContentUtility::class, ['https://localhost'])->makePartial();
+        $legacyMock->shouldReceive('response')->once()->andReturn(
+            new Response(200, '', $headers),
+        );
+
+        $this->assertSame($headers, $legacyMock->headers());
+    }
+    public function testJsonDecodesResponseContent(): void
+    {
+        $legacyMock = Mockery::mock(ContentUtility::class, ['https://localhost'])->makePartial();
+        $legacyMock->shouldReceive('response')->once()->andReturn(
+            new Response(200, '{"foo":"bar"}', ['content-type' => ['application/json']]),
+        );
+
+        $this->assertSame(['foo' => 'bar'], $legacyMock->json());
+    }
+
+    public function testStatusCodeReturnsCode(): void
+    {
+        $legacyMock = Mockery::mock(ContentUtility::class, ['https://localhost'])->makePartial();
+        $legacyMock->shouldReceive('response')->once()->andReturn(
+            new Response(201, ''),
+        );
+
+        $this->assertSame(201, $legacyMock->statusCode());
+    }
+
+    public function testWithHeadersReturnsSelf(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->withHeaders(['Authorization' => 'Bearer token']);
+
+        $this->assertSame($utility, $result);
+    }
+
+    public function testWithTimeoutReturnsSelf(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->withTimeout(60);
+
+        $this->assertSame($utility, $result);
+    }
+}

From 71b1ac4ce0c7006973c9d4f2f3f957ed088fa8f0 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:06:49 +0100
Subject: [PATCH 07/11] feat(uri): add URL manipulation methods

- Add fragment(), withFragment(), withScheme()
- Add withHost(), withPath(), withPort()
- Add removeQueryParameter(), hasQueryParameter()
- Add userInfo(), isValid(), toArray(), equals()
- Add tests for all new features
---
 src/UriUtility.php                | 120 ++++++++++++++++++++++
 tests/UriUtility/FeaturesTest.php | 161 ++++++++++++++++++++++++++++++
 2 files changed, 281 insertions(+)
 create mode 100644 tests/UriUtility/FeaturesTest.php

diff --git a/src/UriUtility.php b/src/UriUtility.php
index 9647465..ed53cca 100644
--- a/src/UriUtility.php
+++ b/src/UriUtility.php
@@ -52,6 +52,22 @@ public function check(ResponseFrom $responseFrom = ResponseFrom::CURL): Response
         return $responseUtility->check($responseFrom);
     }
 
+    /**
+     * Compare two URIs for equality
+     */
+    public function equals(UriUtility $other): bool
+    {
+        return $this->value() === $other->value();
+    }
+
+    /**
+     * Get the URL fragment (the part after #)
+     */
+    public function fragment(): string
+    {
+        return $this->http->getFragment();
+    }
+
     /**
      * Get an array of query parameters from the URL
      */
@@ -75,6 +91,14 @@ public function getQueryString(string $numeric_prefix = '', string $arg_separato
         return http_build_query($this->getQueryParameters(), $numeric_prefix, $arg_separator, $enc_type);
     }
 
+    /**
+     * Check if a query parameter exists
+     */
+    public function hasQueryParameter(string $key): bool
+    {
+        return array_key_exists($key, $this->getQueryParameters());
+    }
+
     /**
      * Retrieve the host component of the URL.
      */
@@ -91,6 +115,14 @@ public function isHttps(): bool
         return 'https' === strtolower($this->scheme());
     }
 
+    /**
+     * Check if the URL is valid
+     */
+    public function isValid(): bool
+    {
+        return filter_var($this->value(), FILTER_VALIDATE_URL) !== false;
+    }
+
 
     /**
      * Add or override query parameters to the uri
@@ -140,6 +172,17 @@ public function query(): string
         return $this->http->getQuery();
     }
 
+    /**
+     * Remove a specific query parameter by key
+     */
+    public function removeQueryParameter(string $key): self
+    {
+        $params = $this->getQueryParameters();
+        unset($params[$key]);
+
+        return $this->setQuery($params);
+    }
+
     /**
      * Get the URLS scheme
      */
@@ -172,6 +215,23 @@ public function timeout(): int
         return $this->timeout;
     }
 
+    /**
+     * Get all parsed URL components as an array
+     *
+     * @return array{scheme: string, host: string, port: int, path: string, query: string, fragment: string}
+     */
+    public function toArray(): array
+    {
+        return [
+            'scheme' => $this->scheme(),
+            'host' => $this->host(),
+            'port' => $this->port(),
+            'path' => $this->path(),
+            'query' => $this->query(),
+            'fragment' => $this->fragment(),
+        ];
+    }
+
     /**
      * Get the url the utility is using.
      */
@@ -188,6 +248,16 @@ public function url(): string
         return $this->value();
     }
 
+    /**
+     * Get the user info component of the URI
+     */
+    public function userInfo(): ?string
+    {
+        $userInfo = $this->http->getUserInfo();
+
+        return $userInfo !== '' ? $userInfo : null;
+    }
+
     /**
      * Get the current URI
      */
@@ -196,6 +266,56 @@ public function value(): string
         return urldecode((string)$this->http);
     }
 
+    /**
+     * Set or replace the URL fragment
+     */
+    public function withFragment(string $fragment): self
+    {
+        $this->http = $this->http->withFragment($fragment);
+
+        return $this;
+    }
+
+    /**
+     * Set or replace the URL host
+     */
+    public function withHost(string $host): self
+    {
+        $this->http = $this->http->withHost($host);
+
+        return $this;
+    }
+
+    /**
+     * Set or replace the URL path
+     */
+    public function withPath(string $path): self
+    {
+        $this->http = $this->http->withPath($path);
+
+        return $this;
+    }
+
+    /**
+     * Set or replace the URL port
+     */
+    public function withPort(?int $port): self
+    {
+        $this->http = $this->http->withPort($port);
+
+        return $this;
+    }
+
+    /**
+     * Set or replace the URL scheme
+     */
+    public function withScheme(string $scheme): self
+    {
+        $this->http = $this->http->withScheme($scheme);
+
+        return $this;
+    }
+
     /**
      * Set the current URL
      */
diff --git a/tests/UriUtility/FeaturesTest.php b/tests/UriUtility/FeaturesTest.php
new file mode 100644
index 0000000..57e9ed6
--- /dev/null
+++ b/tests/UriUtility/FeaturesTest.php
@@ -0,0 +1,161 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\UriUtility;
+
+use Myerscode\Utilities\Web\UriUtility;
+use Tests\BaseUriSuite;
+
+final class FeaturesTest extends BaseUriSuite
+{
+    public function testEqualsReturnsFalseForDifferentUrl(): void
+    {
+        $a = $this->utility('https://example.com');
+        $b = new UriUtility('https://other.com');
+
+        $this->assertFalse($a->equals($b));
+    }
+
+    public function testEqualsReturnsTrueForSameUrl(): void
+    {
+        $a = $this->utility('https://example.com/path');
+        $b = new UriUtility('https://example.com/path');
+
+        $this->assertTrue($a->equals($b));
+    }
+
+    public function testFragmentReturnsEmptyWhenNone(): void
+    {
+        $utility = $this->utility('https://example.com');
+
+        $this->assertSame('', $utility->fragment());
+    }
+    public function testFragmentReturnsFragment(): void
+    {
+        $utility = $this->utility('https://example.com/page#section');
+
+        $this->assertSame('section', $utility->fragment());
+    }
+
+    public function testHasQueryParameterReturnsFalse(): void
+    {
+        $utility = $this->utility('https://example.com?foo=bar');
+
+        $this->assertFalse($utility->hasQueryParameter('baz'));
+    }
+
+    public function testHasQueryParameterReturnsFalseWhenNoQuery(): void
+    {
+        $utility = $this->utility('https://example.com');
+
+        $this->assertFalse($utility->hasQueryParameter('foo'));
+    }
+
+    public function testHasQueryParameterReturnsTrue(): void
+    {
+        $utility = $this->utility('https://example.com?foo=bar');
+
+        $this->assertTrue($utility->hasQueryParameter('foo'));
+    }
+
+    public function testIsValidReturnsFalseForInvalidUrl(): void
+    {
+        $this->assertFalse($this->utility('https://!!!invalid')->isValid());
+    }
+
+    public function testIsValidReturnsTrueForValidUrl(): void
+    {
+        $this->assertTrue($this->utility('https://example.com')->isValid());
+    }
+
+    public function testRemoveQueryParameter(): void
+    {
+        $utility = $this->utility('https://example.com?foo=bar&baz=qux');
+        $result = $utility->removeQueryParameter('foo');
+
+        $this->assertSame($utility, $result);
+        $this->assertSame('https://example.com?baz=qux', $utility->value());
+    }
+
+    public function testRemoveQueryParameterWhenOnly(): void
+    {
+        $utility = $this->utility('https://example.com?foo=bar');
+        $utility->removeQueryParameter('foo');
+
+        $this->assertSame('https://example.com', $utility->value());
+    }
+
+    public function testToArrayReturnsAllComponents(): void
+    {
+        $utility = $this->utility('https://example.com:8080/path?foo=bar#section');
+
+        $this->assertSame([
+            'scheme' => 'https',
+            'host' => 'example.com',
+            'port' => 8080,
+            'path' => '/path',
+            'query' => 'foo=bar',
+            'fragment' => 'section',
+        ], $utility->toArray());
+    }
+
+    public function testUserInfoReturnsNullWhenNone(): void
+    {
+        $utility = $this->utility('https://example.com');
+
+        $this->assertNull($utility->userInfo());
+    }
+
+    public function testWithFragmentSetsFragment(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->withFragment('top');
+
+        $this->assertSame($utility, $result);
+        $this->assertSame('top', $utility->fragment());
+        $this->assertSame('https://example.com#top', $utility->value());
+    }
+
+    public function testWithHostReplacesHost(): void
+    {
+        $utility = $this->utility('https://example.com/path');
+        $utility->withHost('other.com');
+
+        $this->assertSame('other.com', $utility->host());
+        $this->assertSame('https://other.com/path', $utility->value());
+    }
+
+    public function testWithPathReplacesPath(): void
+    {
+        $utility = $this->utility('https://example.com/old');
+        $utility->withPath('/new/path');
+
+        $this->assertSame('/new/path', $utility->path());
+    }
+
+    public function testWithPortNullRemovesPort(): void
+    {
+        $utility = $this->utility('https://example.com:8080');
+        $utility->withPort(null);
+
+        $this->assertSame(443, $utility->port());
+    }
+
+    public function testWithPortSetsPort(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $utility->withPort(8080);
+
+        $this->assertSame(8080, $utility->port());
+    }
+
+    public function testWithSchemeSwitchesToHttp(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->withScheme('http');
+
+        $this->assertSame($utility, $result);
+        $this->assertSame('http', $utility->scheme());
+    }
+}

From c0bc82c90193d54a0e2bcbdaba0a200de770e264 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:07:12 +0100
Subject: [PATCH 08/11] feat(response-util): add head and isAlive

- Add head() for lightweight HEAD requests
- Add setMaxRedirects() fluent setter
- Add isAlive() for quick 2xx liveness checks
- Return self instead of ResponseUtility for fluency
- Add tests for all new features
---
 src/ResponseUtility.php                | 36 +++++++++++++++++--
 tests/ResponseUtility/FeaturesTest.php | 49 ++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 3 deletions(-)
 create mode 100644 tests/ResponseUtility/FeaturesTest.php

diff --git a/src/ResponseUtility.php b/src/ResponseUtility.php
index 1f1f8fc..fc0bd0c 100644
--- a/src/ResponseUtility.php
+++ b/src/ResponseUtility.php
@@ -12,6 +12,7 @@
 use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
 use Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface;
 use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
+use Exception;
 
 class ResponseUtility
 {
@@ -150,27 +151,56 @@ public function fromHttpClient(): Response
             $statusCode = 400;
         } catch (ServerExceptionInterface) {
             $statusCode = 500;
-        } catch (\Exception) {
+        } catch (Exception) {
             throw new InvalidUrlException();
         }
 
         return new Response($statusCode);
     }
 
+    /**
+     * Send a HEAD request using curl (lighter than GET for status checks)
+     *
+     * @throws EmptyUrlException
+     * @throws InvalidUrlException
+     */
+    public function head(): Response
+    {
+        return $this->fromCurl();
+    }
+
+    /**
+     * Check if the URL responds with a 2xx status code
+     */
+    public function isAlive(ResponseFrom $method = ResponseFrom::CURL): bool
+    {
+        return $this->check($method)->isSuccessful();
+    }
+
     /**
      * Set whether or the utility should follow redirects
      */
-    public function setFollowRedirects(bool $followRedirects): ResponseUtility
+    public function setFollowRedirects(bool $followRedirects): self
     {
         $this->followRedirects = $followRedirects;
 
         return $this;
     }
 
+    /**
+     * Set the maximum number of redirects to follow
+     */
+    public function setMaxRedirects(int $maxRedirects): self
+    {
+        $this->maxRedirects = $maxRedirects;
+
+        return $this;
+    }
+
     /**
      * Set the timeout in seconds.
      */
-    public function setTimeout(int $timeout): ResponseUtility
+    public function setTimeout(int $timeout): self
     {
         $this->timeout = $timeout;
 
diff --git a/tests/ResponseUtility/FeaturesTest.php b/tests/ResponseUtility/FeaturesTest.php
new file mode 100644
index 0000000..206b9df
--- /dev/null
+++ b/tests/ResponseUtility/FeaturesTest.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\ResponseUtility;
+
+use Myerscode\Utilities\Web\Data\ResponseFrom;
+use Tests\BaseResponseSuite;
+use Tests\TestResponse;
+
+final class FeaturesTest extends BaseResponseSuite
+{
+    public function testHeadReturnsResponse(): void
+    {
+        self::$server->setResponseOfPath('/head-test', new TestResponse('', [], 200));
+
+        $response = $this->utility(self::serverUrl('/head-test'))->head();
+
+        $this->assertSame(200, $response->code());
+    }
+
+    public function testIsAliveReturnsFalseFor500(): void
+    {
+        self::$server->setResponseOfPath('/dead-test', new TestResponse('', [], 500));
+
+        $this->assertFalse($this->utility(self::serverUrl('/dead-test'))->isAlive());
+    }
+
+    public function testIsAliveReturnsTrueFor200(): void
+    {
+        self::$server->setResponseOfPath('/alive-test', new TestResponse('', [], 200));
+
+        $this->assertTrue($this->utility(self::serverUrl('/alive-test'))->isAlive());
+    }
+
+    public function testIsAliveWithHttpMethod(): void
+    {
+        self::$server->setResponseOfPath('/alive-http', new TestResponse('', [], 200));
+
+        $this->assertTrue($this->utility(self::serverUrl('/alive-http'))->isAlive(ResponseFrom::HTTP));
+    }
+    public function testSetMaxRedirectsReturnsSelf(): void
+    {
+        $utility = $this->utility('https://example.com');
+        $result = $utility->setMaxRedirects(5);
+
+        $this->assertSame($utility, $result);
+    }
+}

From 27ad1b257b84e8fb492fe23500af7a93cf324235 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:07:36 +0100
Subject: [PATCH 09/11] feat(utility): add make, response, isAlive

- Add static make() factory method
- Add response() to expose ResponseUtility
- Add isAlive() for quick liveness checks
- Add tests for all new features
---
 src/Utility.php       | 24 ++++++++++++++++++++++++
 tests/UtilityTest.php | 36 ++++++++++++++++++++++++++++++++++--
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/src/Utility.php b/src/Utility.php
index 42d1bc3..5f4c23b 100644
--- a/src/Utility.php
+++ b/src/Utility.php
@@ -8,6 +8,14 @@ public function __construct(private readonly string $url)
     {
     }
 
+    /**
+     * Create a new utility instance
+     */
+    public static function make(string $url): self
+    {
+        return new self($url);
+    }
+
     /**
      * Get the content utility
      */
@@ -16,6 +24,14 @@ public function content(): ContentUtility
         return new ContentUtility($this->url);
     }
 
+    /**
+     * Quick liveness check — is the URL responding with 2xx?
+     */
+    public function isAlive(): bool
+    {
+        return $this->response()->isAlive();
+    }
+
     /**
      * Get the Ping utility
      */
@@ -24,6 +40,14 @@ public function ping(): PingUtility
         return new PingUtility($this->url);
     }
 
+    /**
+     * Get the response utility
+     */
+    public function response(): ResponseUtility
+    {
+        return new ResponseUtility($this->url);
+    }
+
     /**
      * Get the URL utility
      */
diff --git a/tests/UtilityTest.php b/tests/UtilityTest.php
index b51c7e7..f143af6 100644
--- a/tests/UtilityTest.php
+++ b/tests/UtilityTest.php
@@ -6,11 +6,11 @@
 
 use Myerscode\Utilities\Web\ContentUtility;
 use Myerscode\Utilities\Web\PingUtility;
+use Myerscode\Utilities\Web\ResponseUtility;
 use Myerscode\Utilities\Web\UriUtility;
 use Myerscode\Utilities\Web\Utility;
-use PHPUnit\Framework\TestCase;
 
-final class UtilityTest extends TestCase
+final class UtilityTest extends BaseSuite
 {
     public function testContentReturnsContentUtility(): void
     {
@@ -19,6 +19,31 @@ public function testContentReturnsContentUtility(): void
         $this->assertInstanceOf(ContentUtility::class, $utility->content());
     }
 
+    public function testIsAliveReturnsFalseFor500(): void
+    {
+        self::$server->setResponseOfPath('/utility-dead', new TestResponse('', [], 500));
+
+        $utility = new Utility(self::serverUrl('/utility-dead'));
+
+        $this->assertFalse($utility->isAlive());
+    }
+
+    public function testIsAliveReturnsTrueFor200(): void
+    {
+        self::$server->setResponseOfPath('/utility-alive', new TestResponse('', [], 200));
+
+        $utility = new Utility(self::serverUrl('/utility-alive'));
+
+        $this->assertTrue($utility->isAlive());
+    }
+
+    public function testMakeReturnsUtilityInstance(): void
+    {
+        $utility = Utility::make('https://example.com');
+
+        $this->assertInstanceOf(Utility::class, $utility);
+    }
+
     public function testPingReturnsPingUtility(): void
     {
         $utility = new Utility('https://example.com');
@@ -26,6 +51,13 @@ public function testPingReturnsPingUtility(): void
         $this->assertInstanceOf(PingUtility::class, $utility->ping());
     }
 
+    public function testResponseReturnsResponseUtility(): void
+    {
+        $utility = new Utility('https://example.com');
+
+        $this->assertInstanceOf(ResponseUtility::class, $utility->response());
+    }
+
     public function testUrlReturnsUriUtility(): void
     {
         $utility = new Utility('https://example.com');

From 08a944bd9f0eb3d5b1e1f0ffbef3863b82f97b75 Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:07:59 +0100
Subject: [PATCH 10/11] feat(dom): add convenience methods

- Add title() and metaDescription() helpers
- Add linkHrefs() and imageSrcs() extractors
- Add meta() for arbitrary meta tag lookup
- Add tests for all new methods
---
 src/Resource/Dom.php       | 60 ++++++++++++++++++++++++++
 tests/Resource/DomTest.php | 88 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+)
 create mode 100644 tests/Resource/DomTest.php

diff --git a/src/Resource/Dom.php b/src/Resource/Dom.php
index 3e5cda9..69290f0 100644
--- a/src/Resource/Dom.php
+++ b/src/Resource/Dom.php
@@ -6,4 +6,64 @@
 
 class Dom extends Crawler
 {
+    /**
+     * Get all image sources from the page
+     *
+     * @return array<string>
+     */
+    public function imageSrcs(): array
+    {
+        $imgs = $this->filterXPath('//img[@src]');
+
+        if ($imgs->count() === 0) {
+            return [];
+        }
+
+        return $imgs->each(fn (Crawler $node): string => $node->attr('src') ?? '');
+    }
+
+    /**
+     * Get all links (href attributes) from the page
+     *
+     * @return array<string>
+     */
+    public function linkHrefs(): array
+    {
+        $anchors = $this->filterXPath('//a[@href]');
+
+        if ($anchors->count() === 0) {
+            return [];
+        }
+
+        return $anchors->each(fn (Crawler $node): string => $node->attr('href') ?? '');
+    }
+
+    /**
+     * Get a meta tag content by name
+     */
+    public function meta(string $name): ?string
+    {
+        $meta = $this->filterXPath(sprintf('//meta[@name="%s"]', $name));
+
+        return $meta->count() > 0 ? $meta->attr('content') : null;
+    }
+
+    /**
+     * Get the meta description content
+     */
+    public function metaDescription(): ?string
+    {
+        $meta = $this->filterXPath('//meta[@name="description"]');
+
+        return $meta->count() > 0 ? $meta->attr('content') : null;
+    }
+    /**
+     * Get the page title text
+     */
+    public function title(): ?string
+    {
+        $title = $this->filterXPath('//title');
+
+        return $title->count() > 0 ? $title->text() : null;
+    }
 }
diff --git a/tests/Resource/DomTest.php b/tests/Resource/DomTest.php
new file mode 100644
index 0000000..fee4645
--- /dev/null
+++ b/tests/Resource/DomTest.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Resource;
+
+use Myerscode\Utilities\Web\Resource\Dom;
+use PHPUnit\Framework\TestCase;
+
+final class DomTest extends TestCase
+{
+    public function testImagesReturnsAllSrcs(): void
+    {
+        $html = '<html><body><img src="/img1.png"><img src="/img2.jpg"></body></html>';
+        $dom = $this->makeDom($html);
+
+        $this->assertSame(['/img1.png', '/img2.jpg'], $dom->imageSrcs());
+    }
+
+    public function testImagesReturnsEmptyWhenNoImages(): void
+    {
+        $dom = $this->makeDom('<html><body><p>No images</p></body></html>');
+
+        $this->assertSame([], $dom->imageSrcs());
+    }
+
+    public function testLinksReturnsAllHrefs(): void
+    {
+        $html = '<html><body><a href="/page1">One</a><a href="/page2">Two</a></body></html>';
+        $dom = $this->makeDom($html);
+
+        $this->assertSame(['/page1', '/page2'], $dom->linkHrefs());
+    }
+
+    public function testLinksReturnsEmptyWhenNoAnchors(): void
+    {
+        $dom = $this->makeDom('<html><body><p>No links</p></body></html>');
+
+        $this->assertSame([], $dom->linkHrefs());
+    }
+
+    public function testMetaDescriptionReturnsContent(): void
+    {
+        $dom = $this->makeDom('<html><head><meta name="description" content="A test page"></head></html>');
+
+        $this->assertSame('A test page', $dom->metaDescription());
+    }
+
+    public function testMetaDescriptionReturnsNullWhenMissing(): void
+    {
+        $dom = $this->makeDom('<html><head></head></html>');
+
+        $this->assertNull($dom->metaDescription());
+    }
+
+    public function testMetaReturnsContentByName(): void
+    {
+        $html = '<html><head><meta name="author" content="John"></head></html>';
+        $dom = $this->makeDom($html);
+
+        $this->assertSame('John', $dom->meta('author'));
+    }
+
+    public function testMetaReturnsNullWhenNotFound(): void
+    {
+        $dom = $this->makeDom('<html><head></head></html>');
+
+        $this->assertNull($dom->meta('robots'));
+    }
+
+    public function testTitleReturnsNullWhenMissing(): void
+    {
+        $dom = $this->makeDom('<html><head></head></html>');
+
+        $this->assertNull($dom->title());
+    }
+
+    public function testTitleReturnsPageTitle(): void
+    {
+        $dom = $this->makeDom('<html><head><title>Hello World</title></head></html>');
+
+        $this->assertSame('Hello World', $dom->title());
+    }
+    private function makeDom(string $html): Dom
+    {
+        return new Dom($html);
+    }
+}

From 4e0ed89b60af7beccd7e4f7811a19e0b680980ef Mon Sep 17 00:00:00 2001
From: Fred Myerscough <oniice@gmail.com>
Date: Fri, 3 Apr 2026 13:08:35 +0100
Subject: [PATCH 11/11] docs: update docs for all new features

- Update README with new usage examples
- Document exception hierarchy
- Update content, ping, and URI utility docs
- Add docs for all new methods
---
 README.md               |  27 +++++++++++
 docs/content-utility.md |  61 ++++++++++++++++++++++++
 docs/ping-utility.md    |  32 +++++++++++++
 docs/uri-utility.md     | 103 +++++++++++++++++++++++++++++++++++++++-
 4 files changed, 221 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7ef811e..5f2598b 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,8 @@ composer require myerscode/utilities-web
 use Myerscode\Utilities\Web\Utility;
 
 $web = new Utility('https://example.com');
+// or use the static factory
+$web = Utility::make('https://example.com');
 
 // Get content from a URL
 $content = $web->content()->content();
@@ -34,11 +36,22 @@ $content = $web->content()->content();
 // Get a DOM crawler for the page
 $dom = $web->content()->dom();
 
+// Decode JSON responses
+$data = $web->content()->json();
+
 // Ping a host
 $result = $web->ping()->ping();
+$alive = $web->ping()->isAlive();
+
+// Quick liveness check
+$web->isAlive();
 
 // Work with URLs
 $uri = $web->url();
+
+// Check response status
+$response = $web->response()->check(\Myerscode\Utilities\Web\Data\ResponseFrom::CURL);
+$response->isSuccessful(); // true for 2xx
 ```
 
 ## Available Utilities
@@ -52,6 +65,20 @@ Ping hosts and check latency.
 ### [URI Utility](docs/uri-utility.md)
 Parse, build and manipulate URLs.
 
+## Exception Handling
+
+All package exceptions extend `Myerscode\Utilities\Web\Exceptions\WebUtilityException`, which extends `RuntimeException`. This allows catching all package exceptions in one go:
+
+```php
+use Myerscode\Utilities\Web\Exceptions\WebUtilityException;
+
+try {
+    $content = $web->content()->content();
+} catch (WebUtilityException $e) {
+    // Handle any package exception
+}
+```
+
 ## License
 
 The MIT License (MIT). Please see [License File](LICENSE) for more information.
diff --git a/docs/content-utility.md b/docs/content-utility.md
index a08b473..4323530 100644
--- a/docs/content-utility.md
+++ b/docs/content-utility.md
@@ -27,6 +27,40 @@ $dom = $utility->dom();
 $title = $dom->filterXPath('//title')->text();
 ```
 
+## json(): array
+
+Decode the response content as JSON.
+
+```php
+$data = $utility->json();
+```
+
+Throws `\JsonException` if the content is not valid JSON.
+
+## contentType(): ?string
+
+Get the Content-Type header from the response.
+
+```php
+$type = $utility->contentType(); // 'text/html; charset=utf-8'
+```
+
+## headers(): array
+
+Get all response headers.
+
+```php
+$headers = $utility->headers();
+```
+
+## statusCode(): int
+
+Get the HTTP status code.
+
+```php
+$code = $utility->statusCode(); // 200
+```
+
 ## response(): Response
 
 Get the full Response object containing status code, content and headers.
@@ -38,6 +72,33 @@ $content = $response->content();
 $headers = $response->headers();
 ```
 
+## post(array $data): Response
+
+Send a POST request with form data.
+
+```php
+$response = $utility->post(['name' => 'value']);
+$code = $response->code();
+```
+
+## withHeaders(array $headers): self
+
+Set custom request headers.
+
+```php
+$utility->withHeaders(['Authorization' => 'Bearer token']);
+$content = $utility->content();
+```
+
+## withTimeout(int $seconds): self
+
+Set the request timeout in seconds.
+
+```php
+$utility->withTimeout(60);
+$content = $utility->content();
+```
+
 ## url(): string
 
 Get the URL the utility is using.
diff --git a/docs/ping-utility.md b/docs/ping-utility.md
index 991fd25..8ed4710 100644
--- a/docs/ping-utility.md
+++ b/docs/ping-utility.md
@@ -17,6 +17,38 @@ $result = $utility->ping();
 // ['alive' => true, 'latency' => 12.0]
 ```
 
+## isAlive(): bool
+
+Check if the host is alive.
+
+```php
+$utility->isAlive(); // true
+```
+
+## latency(): ?float
+
+Get the latency in milliseconds, or null if unreachable.
+
+```php
+$utility->latency(); // 12.0
+```
+
+## setTimeout(int $seconds): self
+
+Set the ping timeout in seconds.
+
+```php
+$utility->setTimeout(5)->ping();
+```
+
+## setTtl(int $ttl): self
+
+Set the TTL (time to live).
+
+```php
+$utility->setTtl(128)->ping();
+```
+
 ## url(): string
 
 Get the URL the utility is using.
diff --git a/docs/uri-utility.md b/docs/uri-utility.md
index 1c7d5c5..a2dea98 100644
--- a/docs/uri-utility.md
+++ b/docs/uri-utility.md
@@ -5,7 +5,7 @@ Parse, build and manipulate URLs.
 ```php
 use Myerscode\Utilities\Web\UriUtility;
 
-$utility = new UriUtility('https://example.com/path?foo=bar');
+$utility = new UriUtility('https://example.com/path?foo=bar#section');
 ```
 
 ## host(): string
@@ -56,6 +56,14 @@ Get the raw query string.
 $utility->query(); // 'foo=bar'
 ```
 
+## fragment(): string
+
+Get the URL fragment (the part after #).
+
+```php
+$utility->fragment(); // 'section'
+```
+
 ## getQueryParameters(): array
 
 Get query parameters as an associative array.
@@ -89,6 +97,97 @@ Replace the entire query string.
 $utility->setQuery(['new' => 'value']);
 ```
 
+## removeQueryParameter(string $key): self
+
+Remove a specific query parameter by key.
+
+```php
+$utility->removeQueryParameter('foo');
+```
+
+## hasQueryParameter(string $key): bool
+
+Check if a query parameter exists.
+
+```php
+$utility->hasQueryParameter('foo'); // true
+```
+
+## withScheme(string $scheme): self
+
+Set or replace the URL scheme.
+
+```php
+$utility->withScheme('http');
+```
+
+## withHost(string $host): self
+
+Set or replace the URL host.
+
+```php
+$utility->withHost('other.com');
+```
+
+## withPath(string $path): self
+
+Set or replace the URL path.
+
+```php
+$utility->withPath('/new/path');
+```
+
+## withPort(?int $port): self
+
+Set or replace the URL port. Pass `null` to remove.
+
+```php
+$utility->withPort(8080);
+```
+
+## withFragment(string $fragment): self
+
+Set or replace the URL fragment.
+
+```php
+$utility->withFragment('top');
+```
+
+## userInfo(): ?string
+
+Get the user info component of the URI, or null if not present.
+
+```php
+$utility->userInfo(); // null
+```
+
+## isValid(): bool
+
+Check if the URL is valid without making a request.
+
+```php
+$utility->isValid(); // true
+```
+
+## toArray(): array
+
+Get all parsed URL components as an associative array.
+
+```php
+$utility->toArray();
+// ['scheme' => 'https', 'host' => 'example.com', 'port' => 443, 'path' => '/path', 'query' => 'foo=bar', 'fragment' => 'section']
+```
+
+## equals(UriUtility $other): bool
+
+Compare two URIs for equality.
+
+```php
+$a = new UriUtility('https://example.com');
+$b = new UriUtility('https://example.com');
+$a->equals($b); // true
+```
+
 ## check(ResponseFrom $method): Response
 
 Check the URL response using curl, headers, or HTTP client.
@@ -105,5 +204,5 @@ $response->code(); // 200
 Get the full URL string.
 
 ```php
-$utility->value(); // 'https://example.com/path?foo=bar'
+$utility->value(); // 'https://example.com/path?foo=bar#section'
 ```