fix: skip return check for known action hooks

WordPress's `add_action()` is a wrapper around `add_filter()`, so some
developers use `add_filter()` to register callbacks for action hooks
like `pre_get_posts`. The sniff was incorrectly demanding a return value
from these callbacks, even though action hooks pass arguments by
reference and have no use for a return value.

A configurable `$knownActionHooks` property allows the sniff to
recognise common WordPress core action hooks and skip the return check.
Being public, users can extend the list via their ruleset for custom
action hooks.

Refs #394.

Author: GaryJones

WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php

@@ -20,6 +20,26 @@
  */
 class AlwaysReturnInFilterSniff extends Sniff {
 
+	/**
+	 * Known action hooks that are sometimes registered via `add_filter()`.
+	 *
+	 * Since `add_action()` is a wrapper around `add_filter()` in WordPress,
+	 * some developers use `add_filter()` to register callbacks for action hooks.
+	 * These callbacks are not expected to return a value.
+	 *
+	 * This property is public so it can be extended via a custom ruleset.
+	 *
+	 * @var string[]
+	 */
+	public $knownActionHooks = [
+		'pre_get_posts',
+		'parse_query',
+		'pre_get_users',
+		'pre_get_terms',
+		'pre_get_comments',
+		'pre_get_sites',
+	];
+
 	/**
 	 * Filter name pointer.
 	 *
@@ -65,6 +85,13 @@ public function process_token( $stackPtr ) {
 			return;
 		}
 
+		$filterName = TextStrings::stripQuotes( $this->tokens[ $this->filterNamePtr ]['content'] );
+
+		if ( in_array( $filterName, $this->knownActionHooks, true ) ) {
+			// This is a known action hook, not a filter. No return value expected.
+			return;
+		}
+
 		$callbackPtr = $this->phpcsFile->findNext(
 			array_merge( Tokens::$emptyTokens, [ T_COMMA ] ),
 			$this->filterNamePtr + 1,

WordPressVIPMinimum/Tests/Hooks/AlwaysReturnInFilterUnitTest.inc

@@ -197,6 +197,24 @@ add_filter( 'bad_void_return_with_space', function() { // Error.
 	return ;
 } );
 
+// Known action hooks registered via add_filter should not trigger. Ok.
+add_filter( 'pre_get_posts', function( $query ) {
+	$query->set( 'post_type', 'page' );
+} );
+
+add_filter( 'pre_get_posts', 'modify_query' );
+function modify_query( $query ) {
+	$query->set( 'posts_per_page', 10 );
+}
+
+add_filter( 'parse_query', function( $query ) {
+	$query->set( 'orderby', 'title' );
+} );
+
+add_filter( 'pre_get_users', function( $query ) {
+	$query->set( 'role', 'editor' );
+} );
+
 // Intentional parse error. This has to be the last test in the file!
 class parse_error_test {
 	public function __construct() {