✨ Introduce 7 new exceptions

[jrfnl]

These exceptions are primarily for use by PHPCSUtils itself, though could be used for utilities in external standards as well.

All exceptions extend the PHPCS native RuntimeException, which means replacing existing exceptions being thrown with the new exceptions will not cause a breaking change as catch( PHP_CodeSniffer\Exceptions\RuntimeException $e ) will still catch the new exceptions.

Having said that, once the new exceptions are in use, it also allows for making the catch more specific, which should allow for surfacing errors in sniffs which were accidentally caught.

✨ New PHPCSUtils native RuntimeException class

This exception extends the PHPCS native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change.

This exception is also not final to allow more specific exceptions to extend from it. This is, again, deliberate, to allow pre-existing PHPCSUtils code to switch to more specific child-exceptions without causing a breaking change.

Includes changing the InvalidTokenArray exception to extend this new exception.

✨ New PHPCSUtils\Exceptions\TypeError exception class

New exception to flag an invalid argument type passed to a method using a standardized message.

This exception extends the PHPCSUtils native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change.

If, by the time a 2.0 release happens, usage of this exception has not been replaced with PHP native type declarations yet, it should be considered to switch the parent class for the exception to the PHP native TypeError class (PHP 7.0+), which this exception largely emulates.

Includes perfunctory test for the exception.

✨ New PHPCSUtils\Exceptions\ValueError exception class

New exception to flag arguments using the correct type, but where the value doesn't comply with predefined restrictions, like an empty string being passed, when only a non-empty string is accepted or a negative integer being passed when a positive integer is expected.

The exception ensures these issues are flagged with a more consistent message format using a standardized message prefix.

This exception extends the PHPCSUtils native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change.

By rights, this exception should extend the PHP native ValueError class, but unfortunately, that class is not available until PHP 8.0 (and not extending the RuntimeException would be a breaking change).

By the time a 2.0 release happens, it should be considered to switch the parent class for the exception to the PHP native ValueError (PHP 8.0+) if the minimum supported PHP version allows for it.

Includes perfunctory test for the exception.

✨ New PHPCSUtils\Exceptions\OutOfBoundsStackPtr exception class

New exception to flag a passed stack pointer which doesn't exist in the $phpcsFile.

This exception extends the PHPCSUtils native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change, though extending the PHPCSUtils ValueError class would also have been an option.

By rights, this exception should probably extend the PHP native OutOfBoundsException class, but not extending the RuntimeException would be a breaking change.

By the time a 2.0 release happens, it should be considered to switch the parent class for the exception to the PHP native OutOfBoundsException.

Includes perfunctory test for the exception.

✨ New PHPCSUtils\Exceptions\UnexpectedTokenType exception class

New exception to flag a passed stack pointer argument, which does not comply with the token type requirements of the receiving method.

This exception extends the PHPCSUtils native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change, though extending the PHPCSUtils ValueError class would also have been an option.

By rights, this exception should probably extend the PHP native InvalidArgumentException class, but not extending the RuntimeException would be a breaking change.

By the time a 2.0 release happens, it should be considered to switch the parent class for the exception to the PHP native InvalidArgumentException.

Includes perfunctory test for the exception.

✨ New PHPCSUtils\Exceptions\LogicException class

New exception to flag an error in the program logic.

The exception ensures these issues are flagged with a more consistent message format using a standardized message prefix.

This exception extends the PHPCS native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change.

By rights, this exception should extend the PHP native LogicException class, but not extending the RuntimeException would be a breaking change.

By the time a 2.0 release happens, it should be considered to switch the parent class for the exception to the PHP native LogicException.

Includes perfunctory test for the exception.

✨ New PHPCSUtils\Exceptions\MissingArgumentError exception class

New exception to flag missing, conditionally required, parameters.

The exception ensures these issues are flagged with a more consistent message format using a standardized message prefix.

This exception extends the PHPCS native RuntimeException to allow pre-existing PHPCSUtils code to switch to this exception without causing a breaking change.

By rights, this exception should extend the PHP native ArgumentCountError class, but not extending the RuntimeException would be a breaking change.

By the time a 2.0 release happens, it should be considered to switch the parent class for the exception to the PHP native ArgumentCountError.

Includes perfunctory test for the exception.

[jrfnl]

Rebased without changes. Merging once the build passes.