Add a modern user.search Conduit API method

Summary: Ref T10512. This is fairly bare-bones but appears to work.

Test Plan: Queried all users, queried some stuff by constraints.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T10512

Differential Revision: https://secure.phabricator.com/D15959

src/__phutil_library_map__.php

@@ -4135,6 +4135,7 @@ phutil_register_library_map(array(
     'UserEnableConduitAPIMethod' => 'applications/people/conduit/UserEnableConduitAPIMethod.php',
     'UserFindConduitAPIMethod' => 'applications/people/conduit/UserFindConduitAPIMethod.php',
     'UserQueryConduitAPIMethod' => 'applications/people/conduit/UserQueryConduitAPIMethod.php',
+    'UserSearchConduitAPIMethod' => 'applications/people/conduit/UserSearchConduitAPIMethod.php',
     'UserWhoAmIConduitAPIMethod' => 'applications/people/conduit/UserWhoAmIConduitAPIMethod.php',
   ),
   'function' => array(
@@ -8313,6 +8314,7 @@ phutil_register_library_map(array(
       'PhabricatorFlaggableInterface',
       'PhabricatorApplicationTransactionInterface',
       'PhabricatorFulltextInterface',
+      'PhabricatorConduitResultInterface',
     ),
     'PhabricatorUserBlurbField' => 'PhabricatorUserCustomField',
     'PhabricatorUserCardView' => 'AphrontTagView',
@@ -9028,6 +9030,7 @@ phutil_register_library_map(array(
     'UserEnableConduitAPIMethod' => 'UserConduitAPIMethod',
     'UserFindConduitAPIMethod' => 'UserConduitAPIMethod',
     'UserQueryConduitAPIMethod' => 'UserConduitAPIMethod',
+    'UserSearchConduitAPIMethod' => 'PhabricatorSearchEngineAPIMethod',
     'UserWhoAmIConduitAPIMethod' => 'UserConduitAPIMethod',
   ),
 ));

src/applications/people/conduit/UserSearchConduitAPIMethod.php

@@ -0,0 +1,18 @@
+<?php
+
+final class UserSearchConduitAPIMethod
+  extends PhabricatorSearchEngineAPIMethod {
+
+  public function getAPIMethodName() {
+    return 'user.search';
+  }
+
+  public function newSearchEngine() {
+    return new PhabricatorPeopleSearchEngine();
+  }
+
+  public function getMethodSummary() {
+    return pht('Read information about users.');
+  }
+
+}

src/applications/people/query/PhabricatorPeopleSearchEngine.php

@@ -22,51 +22,79 @@ final class PhabricatorPeopleSearchEngine
       id(new PhabricatorSearchStringListField())
         ->setLabel(pht('Usernames'))
         ->setKey('usernames')
-        ->setAliases(array('username')),
+        ->setAliases(array('username'))
+        ->setDescription(pht('Find users by exact username.')),
       id(new PhabricatorSearchTextField())
         ->setLabel(pht('Name Contains'))
-        ->setKey('nameLike'),
+        ->setKey('nameLike')
+        ->setDescription(
+          pht('Find users whose usernames contain a substring.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Administrators'))
         ->setKey('isAdmin')
         ->setOptions(
           pht('(Show All)'),
           pht('Show Only Administrators'),
-          pht('Hide Administrators')),
+          pht('Hide Administrators'))
+        ->setDescription(
+          pht(
+            'Pass true to find only administrators, or false to omit '.
+            'administrators.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Disabled'))
         ->setKey('isDisabled')
         ->setOptions(
           pht('(Show All)'),
           pht('Show Only Disabled Users'),
-          pht('Hide Disabled Users')),
+          pht('Hide Disabled Users'))
+        ->setDescription(
+          pht(
+            'Pass true to find only disabled users, or false to omit '.
+            'disabled users.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Bots'))
-        ->setKey('isSystemAgent')
+        ->setKey('isBot')
+        ->setAliases(array('isSystemAgent'))
         ->setOptions(
           pht('(Show All)'),
           pht('Show Only Bots'),
-          pht('Hide Bots')),
+          pht('Hide Bots'))
+        ->setDescription(
+          pht(
+            'Pass true to find only bots, or false to omit bots.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Mailing Lists'))
         ->setKey('isMailingList')
         ->setOptions(
           pht('(Show All)'),
           pht('Show Only Mailing Lists'),
-          pht('Hide Mailing Lists')),
+          pht('Hide Mailing Lists'))
+        ->setDescription(
+          pht(
+            'Pass true to find only mailing lists, or false to omit '.
+            'mailing lists.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Needs Approval'))
         ->setKey('needsApproval')
         ->setOptions(
           pht('(Show All)'),
           pht('Show Only Unapproved Users'),
-          pht('Hide Unappproved Users')),
+          pht('Hide Unappproved Users'))
+        ->setDescription(
+          pht(
+            'Pass true to find only users awaiting administrative approval, '.
+            'or false to omit these users.')),
       id(new PhabricatorSearchDateField())
         ->setKey('createdStart')
