Skip to content

Filters/ExactMatch: deprecate the getBlacklist() and getWhitelist() methods #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 25, 2024
Merged

Filters/ExactMatch: deprecate the getBlacklist() and getWhitelist() methods #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 52 additions & 4 deletions src/Filters/ExactMatch.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down Expand Up @@ -92,6 +102,11 @@ public function getChildren()
/**
* Get a list of file paths to exclude.
*
* @deprecated 3.9.0 Implement 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();
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we replace the method with a non- abstract implementation, so downstream code won't need to implement a deprecated method?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@derrabus Thanks for the feedback.

I was struggling a little with whether to do that or not, as that would mean we can no longer enforce that at least one of each of getBlacklist/getBlockedFiles and getWhitelist/getAllowedFiles is required to be implemented and making the new methods abstract would introduce a breaking change in a minor.

Only way I can think of still safeguarding it, would be to remove all four method declarations from the ExactMatch class and using method_exists() checks and throwing an exception is any of these sets don't have a corresponding method, but removing the method declarations also makes it much less obvious what the class expects and would require significantly more documentation to be added to the class.

Not sure it's worth the overhead for the (hopefully) short period until the 4.0 release, especially considering that based on a simple code search, there are no external classes extending the ExactMatch class.

What do you think ?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The abstract class could contain implementations of both methods calling each other, with a recursion detection. If a recursion is detected, you throw because in that case the downstream class hasn't implemented either of them.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@derrabus Hmm.. feels a bit like overengineering for something which isn't a real life issue anyway - see the impact analysis (same link I posted in the underlying issue)

The PHP native implements Serializable vs __serialize() conundrum also comes to mind.

Based on the code in this PR, the following situations are possible for custom Filter classes which extend ExactMatch:

  1. Do nothing, i.e. only implements the old abstract methods.
    Impact:
    • Will continue to work fine without deprecation notices in combination with any PHPCS 3.x release.
    • Will break in combination with PHPCS 4.0 or higher.
  2. Implement both the old and the new methods in whichever way they prefer (one pointing to the other or visa versa).
    Impact:
    • Will work cross-version with any PHPCS 3.x or 4.x release without notices.
    • Once support for PHPCS 3.x is dropped, the implementation of the "old" methods can be removed.
  3. Implement only the "new" methods.
    Impact:
    • Will not work in combination with PHPCS 3.x.
    • Well, that would be one package which is ready early for PHPCS 4.x ;-)

Expand All @@ -100,9 +115,42 @@ abstract protected function getBlacklist();
/**
* Get a list of file paths to include.
*
* @deprecated 3.9.0 Implement 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
40 changes: 38 additions & 2 deletions src/Filters/GitModified.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];

Expand All @@ -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()


Expand Down
40 changes: 38 additions & 2 deletions src/Filters/GitStaged.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];

Expand All @@ -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()


Expand Down