diff --git a/src/__phutil_library_map__.php b/src/__phutil_library_map__.php index d226fdd47d..dc97c2c93c 100644 --- 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', diff --git a/src/applications/conduit/parametertype/ConduitEpochParameterType.php b/src/applications/conduit/parametertype/ConduitEpochParameterType.php new file mode 100644 index 0000000000..2c85378bb3 --- /dev/null +++ b/src/applications/conduit/parametertype/ConduitEpochParameterType.php @@ -0,0 +1,37 @@ +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"]', + ); + } + +} diff --git a/src/applications/conduit/parametertype/ConduitListParameterType.php b/src/applications/conduit/parametertype/ConduitListParameterType.php index 9dfa6f435f..10c81e8c5d 100644 --- 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(); } diff --git a/src/applications/conduit/parametertype/ConduitPHIDListParameterType.php b/src/applications/conduit/parametertype/ConduitPHIDListParameterType.php new file mode 100644 index 0000000000..60199dbe45 --- /dev/null +++ b/src/applications/conduit/parametertype/ConduitPHIDListParameterType.php @@ -0,0 +1,27 @@ +validateStringList($request, $key, $list); + } + + protected function getParameterTypeName() { + return 'list'; + } + + protected function getParameterFormatDescriptions() { + return array( + pht('List of PHIDs.'), + ); + } + + protected function getParameterExamples() { + return array( + '["PHID-WXYZ-1111", "PHID-WXYZ-2222"]', + ); + } + +} diff --git a/src/applications/conduit/parametertype/ConduitProjectListParameterType.php b/src/applications/conduit/parametertype/ConduitProjectListParameterType.php new file mode 100644 index 0000000000..c26db7febf --- /dev/null +++ b/src/applications/conduit/parametertype/ConduitProjectListParameterType.php @@ -0,0 +1,34 @@ +validateStringList($request, $key, $list); + return id(new PhabricatorProjectPHIDResolver()) + ->setViewer($this->getViewer()) + ->resolvePHIDs($list); + } + + protected function getParameterTypeName() { + return 'list'; + } + + 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"]', + ); + } + +} diff --git a/src/applications/conduit/parametertype/ConduitStringListParameterType.php b/src/applications/conduit/parametertype/ConduitStringListParameterType.php index b551ed0ca8..664a1ded99 100644 --- 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() { diff --git a/src/applications/conduit/parametertype/ConduitUserListParameterType.php b/src/applications/conduit/parametertype/ConduitUserListParameterType.php index ee1c5f7aa5..ad6555146d 100644 --- 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); diff --git a/src/applications/paste/query/PhabricatorPasteSearchEngine.php b/src/applications/paste/query/PhabricatorPasteSearchEngine.php index 8e64f337ce..38aaface64 100644 --- 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()), diff --git a/src/applications/project/engineextension/PhabricatorProjectsSearchEngineExtension.php b/src/applications/project/engineextension/PhabricatorProjectsSearchEngineExtension.php index 4db5fd7090..298e0d0775 100644 --- 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; } diff --git a/src/applications/project/searchfield/PhabricatorProjectSearchField.php b/src/applications/project/searchfield/PhabricatorProjectSearchField.php index c3d230653c..f187444e5d 100644 --- 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(); + } + } diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php index 4214e93090..66da79e28a 100644 --- 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').'//'; diff --git a/src/applications/search/field/PhabricatorSearchDateField.php b/src/applications/search/field/PhabricatorSearchDateField.php index c67c7178cc..84b7e2580a 100644 --- 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(); + } + } diff --git a/src/applications/search/field/PhabricatorSearchField.php b/src/applications/search/field/PhabricatorSearchField.php index 6d22cfbcb6..380b574f17 100644 --- 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 )---------------------------------------------------- */ diff --git a/src/applications/search/field/PhabricatorSearchSubscribersField.php b/src/applications/search/field/PhabricatorSearchSubscribersField.php index 6a0e82b85b..7102f33910 100644 --- 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(); + } + } diff --git a/src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php b/src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php index 629570f863..99d01d63c3 100644 --- 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; diff --git a/src/applications/spaces/searchfield/PhabricatorSpacesSearchField.php b/src/applications/spaces/searchfield/PhabricatorSpacesSearchField.php index 751178d498..526103a0c2 100644 --- 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(); + } + } diff --git a/src/applications/subscriptions/engineextension/PhabricatorSubscriptionsSearchEngineExtension.php b/src/applications/subscriptions/engineextension/PhabricatorSubscriptionsSearchEngineExtension.php index 0cd9a7a68c..ccd2e65dff 100644 --- 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; }