Adding `class UnsupportedOperationException extends RuntimeException` to php? View as Markdown

Hi internals,

Currently, there doesn't seem to be an exact fit for indicating that a method isn't supported on an object by design (and will throw unconditionally).
(For example, when implementing an interface or overriding a base class, e.g. an Immutable datastructure not implementing offsetSet/offsetUnset,
an object that does not support serialization and overrides __serialize/__unserialize to forbid it, etc.)

• BadMethodCallException - Exception thrown if a callback refers to an undefined method or if some arguments are missing.
• DomainException/RangeException - Seemingly refer to argument values
• LogicException - "Exception that represents error in the program logic. This kind of exception should lead directly to a fix in your code."
  I don't believe it's quite that, because code designed for the interface implementing the method (e.g. ArrayAccess) might have correct logic,
  it's the choice of implementation/subclass at runtime that caused the exception.
• RuntimeException and its subclasses are also used for unpredictable errors such as missing files, network/db errors, etc,
  making the meaning of try { ... } catch (RuntimeException $e) {} less clear.
• BadMethodCallException - Exception thrown if a callback refers to an undefined method or if some arguments are missing.'
  seems misleading as well since the method is defined and has its arguments, and existing uses in CachingIterator/Phar are checking the object's properties or arguments.
  (Uncaught BadMethodCallException: CachingIterator does not fetch string value (see CachingIterator::__construct) in %s:%d)

RuntimeException (or a userland subclass) is the most common exception type I see used for this purpose,
but RuntimeException is already used for many other things and has many subclasses.
https://www.php.net/manual/en/spl.exceptions.php#spl.exceptions.tree https://www.php.net/manual/en/class.exception.php
(RuntimeException and subclasses are also used for unpredictable errors such as missing files, network/db errors, some types of errors in destructors, etc,
making writing try { ... } catch (RuntimeException $e) {} to catch this also catch other issues that should instead be rethrown.)

It would be useful to provide this instead of having extensions or userland code throw RuntimeException or
implement their own exceptions https://www.php.net/manual/en/class.solrillegaloperationexception

IDEs/type checkers would also have more information to indicate that a method call is probably invalid in a use
case and it would allow userland code to be have more specific api documentation/type info than @throws RuntimeException
(rather than deliberately invoking a shared helper method to throw exceptions).

• Type checkers already check this - e.g. https://psalm.dev/docs/running_psalm/configuration/#ignoreexceptions https://github.com/phan/phan/wiki/Issue-Types-Caught-by-Phan#phanthrowcommentintostring

Thoughts on adding UnsupportedOperationException to the spl?

Thanks,
Tyson