Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127211
Message-ID: <c2369d3c-515e-4b8f-a656-bd1265e9d59e@bastelstu.be>
Date: Sun, 27 Apr 2025 22:57:24 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] [RFC] Throwable Hierarchy Policy for Extensions
To: Kamil Tekiela <tekiela246@gmail.com>
Cc: PHP internals <internals@lists.php.net>,
 "Gina P. Banyard" <internals@gpb.moe>
References: <ffadb6e6-5d16-4b45-a020-4b91565e2ee6@bastelstu.be>
 <CAGBsUrc_wjofCOEuz7MNhuVtpmJJwsatDPCjfAdHH6PQriqgZw@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CAGBsUrc_wjofCOEuz7MNhuVtpmJJwsatDPCjfAdHH6PQriqgZw@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=C3=BCsterhus?=)

Hi

On 4/27/25 22:40, Kamil Tekiela wrote:
>> The exception message MUST NOT be the only property that allows to
> differentiate different types of error that the user may be interested in.
> 
> What does this mean exactly? Can you give an example?

This is intended to say “if a user calls ->getMessage() and consumes it 
in an `if()` statement, then you are doing it wrong” and “the error 
message is intended for human consumption and changes to the message are 
not considered breaking changes”.

Ideally different exception classes should be used, but using the 
`$code` property to differentiate between different types of error is 
also acceptable when there is a wide range of errors the user might be 
interested in. For PDO this might be:

     PdoException extends Exception
     PdoError extends Error
     UnsuccessfulQueryException extends PdoException
     QuerySyntaxError extends PdoError

And then in UnsuccessfulQueryException, use a different code for 
"Duplicate entry", "Query timed out", and "Deadlock" to avoid adding a 
separate class for each failure case. It might make sense to add classes 
for the failure cases that are most likely to require special handling. 
e.g. a DeadlockException to retry the transaction.

But as a user I should not need to do:

     again:
     try {
         $query->execute();
     } catch (UnsuccessfulQueryException $e) {
         if (str_contains($e->getMessage(), 'Timeout')) {
             goto again;
         }
         throw $e
     }

to determine whether it was a timeout, a deadlock or a duplicate entry.

Do you have a wording suggestion to make it clearer what is meant by 
that sentence?

Best regards
Tim Düsterhus