Implement Exception Hierarchy For Better Error Handling

AGENTS.md

@@ -83,6 +83,15 @@ The production code in `src` follows a structured namespace hierarchy under the
 
 All parameters, return values, and properties must use explicit type hints, except in cases where providing the correct type hint would be impossible given limitations of backward compatibility with PHP 7.4. In any case, concrete type annotations using PHPStan should be present.
 
+### Exception handling
+
+All exceptions must use the project's custom exception classes rather than PHP built-in exceptions. This includes:
+
+- Use `WordPress\AiClient\Common\Exception\InvalidArgumentException` instead of PHP's `\InvalidArgumentException`
+- Use `WordPress\AiClient\Common\Exception\RuntimeException` instead of PHP's `\RuntimeException`
+- All custom exceptions implement `WordPress\AiClient\Exceptions\AiClientExceptionInterface` for unified exception handling
+- Follow usage-driven design: only implement static factory methods that are actually used in the codebase
+
 ### Naming conventions
 
 The following naming conventions must be followed for consistency and autoloading:

src/AiClient.php

@@ -5,6 +5,8 @@
 namespace WordPress\AiClient;
 
 use WordPress\AiClient\Builders\PromptBuilder;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\ProviderImplementations\Anthropic\AnthropicProvider;
 use WordPress\AiClient\ProviderImplementations\Google\GoogleProvider;
 use WordPress\AiClient\ProviderImplementations\OpenAi\OpenAiProvider;
