Implement Exception Hierarchy For Better Error Handling #78

Ref34t · 2025-09-01T13:19:00Z

Summary
Implements exception hierarchy to improve error handling across the WordPress AI Client ecosystem, directly addressing feedback from PR 2 in https://github.com/WordPress/wp-ai-client

Changes

New Exception Classes

AiClientExceptionInterface - Base interface for catch-all exception handling
NetworkException - HTTP transport errors, connection failures, timeouts
RequestException - API authentication failures, rate limiting, malformed requests
InvalidArgumentException - Project-scoped extension of \InvalidArgumentException
RuntimeException - Project-scoped extension of \RuntimeException

Updated Code

Updated existing exception usage in AiClient.php, GenerativeAiResult.php, FunctionResponse.php
Modified ResponseException to extend RequestException for better categorization
Added comprehensive test coverage

Benefits

Unified Exception Handling:

try {
    $result = AiClient::prompt('Generate content')->generateText();
} catch (AiClientExceptionInterface $e) {
    // Catches ALL AI Client exceptions
}

Better Error Categorization:

Network issues → NetworkException
API/Auth issues → RequestException
Invalid arguments → InvalidArgumentException

Related

Addresses feedback from 2 review comments about improving exception handling for wp-ai-client integration. https://github.com/WordPress/wp-ai-client

Ref34t · 2025-09-01T13:28:41Z

@felixarntz This implements the exception hierarchy you suggested in PR 2 in the wp-ai-client review. Now developers can catch all AI Client exceptions with catch (AiClientExceptionInterface $e) for unified error handling, while still having specific exception types for different error categories (network, request, validation). The implementation is minimal and focused - exactly what was requested for better WP-ai-client integration.

felixarntz

@Ref34t Thank you for getting this started!

A few points of feedback below, and one higher-level point here: I think we should put the exceptions into specific directories. For example:

InvalidArgumentException and RuntimeException into src/Common/Exception
NetworkException and RequestException into src/Providers/Http/Exception (where we already have ResponseException)

@JasonTheAdams It would be great to get your review as well - including regarding my own feedback.

felixarntz · 2025-09-01T22:05:45Z

src/Exceptions/NetworkException.php

+ *
+ * @since 0.2.0
+ */
+class NetworkException extends RuntimeException implements AiClientExceptionInterface


What is this exception class used for? We should only introduce exceptions that we have concrete usage for.

I can see how a NetworkException might be useful, but then we should also make sure it's used where applicable.

felixarntz · 2025-09-01T22:08:03Z

src/Exceptions/RequestException.php

+ *
+ * @since 0.2.0
+ */
+class RequestException extends RuntimeException implements AiClientExceptionInterface


What would this class be used for? I'm thinking that RequestException is most likely only relevant for bad request data (i.e. as an extension of InvalidArgumentException).

Similarly to my other comment, we need to actually use it if we add it here. There are at least several places in the provider implementation code or its abstract base classes where this could be used.

I think this would also be good to throw in scenarios when a Response comes back with a 400 Bad Request status code. In that case it means an invalid argument was set that our code didn't catch, but the API did.

felixarntz · 2025-09-01T22:09:12Z

src/Providers/Http/Exception/ResponseException.php


 /**
 * Exception class for HTTP response errors.
 *
 * @since 0.1.0
 */
-class ResponseException extends Exception
+class ResponseException extends RequestException


This shouldn't extend RequestException - a ResponseException is definitely something different.

I think the main use-case for ResponseException is when the response data is unexpected - which should never happen, unless a provider changed in ways our code is not aware of. That's IMO the primary use-case for this.

JasonTheAdams · 2025-09-02T15:08:57Z

I agree with @felixarntz! I like the direction, but we need to see these exceptions being used in a few places to indicate their concrete usage.

github-actions · 2025-09-02T15:09:07Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @[email protected].

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: [email protected].

Co-authored-by: felixarntz <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>
Co-authored-by: Ref34t <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Ref34t · 2025-09-02T22:03:53Z

@felixarntz @JasonTheAdams
I've spent some time refactoring and improving the enhancements, you can see below what I did:

Architectural Reorganization

Moved exceptions to proper directories:

InvalidArgumentException & RuntimeException → src/Common/Exception/
NetworkException & RequestException → src/Providers/Http/Exception/
Updated 50+ import statements across the entire codebase

Concrete Usage Examples

NetworkException: PSR-18 network error handling in HttpTransporter::send()
RequestException: 400 Bad Request response handling in HttpTransporter::send()
ResponseException: Missing API data handling in OpenAiModelMetadataDirectory
InvalidArgumentException: 50+ validation locations throughout codebase
RuntimeException: 40+ operational error locations throughout codebase

Proper Inheritance

Fixed inheritance relationships:

RequestException extends InvalidArgumentException (for bad request data validation)
ResponseException extends RuntimeException (for unexpected provider responses)
NetworkException extends RuntimeException (for network connectivity issues)

Enhanced Developer Experience (Static factory methods suggestion)

"Simply adding static from* methods to the various *Exception classes"

RequestException (3 methods):

RequestException::fromInvalidParam('OpenAI', 'temperature', 'Must be between 0 and 2');
RequestException::fromBadRequestResponse('OpenAI', $response);
RequestException::fromBadRequestToUri($uri, 'Invalid  JSON payload');

ResponseException (4 methods):

ResponseException::fromMissingData('OpenAI', 'data');
ResponseException::fromUnexpectedStructure('OpenAI', 'array', 'string');
ResponseException::fromMalformedResponse('OpenAI', 'Invalid JSON format');
ResponseException::fromParsingFailure('OpenAI', 'model list', $jsonException);

NetworkException (5 methods):

