Query sites through WP_Site_Query in wp site list

[swissspidy]

Draft, because this changes how a widely used command reaches the database.

Came out of #638: site list was the odd one out among the list commands, and the reason turned out to be that it never used WP_Site_Query at all.

What it did

It read $wpdb->blogs directly through a chunked table iterator, with a WHERE clause assembled from a hardcoded column list. Consequences:

• Every WP_Site_Query argument beyond those columns was silently ignored — search, site__not_in, network__in, lang__in, domain__in, date_query, orderby, number, offset, meta queries.
• pre_get_sites and the other query filters never ran, so a plugin controlling which sites are visible had no effect here.
• Results were uncached.

This builds a WP_Site_Query argument set instead and hands it everything the command does not consume itself, so those arguments work now:

$ wp site list --search=alpha --field=blog_id
$ wp site list --site__not_in=2 --format=count
$ wp site list --number=1 --offset=1 --field=blog_id
$ wp site list --orderby=id --order=desc --field=blog_id

Behaviour that is deliberately preserved

This command's own argument names. --blog_id, --site__in, --site_id, --network, --site-path and --site_user are mapped onto their WP_Site_Query equivalents. --network still takes precedence over --site_id, and listing by explicit IDs still returns them in the order given (orderby => site__in).

Paging, for two separate reasons. WP_Site_Query::$number defaults to 100, so a plain get_sites() call would silently truncate a network to its first hundred sites — a data-correctness bug, not a performance one. Paging 500 at a time also preserves the memory profile of the chunked iterator this replaces. An explicit --number is the caller's own limit and is passed straight through without paging.

count is withheld from the query arguments, since it makes get_sites() return an integer rather than a list, and --format=count is how this command spells that.

Rows are still plain objects carrying the blogs columns plus url, so --fields, --field and the formatters are unaffected.

Dates

--registered and --last_updated have no direct WP_Site_Query equivalent, so they become a date_query clause bounded by the given value on both ends (before and after with inclusive). Interpreting the value is left to WP_Date_Query, which means:

• A full timestamp matches that second, exactly as before.
• A value carrying no time of day — 2026, 2026-08, 2026-08-17 — matches that whole year, month or day.
• The SQL is a pair of plain comparisons rather than a component-wise YEAR()/MONTH()/DATE_FORMAT() match, so it works on SQLite as well. Nothing in this PR is skipped on any backend.
• A value WordPress cannot parse resolves to a date no site can carry, so the list comes back empty rather than erroring.

Since #638 landed, these two also have option entries of their own rather than being described inside the --<field>=<value> blurb. The <yyyy-mm-dd-hh-ii-ss> placeholder they arrived with implied a full timestamp was required, which is no longer true, so they take <date>.

Testing

Three scenarios added: the newly available WP_Site_Query arguments; the existing filters still behaving — including --site__in ordering, --site_user, and the two of them intersecting rather than one replacing the other; and the date filters.

Run with the same tag filtering CI applies, on the merge of main (#636, #638 and the README regeneration are all in the base now). Nothing is skipped on either backend, so the two runs cover the same 38 scenarios:

Backend	Result
MariaDB 10.11	38 scenarios, 498 steps, all passed
SQLite 3.45	38 scenarios, 498 steps, all passed

Widened to every feature that exercises wp site list — site, site-generate, site-empty, site-create, signup — and diffed the failures against origin/main with src/ and features/ checked out at the base:

origin/main : 4 failures   (Empty a site, Empty a site and its uploads directory,
                            Create new site with custom $super_admins global,
                            Respect defined $base in wp-config)
this branch : the same 4
NEW: none    FIXED: none

Those four are pre-existing and unrelated.

The --site_user plus --site__in coverage was checked against the regression it is meant to catch: replacing the array_intersect in list_() with a plain overwrite makes it fail, while the 24 steps ahead of it in the scenario still pass.

PHPCS clean. PHPStan reports no new errors against origin/main — the same total on both sides, and the two findings in Site_Command.php are present on both. The dynamic argument array cannot be narrowed to the shape get_sites() documents, since it is whatever the user passed and WP_Site_Query validates it itself, so those two calls carry an argument.type ignore.

🤖 Generated with Claude Code

https://claude.ai/code/session_014SSZzqMJRDTiLiDxQEPYcL

Summary by CodeRabbit

• New Features

  • Enhanced wp site list with broader filtering and ordering options, including search, exclusions, network, path, user, and registration or last-updated date filters.
  • Added support for pagination, result counts, and preserving explicitly requested site order.
  • Improved handling of combined filters and date-only matching.

• Documentation

  • Expanded command usage guidance with supported filters, date syntax, and practical examples.

• Tests

  • Added comprehensive coverage for filtering, pagination, ordering, counts, and invalid or nonmatching dates.

[codecov]

Codecov Report

❌ Patch coverage is 98.27586% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Site_Command.php	98.27%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[swissspidy]

On the out-of-diff note asking for --site_user combined with --site__in — added in b5ea101, in both directions so the new assertion cannot pass vacuously either:

When I run `wp site list --site__in={ALPHA_ID} --site_user=bobby --format=count`
Then STDOUT should be:
  """
  0
  """

When I run `wp site list --site__in=1,{ALPHA_ID} --site_user=bobby --field=blog_id`
Then STDOUT should be:
  """
  1
  """

The first pins the exclusion described; the second pins that the intersection still keeps what it should, since a change making --site__in plus --site_user always return nothing would satisfy the first step on its own.

Verified the pair catches the regression it is meant to. Replacing the intersection in list_() with a plain overwrite:

if ( isset( $query_args['site__in'] ) ) {
	$user_ids = array_intersect( array_map( 'intval', $query_args['site__in'] ), $user_ids );
}

makes the first new step fail with 1 instead of 0 — while the 24 steps ahead of it in the scenario still pass, which is exactly the gap identified.

---

Generated by Claude Code