✨ Allow to specify custom site query for --all-sites flag

Author: Guido W. Pettinari

phpstan.neon

@@ -1,13 +1,13 @@
 # Make sure to use https://github.com/php-stubs/wp-cli-stubs
 
 parameters:
-  level: 8
-  paths:
-    - src
-  scanFiles:
-    - %rootDir%/../../php-stubs/wordpress-stubs/wordpress-stubs.php
-    - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-stubs.php
-    - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-commands-stubs.php
-    - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-i18n-stubs.php
-  ignoreErrors:
-    - '~^Parameter #2 \$callable of static method WP_CLI::add_command\(\) expects callable\(\): mixed, .+ given\.$~'
+    level: 8
+    paths:
+        - src
+    scanFiles:
+        - %rootDir%/../../php-stubs/wordpress-stubs/wordpress-stubs.php
+        - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-stubs.php
+        - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-commands-stubs.php
+        - %rootDir%/../../php-stubs/wp-cli-stubs/wp-cli-i18n-stubs.php
+    ignoreErrors:
+        - '~^Parameter #2 \$callable of static method WP_CLI::add_command\(\) expects callable\(\): mixed, .+ given\.$~'

src/Command.php

@@ -38,8 +38,19 @@ abstract class Command
      */
     protected static bool $allow_all_sites_flag = false;
 
+    /**
+     * The site query for those commands that allow the --all-sites flag
+     *
+     * @see https://developer.wordpress.org/reference/functions/get_sites/
+     * 
+     * @var array<string,mixed>
+     */
+    protected static array $site_query = ['deleted' => 0, 'number' => PHP_INT_MAX];
+
     /**
      * Synopsis of the command
+     *
+     * @var array<int,array<string|mixed>>
      */
     protected static array $synopsis = [];
 
@@ -55,10 +66,19 @@ abstract class Command
 
     /**
      * All subclasses must have an invoke method that handles the command
+     *
+     * @param array<mixed> $args
+     * @param array<string,mixed> $assoc_args
      */
-    abstract protected static function invoke( array $args, array $assoc_args );
+    abstract protected static function invoke( array $args, array $assoc_args ): void;
 
-    public function __invoke( array $args, array $assoc_args )
+    /**
+     * Actual handler of the command
+     *
+     * @param array<mixed> $args
+     * @param array<string,mixed> $assoc_args
+     */
+    public function __invoke( array $args, array $assoc_args ): void
     {
         if ( ! is_multisite() ) {
             static::invoke( $args, $assoc_args );
@@ -69,8 +89,11 @@ public function __invoke( array $args, array $assoc_args )
 
     /**
      * Handle the command for multisite installations
+     *
+     * @param array<mixed> $args
+     * @param array<string,mixed> $assoc_args
      */
-    public static function invoke_multisite( array $args, array $assoc_args )
+    public static function invoke_multisite( array $args, array $assoc_args ): void
     {
         $all_sites_flag = Utils::get_flag_value( $assoc_args, 'all-sites' );
 
@@ -81,7 +104,7 @@ public static function invoke_multisite( array $args, array $assoc_args )
 
         // If the --all-sites flag is set then run the handler on all sites.
         if ( $all_sites_flag ) {
-            Utils::run_on_all_sites( [ static::class, 'invoke' ], $args, $assoc_args );
+            Utils::run_on_all_sites( [ static::class, 'invoke' ], $args, $assoc_args, static::$site_query );
         } else {
             // Run the handler on the current site.
             static::invoke( $args, $assoc_args );
@@ -238,7 +261,7 @@ public static function _after_invoke(): void
     /**
      * Get the command synopsis
      *
-     * @return array[]
+     * @return array<int,array<string|mixed>>
      */
     public static function get_synopsis(): array
     {   

src/Utils.php

@@ -1,6 +1,8 @@
 <?php
 namespace Idearia\WP_CLI;
 
+use WP_CLI;
+
 abstract class Utils
 {
     /**
@@ -23,9 +25,9 @@ public static function is_cli_running(): bool
      * @access public
      * @category Input
      *
-     * @param array  $assoc_args Arguments array.
-     * @param string $flag       Flag to get the value.
-     * @param mixed  $default    Default value for the flag. Default: NULL.
+     * @param array<string,mixed> $assoc_args Arguments array.
+     * @param string $flag Flag to get the value.
+     * @param mixed $default Default value for the flag. Default: NULL.
      * @return mixed
      */
     public static function get_flag_value( array $assoc_args, string $flag, mixed $default = null )
@@ -39,15 +41,24 @@ public static function get_flag_value( array $assoc_args, string $flag, mixed $d
      * The callback must take two array arguments: $args and $assoc_args.
      *
      * @param callable $callback
-     * @param array $args
-     * @param array $assoc_args
+     * @param array<mixed> $args
+     * @param array<string,mixed> $assoc_args
+     * @param array<string,mixed> $site_query Optional. Query arguments for get_sites(). Default: ['deleted' => 0, 'number' => PHP_INT_MAX]
      */
-    public static function run_on_all_sites( callable $callback, array $args, array $assoc_args ) : void
+    public static function run_on_all_sites(
+        callable $callback,
+        array $args,
+        array $assoc_args,
+        array $site_query = ['deleted' => 0, 'number' => PHP_INT_MAX]
+    ) : void
     {
         // Get all active sites.
-        $sites = get_sites( array(
-            'deleted'  => 0,
-        ) );
+        $sites = get_sites( $site_query );
+
+        if ( is_int( $sites ) ) {
+            WP_CLI::error( "Wrong site query. Did you pass 'count' as a query var?" );
+            die(); // Just in case.
+        }
 
         // Loop through all sites.
         foreach ( $sites as $site ) {