NetworkException::fromPsr18NetworkException($uri, $networkException);
NetworkException::fromConnectionFailure($uri, 'Connection refused');
NetworkException::fromTimeout($uri, 'request', 30);
NetworkException::fromDnsFailure('api.openai.com');
NetworkException::fromSslError($uri, 'Certificate  validation failed');

Kindly review and let me know if you have any concerned

JasonTheAdams

Thanks, @Ref34t! I'm not sure I see the point in creating our own InvalidArgumentException and RuntimeException classes. Do you, @felixarntz?

felixarntz · 2025-09-02T23:20:03Z

@JasonTheAdams I do actually. It's simply about providing classes that can implement a common interface to identify "this is a specific exception from our PHP AI Client SDK".

Consuming code can then decide whether they want to catch e.g. RuntimeException and/or InvalidArgumentException or whether they want to do a single catch-all for "known" exceptions from our SDK only by catching AiClientExceptionInterface.

JasonTheAdams · 2025-09-03T15:44:17Z

I like that, @felixarntz! Admittedly, I hadn't noticed the common Interface. I like that idea of being able to catch exceptions thrown by this package.

As a note, I think we should update the AGENTS.md to include a note that all exceptions should use our own, including primitives, and if a primitive doesn't exist it should be created. Not sure if we should add this elsewhere, too. If we're going down this road it's important that we're consistent.

JasonTheAdams

I'm tracking now, @Ref34t! Good work!

I don't think we need all these static methods. As far as I can tell, there all used only one time. If that's the case, the abstraction isn't necessary and we can just let the implementing code determine the code, message, and such.

JasonTheAdams · 2025-09-03T17:47:54Z

src/Common/Exception/InvalidArgumentException.php

+ * This extends PHP's built-in InvalidArgumentException while implementing
+ * the AI Client exception interface for consistent catch handling.
+ *
+ * @since 0.2.0


Here and throughout, always use n.e.x.t because we don't want to assume we know the version something will be released in.

Suggested change

* @since 0.2.0

* @since n.e.x.t

felixarntz

@Ref34t @JasonTheAdams I do think some of the static methods are useful - just not all of them.

Per my previous feedback, @Ref34t it would be great if you could review the codebase for where exceptions are thrown and update these exceptions to use the new exception classes and new static methods if applicable.

We should not introduce any exception classes or any static methods that aren't used anywhere - I think that's a good guiding principle. Therefore it's important that we update any existing exceptions to use the new approach, and if there are none for a specific exception or static method, we know it's not useful, at least not at this point.

Ref34t · 2025-09-04T15:47:31Z

very interesting Convo Champs @felixarntz @JasonTheAdams 🥇
I'll work it this today and bring the best from it based on my idea and your thoughts

Mohamed Khaled added 2 commits September 1, 2025 16:11

Implement simplified exception hierarchy for better error handling

9d4b949

Fix code style violations

67b60dc

Ref34t marked this pull request as ready for review September 1, 2025 13:28

felixarntz added the [Type] Enhancement A suggestion for improvement. label Sep 1, 2025

felixarntz reviewed Sep 1, 2025

View reviewed changes

felixarntz mentioned this pull request Sep 2, 2025

Enhancement: Improve Error Handling Developer Experience #60

Closed

JasonTheAdams self-requested a review September 2, 2025 14:50

Mohamed Khaled added 2 commits September 3, 2025 00:55

Implement exception hierarchy reorganization with static factory methods

85f8bf9

Fix code style violations in exception classes

bca86db

Mohamed Khaled added 2 commits September 3, 2025 01:05

Fix line length violations in exception factory methods

1e47d83

Fix function declaration brace placement

722138b

JasonTheAdams reviewed Sep 2, 2025

View reviewed changes

JasonTheAdams mentioned this pull request Sep 3, 2025

Development roadmap #8

Open

20 tasks

JasonTheAdams requested changes Sep 3, 2025

View reviewed changes

felixarntz reviewed Sep 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement Exception Hierarchy For Better Error Handling #78

Implement Exception Hierarchy For Better Error Handling #78

Uh oh!

Ref34t commented Sep 1, 2025 •

edited

Loading

Uh oh!

Ref34t commented Sep 1, 2025

Uh oh!

felixarntz left a comment

Uh oh!

felixarntz Sep 1, 2025

Uh oh!

felixarntz Sep 1, 2025

Uh oh!

felixarntz Sep 1, 2025

Uh oh!

JasonTheAdams commented Sep 2, 2025

Uh oh!

github-actions bot commented Sep 2, 2025 •

edited

Loading

Uh oh!

Ref34t commented Sep 2, 2025

Uh oh!

JasonTheAdams left a comment

Uh oh!

felixarntz commented Sep 2, 2025

Uh oh!

JasonTheAdams commented Sep 3, 2025

Uh oh!

JasonTheAdams left a comment

Uh oh!

JasonTheAdams Sep 3, 2025

Uh oh!

felixarntz left a comment

Uh oh!

Ref34t commented Sep 4, 2025

Uh oh!

Uh oh!

Implement Exception Hierarchy For Better Error Handling #78

Are you sure you want to change the base?

Implement Exception Hierarchy For Better Error Handling #78

Uh oh!

Conversation

Ref34t commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ref34t commented Sep 1, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams commented Sep 2, 2025

Uh oh!

github-actions bot commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

Ref34t commented Sep 2, 2025

Uh oh!

JasonTheAdams left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz commented Sep 2, 2025

Uh oh!

JasonTheAdams commented Sep 3, 2025

Uh oh!

JasonTheAdams left a comment

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Ref34t commented Sep 4, 2025

Uh oh!

Uh oh!

Ref34t commented Sep 1, 2025 •

edited

Loading

github-actions bot commented Sep 2, 2025 •

edited

Loading