Query sites through WP_Site_Query in wp site list

README.md

@@ -5342,7 +5342,7 @@ These fields are optionally available:
 Lists all sites in a multisite installation.
 
 ~~~
-wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_user=<value>] [--site-path=<path>] [--blog_id=<blog_id>] [--site_id=<site_id>] [--domain=<domain>] [--registered=<yyyy-mm-dd-hh-ii-ss>] [--last_updated=<yyyy-mm-dd-hh-ii-ss>] [--public=<public>] [--archived=<archived>] [--mature=<mature>] [--spam=<spam>] [--deleted=<deleted>] [--lang_id=<lang_id>] [--field=<field>] [--fields=<fields>] [--format=<format>]
+wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_user=<value>] [--site-path=<path>] [--blog_id=<blog_id>] [--site_id=<site_id>] [--domain=<domain>] [--registered=<date>] [--last_updated=<date>] [--public=<public>] [--archived=<archived>] [--mature=<mature>] [--spam=<spam>] [--deleted=<deleted>] [--lang_id=<lang_id>] [--field=<field>] [--fields=<fields>] [--format=<format>]
 ~~~
 
 **OPTIONS**
@@ -5351,8 +5351,10 @@ wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_u
 		The network to which the sites belong.
 
 	[--<field>=<value>]
-		Filter by one or more fields (see "Available Fields" section). However,
-		'url' isn't an available filter, as it comes from 'home' in wp_options.
+		Filter by one or more fields (see "Available Fields" section), or pass any
+		other argument accepted by WP_Site_Query, such as 'search', 'site__not_in',
+		'number', 'offset', 'orderby' or 'order'. However, 'url' isn't an available
+		filter, as it comes from 'home' in wp_options.
 		Note: '--path' conflicts with the global parameter of the same name; use
 		'--site-path' to filter by path instead.
 
@@ -5375,11 +5377,13 @@ wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_u
 	[--domain=<domain>]
 		Filter by domain.
 
-	[--registered=<yyyy-mm-dd-hh-ii-ss>]
-		Filter by the date the site was registered.
+	[--registered=<date>]
+		Filter by the date the site was registered. Accepts a timestamp or a
+		date; a value carrying no time of day matches that whole day.
 
-	[--last_updated=<yyyy-mm-dd-hh-ii-ss>]
-		Filter by the date the site was last updated.
+	[--last_updated=<date>]
+		Filter by the date the site was last updated. Accepts a timestamp or a
+		date; a value carrying no time of day matches that whole day.
 
 	[--public=<public>]
 		Filter by whether the site is public. Accepts 1 or 0.
@@ -5446,6 +5450,15 @@ These fields are optionally available:
     http://www.example.com/
     http://www.example.com/subdir/
 
+    # Output site URLs, most recently registered first
+    $ wp site list --orderby=registered --order=desc --field=url
+    http://www.example.com/subdir/
+    http://www.example.com/
+
+    # Search for sites by domain or path
+    $ wp site list --search=subdir --field=url
+    http://www.example.com/subdir/
+
 
 
 ### wp site mature

features/site.feature

@@ -1041,3 +1041,178 @@ Feature: Manage sites in a multisite installation
       """
       3
       """
+
+  Scenario: List sites using WP_Site_Query arguments
+    Given a WP multisite install
+
+    When I run `wp site create --slug=alpha --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {ALPHA_ID}
+
+    When I run `wp site create --slug=beta --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {BETA_ID}
+
+    # --search, --site__not_in, --number, --offset and --orderby all come from
+    # WP_Site_Query and were silently ignored before.
+    When I run `wp site list --search=alpha --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --site__not_in={ALPHA_ID} --format=count`
+    Then STDOUT should be:
+      """
+      2
+      """
+
+    When I run `wp site list --number=1 --format=count`
+    Then STDOUT should be:
+      """
+      1
+      """
+
+    When I run `wp site list --number=1 --offset=1 --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --orderby=id --order=desc --field=blog_id`
+    Then STDOUT should be:
+      """
+      {BETA_ID}
+      {ALPHA_ID}
+      1
+      """
+
+  Scenario: Existing site list filters keep working against WP_Site_Query
+    Given a WP multisite install
+
+    When I run `wp site create --slug=alpha --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {ALPHA_ID}
+
+    When I run `wp site create --slug=beta --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {BETA_ID}
+
+    # --site__in returns rows in the order the IDs were given.
+    When I run `wp site list --site__in={BETA_ID},{ALPHA_ID} --field=blog_id`
+    Then STDOUT should be:
+      """
+      {BETA_ID}
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --blog_id={ALPHA_ID} --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --site_id=1 --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp site list --site_id=2 --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp site list --site-path=/alpha/ --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    # admin belongs to every site, bobby only to the one they were created on, so the
+    # two counts differ and neither can pass by accident.
+    When I run `wp site list --site_user=admin --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp user create bobby bobby@example.com --role=author --porcelain`
+    Then STDOUT should be a number
+
+    When I run `wp site list --site_user=bobby --field=blog_id`
+    Then STDOUT should be:
+      """
+      1
+      """
+
+    # --site__in and --site_user narrow each other rather than one replacing the
+    # other, so the pair keeps only the sites satisfying both.
+    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
+      """
+
+  Scenario: Filter the site list by registration or update date
+    Given a WP multisite install
+
+    When I run `wp site create --slug=alpha --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {ALPHA_ID}
+
+    When I run `wp site list --blog_id={ALPHA_ID} --field=registered`
+    Then STDOUT should not be empty
+    And save STDOUT as {REGISTERED}
+    And save STDOUT '(\d{4}-\d{2}-\d{2})' as {REGISTERED_DAY}
+
+    When I run `wp site list --registered='{REGISTERED}' --field=blog_id`
+    Then STDOUT should contain:
+      """
+      {ALPHA_ID}
+      """
+
+    # A value carrying no time of day matches every site registered that day, and
+    # only those - a day nothing was registered on comes back empty.
+    When I run `wp site list --registered={REGISTERED_DAY} --field=blog_id`
+    Then STDOUT should contain:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --registered=1999-01-01 --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp site list --registered='1999-01-01 00:00:00' --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp site list --blog_id={ALPHA_ID} --field=last_updated`
+    Then STDOUT should not be empty
+    And save STDOUT as {LAST_UPDATED}
+
+    When I run `wp site list --last_updated='{LAST_UPDATED}' --field=blog_id`
+    Then STDOUT should contain:
+      """
+      {ALPHA_ID}
+      """
+
+    # Interpreting the value is left to WP_Date_Query, which resolves anything it
+    # cannot parse to a date no site can have registered on.
+    When I run `wp site list --registered=notadate --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """