Flesh out Conduit types for Paste search fields

Summary: Ref T9964. This fills in types and descriptions for ApplicationSearch fields in Paste. Test Plan: Got this nice table now: {F1023999} Reviewers: chad Reviewed By: chad Maniphest Tasks: T9964 Differential Revision: https://secure.phabricator.com/D14765
2024-12-22 05:20:56 +01:00 · 2015-12-13 06:52:37 -08:00 · 2015-12-13 06:52:37 -08:00 · 0282ce74ab
commit 0282ce74ab
parent 1b325a0a89
17 changed files with 192 additions and 26 deletions
--- a/src/__phutil_library_map__.php
+++ b/src/__phutil_library_map__.php
@ -228,6 +228,7 @@ phutil_register_library_map(array(
    'ConduitConnectConduitAPIMethod' => 'applications/conduit/method/ConduitConnectConduitAPIMethod.php',
    'ConduitConnectionGarbageCollector' => 'applications/conduit/garbagecollector/ConduitConnectionGarbageCollector.php',
    'ConduitDeprecatedCallSetupCheck' => 'applications/conduit/check/ConduitDeprecatedCallSetupCheck.php',
+    'ConduitEpochParameterType' => 'applications/conduit/parametertype/ConduitEpochParameterType.php',
    'ConduitException' => 'applications/conduit/protocol/exception/ConduitException.php',
    'ConduitGetCapabilitiesConduitAPIMethod' => 'applications/conduit/method/ConduitGetCapabilitiesConduitAPIMethod.php',
    'ConduitGetCertificateConduitAPIMethod' => 'applications/conduit/method/ConduitGetCertificateConduitAPIMethod.php',
@ -235,8 +236,10 @@ phutil_register_library_map(array(
    'ConduitLogGarbageCollector' => 'applications/conduit/garbagecollector/ConduitLogGarbageCollector.php',
    'ConduitMethodDoesNotExistException' => 'applications/conduit/protocol/exception/ConduitMethodDoesNotExistException.php',
    'ConduitMethodNotFoundException' => 'applications/conduit/protocol/exception/ConduitMethodNotFoundException.php',
+    'ConduitPHIDListParameterType' => 'applications/conduit/parametertype/ConduitPHIDListParameterType.php',
    'ConduitParameterType' => 'applications/conduit/parametertype/ConduitParameterType.php',
    'ConduitPingConduitAPIMethod' => 'applications/conduit/method/ConduitPingConduitAPIMethod.php',
+    'ConduitProjectListParameterType' => 'applications/conduit/parametertype/ConduitProjectListParameterType.php',
    'ConduitQueryConduitAPIMethod' => 'applications/conduit/method/ConduitQueryConduitAPIMethod.php',
    'ConduitResultSearchEngineExtension' => 'applications/conduit/query/ConduitResultSearchEngineExtension.php',
    'ConduitSSHWorkflow' => 'applications/conduit/ssh/ConduitSSHWorkflow.php',
@ -4074,6 +4077,7 @@ phutil_register_library_map(array(
    'ConduitConnectConduitAPIMethod' => 'ConduitAPIMethod',
    'ConduitConnectionGarbageCollector' => 'PhabricatorGarbageCollector',
    'ConduitDeprecatedCallSetupCheck' => 'PhabricatorSetupCheck',
+    'ConduitEpochParameterType' => 'ConduitListParameterType',
    'ConduitException' => 'Exception',
    'ConduitGetCapabilitiesConduitAPIMethod' => 'ConduitAPIMethod',
    'ConduitGetCertificateConduitAPIMethod' => 'ConduitAPIMethod',
@ -4081,8 +4085,10 @@ phutil_register_library_map(array(
    'ConduitLogGarbageCollector' => 'PhabricatorGarbageCollector',
    'ConduitMethodDoesNotExistException' => 'ConduitMethodNotFoundException',
    'ConduitMethodNotFoundException' => 'ConduitException',
+    'ConduitPHIDListParameterType' => 'ConduitListParameterType',
    'ConduitParameterType' => 'Phobject',
    'ConduitPingConduitAPIMethod' => 'ConduitAPIMethod',
+    'ConduitProjectListParameterType' => 'ConduitListParameterType',
    'ConduitQueryConduitAPIMethod' => 'ConduitAPIMethod',
    'ConduitResultSearchEngineExtension' => 'PhabricatorSearchEngineExtension',
    'ConduitSSHWorkflow' => 'PhabricatorSSHWorkflow',
--- a/src/applications/conduit/parametertype/ConduitEpochParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitEpochParameterType.php
@ -0,0 +1,37 @@
+<?php
+
+final class ConduitEpochParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $value = parent::getParameterValue($request, $key);
+
+    if (!is_int($value)) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Expected integer, got something else.'));
+    }
+
+    return $value;
+  }
+
+  protected function getParameterTypeName() {
+    return 'epoch';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('Epoch timestamp, as an integer.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-PROJ-1111"]',
+      '["backend"]',
+      '["PHID-PROJ-2222", "frontend"]',
+    );
+  }
+
+}
--- a/src/applications/conduit/parametertype/ConduitListParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitListParameterType.php
@ -4,7 +4,7 @@ abstract class ConduitListParameterType
  extends ConduitParameterType {

  protected function getParameterValue(array $request, $key) {
-    $value = parent::getParameterValue();
+    $value = parent::getParameterValue($request, $key);

    if (!is_array($value)) {
      $this->raiseValidationException(
@ -30,6 +30,22 @@ abstract class ConduitListParameterType
    return $value;
  }

+  protected function validateStringList(array $request, $key, array $list) {
+    foreach ($list as $idx => $item) {
+      if (!is_string($item)) {
+        $this->raiseValidationException(
+          $request,
+          $key,
+          pht(
+            'Expected a list of strings, but item with index "%s" is '.
+            'not a string.',
+            $idx));
+      }
+    }
+
+    return $list;
+  }
+
  protected function getParameterDefault() {
    return array();
  }
--- a/src/applications/conduit/parametertype/ConduitPHIDListParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitPHIDListParameterType.php
@ -0,0 +1,27 @@
+<?php
+
+final class ConduitPHIDListParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $list = parent::getParameterValue($request, $key);
+    return $this->validateStringList($request, $key, $list);
+  }
+
+  protected function getParameterTypeName() {
+    return 'list<phid>';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('List of PHIDs.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-WXYZ-1111", "PHID-WXYZ-2222"]',
+    );
+  }
+
+}
--- a/src/applications/conduit/parametertype/ConduitProjectListParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitProjectListParameterType.php
@ -0,0 +1,34 @@
+<?php
+
+final class ConduitProjectListParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $list = parent::getParameterValue($request, $key);
+    $list = $this->validateStringList($request, $key, $list);
+    return id(new PhabricatorProjectPHIDResolver())
+      ->setViewer($this->getViewer())
+      ->resolvePHIDs($list);
+  }
+
+  protected function getParameterTypeName() {
+    return 'list<project>';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('List of project PHIDs.'),
+      pht('List of project tags.'),
+      pht('List with a mixture of PHIDs and tags.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-PROJ-1111"]',
+      '["backend"]',
+      '["PHID-PROJ-2222", "frontend"]',
+    );
+  }
+
+}
--- a/src/applications/conduit/parametertype/ConduitStringListParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitStringListParameterType.php
@ -4,21 +4,8 @@ final class ConduitStringListParameterType
  extends ConduitListParameterType {

  protected function getParameterValue(array $request, $key) {
-    $list = parent::getParameterValue();
-
-    foreach ($list as $idx => $item) {
-      if (!is_string($item)) {
-        $this->raiseValidationException(
-          $request,
-          $key,
-          pht(
-            'Expected a list of strings, but item with index "%s" is '.
-            'not a string.',
-            $idx));
-      }
-    }
-
-    return $list;
+    $list = parent::getParameterValue($request, $key);
+    return $this->validateStringList($request, $key, $list);
  }

  protected function getParameterTypeName() {
--- a/src/applications/conduit/parametertype/ConduitUserListParameterType.php
+++ b/src/applications/conduit/parametertype/ConduitUserListParameterType.php
@ -4,7 +4,8 @@ final class ConduitUserListParameterType
  extends ConduitListParameterType {

  protected function getParameterValue(array $request, $key) {
-    $list = parent::getParameterValue();
+    $list = parent::getParameterValue($request, $key);
+    $list = $this->validateStringList($request, $key, $list);
    return id(new PhabricatorUserPHIDResolver())
      ->setViewer($this->getViewer())
      ->resolvePHIDs($list);
--- a/src/applications/paste/query/PhabricatorPasteSearchEngine.php
+++ b/src/applications/paste/query/PhabricatorPasteSearchEngine.php
@ -48,19 +48,29 @@ final class PhabricatorPasteSearchEngine
        ->setAliases(array('authors'))
        ->setKey('authorPHIDs')
        ->setConduitKey('authors')
-        ->setLabel(pht('Authors')),
+        ->setLabel(pht('Authors'))
+        ->setDescription(
+          pht('Search for pastes with specific authors.')),
      id(new PhabricatorSearchStringListField())
        ->setKey('languages')
-        ->setLabel(pht('Languages')),
+        ->setLabel(pht('Languages'))
+        ->setDescription(
+          pht('Search for pastes highlighted in specific languages.')),
      id(new PhabricatorSearchDateField())
        ->setKey('createdStart')
-        ->setLabel(pht('Created After')),
+        ->setLabel(pht('Created After'))
+        ->setDescription(
+          pht('Search for pastes created after a given time.')),
      id(new PhabricatorSearchDateField())
        ->setKey('createdEnd')
-        ->setLabel(pht('Created Before')),
+        ->setLabel(pht('Created Before'))
+        ->setDescription(
+          pht('Search for pastes created before a given time.')),
      id(new PhabricatorSearchCheckboxesField())
        ->setKey('statuses')
        ->setLabel(pht('Status'))
+        ->setDescription(
+          pht('Search for archived or active pastes.'))
        ->setOptions(
          id(new PhabricatorPaste())
            ->getStatusNameMap()),
--- a/src/applications/project/engineextension/PhabricatorProjectsSearchEngineExtension.php
+++ b/src/applications/project/engineextension/PhabricatorProjectsSearchEngineExtension.php
@ -42,7 +42,9 @@ final class PhabricatorProjectsSearchEngineExtension
      ->setKey('projectPHIDs')
      ->setConduitKey('projects')
      ->setAliases(array('project', 'projects'))
-      ->setLabel(pht('Projects'));
+      ->setLabel(pht('Projects'))
+      ->setDescription(
+        pht('Search for objects associated with given projects.'));

    return $fields;
  }
--- a/src/applications/project/searchfield/PhabricatorProjectSearchField.php
+++ b/src/applications/project/searchfield/PhabricatorProjectSearchField.php
@ -47,4 +47,8 @@ final class PhabricatorProjectSearchField

  }

+  protected function newConduitParameterType() {
+    return new ConduitProjectListParameterType();
+  }
+
 }
--- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
+++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
@ -160,8 +160,7 @@ EOTEXT
      $type_object = $field->getConduitParameterType();
      if ($type_object) {
        $type = '`'.$type_object->getTypeName().'`';
-        // TODO: Support generating and surfacing this information.
-        $description = pht('TODO');
+        $description = $field->getDescription();
      } else {
        $type = '';
        $description = '//'.pht('Not Supported').'//';
--- a/src/applications/search/field/PhabricatorSearchDateField.php
+++ b/src/applications/search/field/PhabricatorSearchDateField.php
@ -38,4 +38,8 @@ final class PhabricatorSearchDateField
    return PhabricatorTime::parseLocalTime($value, $this->getViewer());
  }

+  protected function newConduitParameterType() {
+    return new ConduitEpochParameterType();
+  }
+
 }
--- a/src/applications/search/field/PhabricatorSearchField.php
+++ b/src/applications/search/field/PhabricatorSearchField.php
@ -16,6 +16,7 @@ abstract class PhabricatorSearchField extends Phobject {
  private $label;
  private $aliases = array();
  private $errors = array();
+  private $description;


 /* -(  Configuring Fields  )------------------------------------------------- */
@ -163,6 +164,30 @@ abstract class PhabricatorSearchField extends Phobject {
  }


+  /**
+   * Set a human-readable description for this field.
+   *
+   * @param string Human-readable description.
+   * @return this
+   * @task config
+   */
+  public function setDescription($description) {
+    $this->description = $description;
+    return $this;
+  }
+
+
+  /**
+   * Get this field's human-readable description.
+   *
+   * @return string|null Human-readable description.
+   * @task config
+   */
+  public function getDescription() {
+    return $this->description;
+  }
+
+
 /* -(  Handling Errors  )---------------------------------------------------- */


--- a/src/applications/search/field/PhabricatorSearchSubscribersField.php
+++ b/src/applications/search/field/PhabricatorSearchSubscribersField.php
@ -18,4 +18,10 @@ final class PhabricatorSearchSubscribersField
    return new PhabricatorMetaMTAMailableFunctionDatasource();
  }

+  protected function newConduitParameterType() {
+    // TODO: Ideally, this should eventually be a "Subscribers" type which
+    // accepts projects as well.
+    return new ConduitUserListParameterType();
+  }
+
 }
--- a/src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php
+++ b/src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php
@ -30,7 +30,9 @@ final class PhabricatorSpacesSearchEngineExtension
        ->setKey('spacePHIDs')
        ->setConduitKey('spaces')
        ->setAliases(array('space', 'spaces'))
-        ->setLabel(pht('Spaces'));
+        ->setLabel(pht('Spaces'))
+        ->setDescription(
+          pht('Search for objects in certain spaces.'));
    }

    return $fields;
--- a/src/applications/spaces/searchfield/PhabricatorSpacesSearchField.php
+++ b/src/applications/spaces/searchfield/PhabricatorSpacesSearchField.php
@ -40,4 +40,8 @@ final class PhabricatorSpacesSearchField
    return $phids;
  }

+  protected function newConduitParameterType() {
+    return new ConduitPHIDListParameterType();
+  }
+
 }
--- a/src/applications/subscriptions/engineextension/PhabricatorSubscriptionsSearchEngineExtension.php
+++ b/src/applications/subscriptions/engineextension/PhabricatorSubscriptionsSearchEngineExtension.php
@ -43,7 +43,9 @@ final class PhabricatorSubscriptionsSearchEngineExtension
      ->setLabel(pht('Subscribers'))
      ->setKey('subscriberPHIDs')
      ->setConduitKey('subscribers')
-      ->setAliases(array('subscriber', 'subscribers'));
+      ->setAliases(array('subscriber', 'subscribers'))
+      ->setDescription(
+        pht('Search for objects with certain subscribers.'));

    return $fields;
  }