-        ->setLabel(pht('Joined After')),
+        ->setLabel(pht('Joined After'))
+        ->setDescription(
+          pht('Find user accounts created after a given time.')),
       id(new PhabricatorSearchDateField())
         ->setKey('createdEnd')
-        ->setLabel(pht('Joined Before')),
+        ->setLabel(pht('Joined Before'))
+        ->setDescription(
+          pht('Find user accounts created before a given time.')),
+
     );
   }
 
@@ -115,8 +143,8 @@ final class PhabricatorPeopleSearchEngine
       $query->withIsMailingList($map['isMailingList']);
     }
 
-    if ($map['isSystemAgent'] !== null) {
-      $query->withIsSystemAgent($map['isSystemAgent']);
+    if ($map['isBot'] !== null) {
+      $query->withIsSystemAgent($map['isBot']);
     }
 
     if ($map['needsApproval'] !== null) {

src/applications/people/storage/PhabricatorUser.php

@@ -16,7 +16,8 @@ final class PhabricatorUser
     PhabricatorSSHPublicKeyInterface,
     PhabricatorFlaggableInterface,
     PhabricatorApplicationTransactionInterface,
-    PhabricatorFulltextInterface {
+    PhabricatorFulltextInterface,
+    PhabricatorConduitResultInterface {
 
   const SESSION_TABLE = 'phabricator_session';
   const NAMETOKEN_TABLE = 'user_nametoken';
@@ -1389,4 +1390,68 @@ final class PhabricatorUser
     return new PhabricatorUserFulltextEngine();
   }
 
+
+/* -(  PhabricatorConduitResultInterface  )---------------------------------- */
+
+
+  public function getFieldSpecificationsForConduit() {
+    return array(
+      id(new PhabricatorConduitSearchFieldSpecification())
+        ->setKey('username')
+        ->setType('string')
+        ->setDescription(pht("The user's username.")),
+      id(new PhabricatorConduitSearchFieldSpecification())
+        ->setKey('realName')
+        ->setType('string')
+        ->setDescription(pht("The user's real name.")),
+      id(new PhabricatorConduitSearchFieldSpecification())
+        ->setKey('roles')
+        ->setType('list<string>')
+        ->setDescription(pht('List of acccount roles.')),
+    );
+  }
+
+  public function getFieldValuesForConduit() {
+    $roles = array();
+
+    if ($this->getIsDisabled()) {
+      $roles[] = 'disabled';
+    }
+
+    if ($this->getIsSystemAgent()) {
+      $roles[] = 'bot';
+    }
+
+    if ($this->getIsMailingList()) {
+      $roles[] = 'list';
+    }
+
+    if ($this->getIsAdmin()) {
+      $roles[] = 'admin';
+    }
+
+    if ($this->getIsEmailVerified()) {
+      $roles[] = 'verified';
+    }
+
+    if ($this->getIsApproved()) {
+      $roles[] = 'approved';
+    }
+
+    if ($this->isUserActivated()) {
+      $roles[] = 'activated';
+    }
+
+    return array(
+      'username' => $this->getUsername(),
+      'realName' => $this->getRealName(),
+      'roles' => $roles,
+    );
+  }
+
+  public function getConduitSearchAttachments() {
+    return array();
+  }
+
+
 }

src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php

@@ -501,6 +501,7 @@ EOTEXT
     }
 
     $table = id(new AphrontTableView($rows))
+      ->setNoDataString(pht('This call does not support any attachments.'))
       ->setHeaders(
         array(
           pht('Key'),

src/applications/search/field/PhabricatorSearchThreeStateField.php

@@ -45,4 +45,8 @@ final class PhabricatorSearchThreeStateField
     return null;
   }
 
+  protected function newConduitParameterType() {
+    return new ConduitBoolParameterType();
+  }
+
 }