Merge pull request WordPress#78 from Ref34t/feature/exception-hierarchy

Implement Exception Hierarchy For Better Error Handling

Author: felixarntz

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 the custom primitive exceptions in `WordPress\AiClient\Common\Exception\` instead of the PHP primitive exceptions
+- If a PHP primitive exception is needed that doesn't have a custom exception counterpart, then create one that extends the primitive and implements AiClientExceptionInterface
+- 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;
@@ -312,7 +314,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.'
         );
@@ -332,7 +334,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/Contracts/AiClientExceptionInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common\Contracts;
+
+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/Common/Exception/InvalidArgumentException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common\Exception;
+
+use WordPress\AiClient\Common\Contracts\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\Common\Contracts\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/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;
 

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.