@@ -282,7 +284,7 @@ public static function generateSpeechResult(
      */
     public static function message(?string $text = null)
     {
-        throw new \RuntimeException(
+        throw new RuntimeException(
             'MessageBuilder is not yet available. This method depends on builder infrastructure. ' .
             'Use direct generation methods (generateTextResult, generateImageResult, etc.) for now.'
         );
@@ -302,7 +304,7 @@ private static function validateModelOrConfigParameter($modelOrConfig): void
             && !$modelOrConfig instanceof ModelInterface
             && !$modelOrConfig instanceof ModelConfig
         ) {
-            throw new \InvalidArgumentException(
+            throw new InvalidArgumentException(
                 'Parameter must be a ModelInterface instance (specific model), ' .
                 'ModelConfig instance (for auto-discovery), or null (default auto-discovery). ' .
                 sprintf('Received: %s', is_object($modelOrConfig) ? get_class($modelOrConfig) : gettype($modelOrConfig))

src/Builders/PromptBuilder.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Builders;
 
-use InvalidArgumentException;
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Messages\DTO\Message;

src/Common/AbstractDataTransferObject.php

@@ -4,11 +4,11 @@
 
 namespace WordPress\AiClient\Common;
 
-use InvalidArgumentException;
 use JsonSerializable;
 use stdClass;
 use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
 use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 
 /**
  * Abstract base class for all Data Value Objects in the AI Client.

src/Common/AbstractEnum.php

@@ -5,10 +5,10 @@
 namespace WordPress\AiClient\Common;
 
 use BadMethodCallException;
-use InvalidArgumentException;
 use JsonSerializable;
 use ReflectionClass;
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 
 /**
  * Abstract base class for enum-like behavior in PHP 7.4.

src/Common/Exception/InvalidArgumentException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common\Exception;
+
+use WordPress\AiClient\Exceptions\AiClientExceptionInterface;
+
+/**
+ * Exception thrown when an invalid argument is provided.
+ *
+ * This extends PHP's built-in InvalidArgumentException while implementing
+ * the AI Client exception interface for consistent catch handling.
+ *
+ * @since n.e.x.t
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements AiClientExceptionInterface
+{
+}

src/Common/Exception/RuntimeException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common\Exception;
+
+use WordPress\AiClient\Exceptions\AiClientExceptionInterface;
+
+/**
+ * Exception thrown for runtime errors.
+ *
+ * This extends PHP's built-in RuntimeException while implementing
+ * the AI Client exception interface for consistent catch handling.
+ *
+ * @since n.e.x.t
+ */
+class RuntimeException extends \RuntimeException implements AiClientExceptionInterface
+{
+}

src/Exceptions/AiClientExceptionInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Exceptions;
+
+use Throwable;
+
+/**
+ * Base interface for all AI Client exceptions.
+ *
+ * This interface allows callers to catch all AI Client specific exceptions
+ * with a single catch statement.
+ *
+ * @since n.e.x.t
+ */
+interface AiClientExceptionInterface extends Throwable
+{
+}

src/Files/DTO/File.php

@@ -4,9 +4,9 @@
 
 namespace WordPress\AiClient\Files\DTO;
 
-use InvalidArgumentException;
-use RuntimeException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\ValueObjects\MimeType;
 
@@ -375,12 +375,7 @@ private function determineMimeType(
 
             $extension = pathinfo($cleanPath, PATHINFO_EXTENSION);
             if (!empty($extension)) {
-                try {
-                    return MimeType::fromExtension($extension);
-                } catch (InvalidArgumentException $e) {
-                    // Extension not recognized, continue to error
-                    unset($e);
-                }
+                return MimeType::fromExtension($extension);
             }
         }
 

src/Files/ValueObjects/MimeType.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Files\ValueObjects;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 
 /**
  * Value object representing a MIME type.

src/Messages/DTO/Message.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
 /**
@@ -188,7 +188,7 @@ final public static function fromArray(array $array): self
             return new ModelMessage($parts);
         } else {
             // Only USER and MODEL roles are supported
-            throw new \InvalidArgumentException('Invalid message role: ' . $role->value);
+            throw new InvalidArgumentException('Invalid message role: ' . $role->value);
         }
     }
 }

src/Messages/DTO/MessagePart.php

@@ -4,9 +4,9 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use InvalidArgumentException;
-use RuntimeException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Messages\Enums\MessagePartChannelEnum;
 use WordPress\AiClient\Messages\Enums\MessagePartTypeEnum;

src/ProviderImplementations/Anthropic/AnthropicModelMetadataDirectory.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Anthropic;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Providers\Http\Contracts\RequestAuthenticationInterface;
 use WordPress\AiClient\Providers\Http\DTO\ApiKeyRequestAuthentication;

src/ProviderImplementations/Anthropic/AnthropicProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Anthropic;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/ProviderImplementations/Google/GoogleModelMetadataDirectory.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Google;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;

src/ProviderImplementations/Google/GoogleProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Google;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/ProviderImplementations/OpenAi/OpenAiModelMetadataDirectory.php

@@ -4,13 +4,13 @@
 
 namespace WordPress\AiClient\ProviderImplementations\OpenAi;
 
-use RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Providers\Http\DTO\Request;
 use WordPress\AiClient\Providers\Http\DTO\Response;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
+use WordPress\AiClient\Providers\Http\Exception\ResponseException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 use WordPress\AiClient\Providers\Models\DTO\SupportedOption;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
@@ -53,9 +53,7 @@ protected function parseResponseToModelMetadataList(Response $response): array
         /** @var ModelsResponseData $responseData */
         $responseData = $response->getData();
         if (!isset($responseData['data']) || !$responseData['data']) {
-            throw new RuntimeException(
-                'Unexpected API response: Missing the data key.'
-            );
+            throw ResponseException::fromMissingData('OpenAI', 'data');
         }
 
         // Unfortunately, the OpenAI API does not return model capabilities, so we have to hardcode them here.

src/ProviderImplementations/OpenAi/OpenAiProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\OpenAi;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/Providers/ApiBasedImplementation/AbstractApiBasedModelMetadataDirectory.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\ApiBasedImplementation;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;
 use WordPress\AiClient\Providers\Http\Contracts\WithHttpTransporterInterface;
 use WordPress\AiClient\Providers\Http\Contracts\WithRequestAuthenticationInterface;

src/Providers/Contracts/ModelMetadataDirectoryInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
 /**

src/Providers/Contracts/ProviderInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\DTO\ProviderMetadata;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;

src/Providers/Contracts/ProviderOperationsHandlerInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Operations\Contracts\OperationInterface;
 
 /**

src/Providers/DTO/ProviderModelsMetadata.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Providers\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
 /**

src/Providers/Http/DTO/Request.php

@@ -4,9 +4,9 @@
 
 namespace WordPress\AiClient\Providers\Http\DTO;
 
-use InvalidArgumentException;
 use JsonException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
 

src/Providers/Http/DTO/Response.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Providers\Http\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
 
 /**

src/Providers/Http/Exception/NetworkException.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Http\Exception;
+
+use WordPress\AiClient\Common\Exception\RuntimeException;
+
+/**
+ * Exception thrown for network-related errors.
+ *
+ * This includes HTTP transport errors, connection failures,
+ * timeouts, and other network-related issues.
+ *
+ * @since n.e.x.t
+ */
+class NetworkException extends RuntimeException
+{
+    /**
+     * Creates a NetworkException from a PSR-18 network exception.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $uri The URI that was being requested.
+     * @param \Throwable $networkException The PSR-18 network exception.
+     * @return self
+     */
+    public static function fromPsr18NetworkException(string $uri, \Throwable $networkException): self
+    {
+        $message = sprintf(
+            'Network error occurred while sending request to %s: %s',
+            $uri,
+            $networkException->getMessage()
+        );
+
+        return new self($message, 0, $networkException);
+    }
+}