Filters/ExactMatch: deprecate the getBlacklist() and `getWhitelist(…

…)` methods Deprecate the `getBlacklist()` and `getWhitelist()` methods and introduce the `getDisallowedFiles()` and `getAllowedFiles()` replacement methods. When available in child classes, the `getDisallowedFiles()` and `getAllowedFiles()` methods will take precedence over the deprecated `getBlacklist()` and `getWhitelist()` methods. Fixes 198
PHPCSStandards · Jan 12, 2024 · 9d4af7a · 9d4af7a
1 parent f6566e9
commit 9d4af7a
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 8 deletions.
diff --git a/src/Filters/ExactMatch.php b/src/Filters/ExactMatch.php
@@ -47,22 +47,32 @@ public function accept()
         }
 
         if ($this->disallowedFiles === null) {
-            $this->disallowedFiles = $this->getblacklist();
+            $this->disallowedFiles = $this->getDisallowedFiles();
+
+            // BC-layer.
+            if ($this->disallowedFiles === null) {
+                $this->disallowedFiles = $this->getBlacklist();
+            }
         }
 
         if ($this->allowedFiles === null) {
-            $this->allowedFiles = $this->getwhitelist();
+            $this->allowedFiles = $this->getAllowedFiles();
+
+            // BC-layer.
+            if ($this->allowedFiles === null) {
+                $this->allowedFiles = $this->getWhitelist();
+            }
         }
 
         $filePath = Util\Common::realpath($this->current());
 
-        // If file is both disallowed and allowed, the disallowed files list takes precedence.
+        // If a file is both disallowed and allowed, the disallowed files list takes precedence.
         if (isset($this->disallowedFiles[$filePath]) === true) {
             return false;
         }
 
         if (empty($this->allowedFiles) === true && empty($this->disallowedFiles) === false) {
-            // We are only checking a disallowed files list, so everything else should be allowed.
+            // We are only checking the disallowed files list, so everything else should be allowed.
             return true;
         }
 
@@ -92,6 +102,11 @@ public function getChildren()
     /**
      * Get a list of file paths to exclude.
      *
+     * @deprecated 3.9.0 Overload the `getDisallowedFiles()` method instead.
+     *                   The `getDisallowedFiles()` method will be made abstract and therefore required
+     *                   in v4.0 and this method will be removed.
+     *                   If both methods are implemented, the new `getDisallowedFiles()` method will take precedence.
+     *
      * @return array
      */
     abstract protected function getBlacklist();
@@ -100,9 +115,42 @@ abstract protected function getBlacklist();
     /**
      * Get a list of file paths to include.
      *
+     * @deprecated 3.9.0 Overload the `getAllowedFiles()` method instead.
+     *                   The `getAllowedFiles()` method will be made abstract and therefore required
+     *                   in v4.0 and this method will be removed.
+     *                   If both methods are implemented, the new `getAllowedFiles()` method will take precedence.
+     *
      * @return array
      */
     abstract protected function getWhitelist();
 
 
+    /**
+     * Get a list of file paths to exclude.
+     *
+     * @since 3.9.0 Replaces the deprecated `getBlacklist()` method.
+     *
+     * @return array|null
+     */
+    protected function getDisallowedFiles()
+    {
+        return null;
+
+    }//end getDisallowedFiles()
+
+
+    /**
+     * Get a list of file paths to include.
+     *
+     * @since 3.9.0 Replaces the deprecated `getWhitelist()` method.
+     *
+     * @return array|null
+     */
+    protected function getAllowedFiles()
+    {
+        return null;
+
+    }//end getAllowedFiles()
+
+
 }//end class
diff --git a/src/Filters/GitModified.php b/src/Filters/GitModified.php
@@ -18,21 +18,41 @@ class GitModified extends ExactMatch
     /**
      * Get a list of file paths to exclude.
      *
+     * @since 3.9.0
+     *
      * @return array
      */
-    protected function getBlacklist()
+    protected function getDisallowedFiles()
     {
         return [];
 
+    }//end getDisallowedFiles()
+
+
+    /**
+     * Get a list of file paths to exclude.
+     *
+     * @deprecated 3.9.0 Overload the `getDisallowedFiles()` method instead.
+     *
+     * @codeCoverageIgnore
+     *
+     * @return array
+     */
+    protected function getBlacklist()
+    {
+        return $this->getDisallowedFiles();
+
     }//end getBlacklist()
 
 
     /**
      * Get a list of file paths to include.
      *
+     * @since 3.9.0
+     *
      * @return array
      */
-    protected function getWhitelist()
+    protected function getAllowedFiles()
     {
         $modified = [];
 
@@ -59,6 +79,22 @@ protected function getWhitelist()
 
         return $modified;
 
+    }//end getAllowedFiles()
+
+
+    /**
+     * Get a list of file paths to include.
+     *
+     * @deprecated 3.9.0 Overload the `getAllowedFiles()` method instead.
+     *
+     * @codeCoverageIgnore
+     *
+     * @return array
+     */
+    protected function getWhitelist()
+    {
+        return $this->getAllowedFiles();
+
     }//end getWhitelist()
 
 

diff --git a/src/Filters/GitStaged.php b/src/Filters/GitStaged.php
@@ -20,21 +20,41 @@ class GitStaged extends ExactMatch
     /**
      * Get a list of file paths to exclude.
      *
+     * @since 3.9.0
+     *
      * @return array
      */
-    protected function getBlacklist()
+    protected function getDisallowedFiles()
     {
         return [];
 
+    }//end getDisallowedFiles()
+
+
+    /**
+     * Get a list of file paths to exclude.
+     *
+     * @deprecated 3.9.0 Overload the `getDisallowedFiles()` method instead.
+     *
+     * @codeCoverageIgnore
+     *
+     * @return array
+     */
+    protected function getBlacklist()
+    {
+        return $this->getDisallowedFiles();
+
     }//end getBlacklist()
 
 
     /**
      * Get a list of file paths to include.
      *
+     * @since 3.9.0
+     *
      * @return array
      */
-    protected function getWhitelist()
+    protected function getAllowedFiles()
     {
         $modified = [];
 
@@ -61,6 +81,22 @@ protected function getWhitelist()
 
         return $modified;
 
+    }//end getAllowedFiles()
+
+
+    /**
+     * Get a list of file paths to include.
+     *
+     * @deprecated 3.9.0 Overload the `getAllowedFiles()` method instead.
+     *
+     * @codeCoverageIgnore
+     *
+     * @return array
+     */
+    protected function getWhitelist()
+    {
+        return $this->getAllowedFiles();
+
     }//end getWhitelist()