✨ 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.

Author: jrfnl

PHPCSUtils/Exceptions/MissingArgumentError.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2024 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Exceptions;
+
+use PHPCSUtils\Exceptions\RuntimeException;
+
+/**
+ * Exception for when a (conditionally) required parameter is not passed.
+ *
+ * {@internal This exception should probably extend the PHP native `ArgumentCountError`, but
+ * that would inhibit the use of this exception, as replacing existing exceptions with this
+ * (better) one would then be a breaking change.}
+ *
+ * @since 1.1.0
+ */
+final class MissingArgumentError extends RuntimeException
+{
+
+    /**
+     * Create a new MissingArgumentError exception with a standardized start of the text.
+     *
+     * @param int    $position The argument position in the function signature. 1-based.
+     * @param string $name     The argument name in the function signature.
+     * @param string $message  Arbitrary message text, which should indicate under what
+     *                         conditions the parameter is required.
+     *
+     * @return \PHPCSUtils\Exceptions\MissingArgumentError
+     */
+    public static function create($position, $name, $message)
+    {
+        $stack = \debug_backtrace(\DEBUG_BACKTRACE_IGNORE_ARGS, 2);
+
+        return new self(
+            \sprintf(
+                '%s::%s(): Argument #%d (%s) is required %s.',
+                $stack[1]['class'],
+                $stack[1]['function'],
+                $position,
+                $name,
+                $message
+            )
+        );
+    }
+}

Tests/Exceptions/MissingArgumentError/MissingArgumentErrorTest.php

@@ -0,0 +1,43 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2024 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Tests\Exceptions\MissingArgumentError;
+
+use PHPCSUtils\Exceptions\MissingArgumentError;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Exceptions\MissingArgumentError
+ *
+ * @since 1.1.0
+ */
+final class MissingArgumentErrorTest extends TestCase
+{
+
+    /**
+     * Test that the text of the exception is as expected.
+     *
+     * @return void
+     */
+    public function testCreate()
+    {
+        $message = \sprintf(
+            '%s(): Argument #2 ($config) is required for PHPCS 4.x',
+            __METHOD__
+        );
+
+        $this->expectException('PHPCSUtils\Exceptions\MissingArgumentError');
+        $this->expectExceptionMessage($message);
+
+        throw MissingArgumentError::create(2, '$config', 'for PHPCS 4.x');
+    }
+}