Generic/UnusedFunctionParameter: ignore magic methods

The function signature of magic methods - with the exception of `__construct()` and `__invoke()` - is dictated by PHP and unused parameters cannot be removed, which means that the warnings for these can never be resolved, only ignored via annotations.

This commit fixes this by checking whether a function is a magic method and if so, bowing out.

Includes unit tests.

Note: while not all magic methods take arguments, I'm still including the (nearly) full list of magic methods in the property as the other magic methods can be ignored anyway (no arguments).

src/Standards/Generic/Sniffs/CodeAnalysis/UnusedFunctionParameterSniff.php

@@ -30,6 +30,32 @@ class UnusedFunctionParameterSniff implements Sniff
      */
     public $ignoreTypeHints = [];
 
+    /**
+     * A list of all PHP magic methods with fixed method signatures.
+     *
+     * Note: `__construct()` and `__invoke()` are excluded on purpose
+     * as their method signature is not fixed.
+     *
+     * @var array
+     */
+    private $magicMethods = [
+        '__destruct'    => true,
+        '__call'        => true,
+        '__callstatic'  => true,
+        '__get'         => true,
+        '__set'         => true,
+        '__isset'       => true,
+        '__unset'       => true,
+        '__sleep'       => true,
+        '__wakeup'      => true,
+        '__serialize'   => true,
+        '__unserialize' => true,
+        '__tostring'    => true,
+        '__set_state'   => true,
+        '__clone'       => true,
+        '__debuginfo'   => true,
+    ];
+
 
     /**
      * Returns an array of tokens this test wants to listen for.
@@ -71,8 +97,18 @@ public function process(File $phpcsFile, $stackPtr)
         $extends    = false;
 
         if ($token['code'] === T_FUNCTION) {
-            $classPtr   = $phpcsFile->getCondition($stackPtr, T_CLASS);
+            $classPtr = $phpcsFile->getCondition($stackPtr, T_CLASS);
             if ($classPtr !== false) {
+                // Check for magic methods and ignore these as the method signature cannot be changed.
+                $methodName = $phpcsFile->getDeclarationName($stackPtr);
+                if (empty($methodName) === false) {
+                    $methodNameLc = strtolower($methodName);
+                    if (isset($this->magicMethods[$methodNameLc]) === true) {
+                        return;
+                    }
+                }
+
+                // Check for extends/implements and adjust the error code when found.
                 $implements = $phpcsFile->findImplementedInterfaceNames($classPtr);
                 $extends    = $phpcsFile->findExtendedClassName($classPtr);
                 if ($extends !== false) {
@@ -81,7 +117,7 @@ public function process(File $phpcsFile, $stackPtr)
                     $errorCode .= 'InImplementedInterface';
                 }
             }
-        }
+        }//end if
 
         $params       = [];
         $methodParams = $phpcsFile->getMethodParameters($stackPtr);

src/Standards/Generic/Tests/CodeAnalysis/UnusedFunctionParameterUnitTest.inc

@@ -44,13 +44,13 @@ HERE;
     $x = $parameter; // This line must be immediately after the HERE; with no intervening blank lines.
     $tango = <<<HERE
 1 Must be a HEREdoc
-2 
-3 
-4 
-5   
+2
+3
+4
+5
 6
 7
-8 
+8
 9 at least 9 lines long
 HERE;
 }
@@ -172,3 +172,80 @@ class MyExtendedClass implements SomeInterface {
         $fn = fn($c, $d) => $c[2];
     }
 }
+
+
+/**
+ * Magic methods must match the function signature dictated by PHP.
+ * Flagging unused parameters leads to notices which cannot be solved.
+ */
+class MagicMethodsWithParams {
+    public function __set(string $name, mixed $value) {
+        // Forbid dynamic properties & overloading inaccessible properties.
+        throw new RuntimeException('Forbidden');
+    }
+
+    public function __get(string $name) {
+        throw new RuntimeException('Forbidden');
+    }
+
+    public function __isset(string $name) {
+        throw new RuntimeException('Forbidden');
+    }
+
+    public function __unset(string $name) {
+        throw new RuntimeException('Forbidden');
+    }
+
+    public function __unserialize( array $data ) {
+        // Prevent unserializing from a stored representation of the object for security reasons.
+        $this->instance = new self();
+    }
+
+    public static function __set_state(array $properties) {
+        return new self();
+    }
+
+    public function __call(string $name, array $arguments) {
+        if (method_exists($this, $name)) {
+            // None of the methods which can be called in this class take arguments, so not passing them.
+            return $this->$name();
+        }
+    }
+
+    public static function __callStatic(string $name, array $arguments) {
+        if (method_exists($this, $name)) {
+            // None of the methods which can be called in this class take arguments, so not passing them.
+            return self::$name();
+        }
+    }
+}
+
+/**
+ * Unused parameters in magic methods which have flexible function signatures should still be flagged.
+ */
+class MagicMethodsWithParamsNotDictatedByPHP {
+    public $foo;
+    public function __construct($foo, $bar, $baz) {
+        $this->foo = $foo;
+    }
+
+    public function __invoke($foo, $bar, $baz) {
+        $this->foo = $foo;
+    }
+}
+
+/**
+ * Unused parameters in magic methods which have flexible function signatures
+ * where the method potentially overloads a parent method should still be flagged,
+ * but should use the `FoundInExtendedClassAfterLastUsed` error code.
+ */
+class MagicMethodsWithParamsNotDictatedByPHPInChildClass extends SomeParent{
+    public $foo;
+    public function __construct($foo, $bar, $baz) {
+        $this->foo = $foo;
+    }
+
+    public function __invoke($foo, $bar, $baz) {
+        $this->foo = $foo;
+    }
+}

src/Standards/Generic/Tests/CodeAnalysis/UnusedFunctionParameterUnitTest.php

@@ -52,6 +52,10 @@ public function getWarningList()
             125 => 2,
             163 => 1,
             172 => 1,
+            228 => 2,
+            232 => 2,
+            244 => 2,
+            248 => 2,
         ];
 
     }//end getWarningList()