Formalize custom Conduit fields on objects

Summary: Ref T9964. This just adds more structure to application fields, to make it harder to make typos and easier to validate them later.

Test Plan: Viewed APIs, called some APIs, saw good documentation and correct results.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9964

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

src/__phutil_library_map__.php

@@ -1897,6 +1897,7 @@ phutil_register_library_map(array(
     'PhabricatorConduitRequestExceptionHandler' => 'aphront/handler/PhabricatorConduitRequestExceptionHandler.php',
     'PhabricatorConduitResultInterface' => 'applications/conduit/interface/PhabricatorConduitResultInterface.php',
     'PhabricatorConduitSearchEngine' => 'applications/conduit/query/PhabricatorConduitSearchEngine.php',
+    'PhabricatorConduitSearchFieldSpecification' => 'applications/conduit/interface/PhabricatorConduitSearchFieldSpecification.php',
     'PhabricatorConduitTestCase' => '__tests__/PhabricatorConduitTestCase.php',
     'PhabricatorConduitToken' => 'applications/conduit/storage/PhabricatorConduitToken.php',
     'PhabricatorConduitTokenController' => 'applications/conduit/controller/PhabricatorConduitTokenController.php',
@@ -6014,6 +6015,7 @@ phutil_register_library_map(array(
     'PhabricatorConduitRequestExceptionHandler' => 'PhabricatorRequestExceptionHandler',
     'PhabricatorConduitResultInterface' => 'PhabricatorPHIDInterface',
     'PhabricatorConduitSearchEngine' => 'PhabricatorApplicationSearchEngine',
+    'PhabricatorConduitSearchFieldSpecification' => 'Phobject',
     'PhabricatorConduitTestCase' => 'PhabricatorTestCase',
     'PhabricatorConduitToken' => array(
       'PhabricatorConduitDAO',

src/applications/conduit/interface/PhabricatorConduitResultInterface.php

@@ -16,10 +16,10 @@ interface PhabricatorConduitResultInterface
 
   public function getFieldSpecificationsForConduit() {
     return array(
-      'name' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('name')
-        'description' => pht('The name of the object.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('The name of the object.')),
     );
   }
 

src/applications/conduit/interface/PhabricatorConduitSearchFieldSpecification.php

@@ -0,0 +1,37 @@
+<?php
+
+final class PhabricatorConduitSearchFieldSpecification
+  extends Phobject {
+
+  private $key;
+  private $type;
+  private $description;
+
+  public function setKey($key) {
+    $this->key = $key;
+    return $this;
+  }
+
+  public function getKey() {
+    return $this->key;
+  }
+
+  public function setType($type) {
+    $this->type = $type;
+    return $this;
+  }
+
+  public function getType() {
+    return $this->type;
+  }
+
+  public function setDescription($description) {
+    $this->description = $description;
+    return $this;
+  }
+
+  public function getDescription() {
+    return $this->description;
+  }
+
+}

src/applications/maniphest/storage/ManiphestTask.php

@@ -399,30 +399,30 @@ final class ManiphestTask extends ManiphestDAO
 
   public function getFieldSpecificationsForConduit() {
     return array(
-      'title' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('title')
-        'description' => pht('The name of the object.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('The title of the task.')),
-      'authorPHID' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'phid',
+        ->setKey('authorPHID')
-        'description' => pht('Original task author.'),
+        ->setType('phid')
-      ),
+        ->setDescription(pht('Original task author.')),
-      'ownerPHID' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'phid?',
+        ->setKey('ownerPHID')
-        'description' => pht('Current task owner.'),
+        ->setType('phid?')
-      ),
+        ->setDescription(pht('Current task owner, if task is assigned.')),
-      'status' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('status')
-        'description' => pht('Current task status.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('Task status.')),
-      'priority' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'int',
+        ->setKey('priority')
-        'description' => pht('Task priority.'),
+        ->setType('int')
-      ),
+        ->setDescription(pht('Task priority.')),
-      'subpriority' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'double',
+        ->setKey('subpriority')
-        'description' => pht('Order within priority level.'),
+        ->setType('double')
-      ),
+        ->setDescription(pht('Order within priority level.')),
     );
   }
 

src/applications/owners/storage/PhabricatorOwnersPackage.php

@@ -391,22 +391,22 @@ final class PhabricatorOwnersPackage
 
   public function getFieldSpecificationsForConduit() {
     return array(
-      'name' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('name')
-        'description' => pht('The name of the package.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('The name of the package.')),
-      'description' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('description')
-        'description' => pht('The package description.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('The package description.')),
-      'status' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('status')
-        'description' => pht('Active or archived status of the package.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('Active or archived status of the package.')),
-      'owners' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'list<map<string, wild>>',
+        ->setKey('owners')
-        'description' => pht('List of package owners.'),
+        ->setType('list<map<string, wild>>')
-      ),
+        ->setDescription(pht('List of package owners.')),
     );
   }
 

src/applications/paste/storage/PhabricatorPaste.php

@@ -257,22 +257,22 @@ final class PhabricatorPaste extends PhabricatorPasteDAO
 
   public function getFieldSpecificationsForConduit() {
     return array(
-      'title' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('title')
-        'description' => pht('The name of the object.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('The title of the paste.')),
-      'authorPHID' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'phid',
+        ->setKey('authorPHID')
-        'description' => pht('User PHID of the author.'),
+        ->setType('phid')
-      ),
+        ->setDescription(pht('User PHID of the author.')),
-      'language' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string?',
+        ->setKey('language')
-        'description' => pht('Language to use for syntax highlighting.'),
+        ->setType('string?')
-      ),
+        ->setDescription(pht('Language to use for syntax highlighting.')),
-      'status' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'string',
+        ->setKey('status')
-        'description' => pht('Active or archived status of the paste.'),
+        ->setType('string')
-      ),
+        ->setDescription(pht('Active or arhived status of the paste.')),
     );
   }
 

src/applications/policy/engineextension/PhabricatorPolicySearchEngineExtension.php

@@ -23,11 +23,10 @@ final class PhabricatorPolicySearchEngineExtension
 
   public function getFieldSpecificationsForConduit($object) {
     return array(
-      'policy' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'map<string, wild>',
+        ->setKey('policy')
-        'description' => pht(
+        ->setType('map<string, wild>')
-          'Map of capabilities to current policies.'),
+        ->setDescription(pht('Map of capabilities to current policies.')),
-      ),
     );
   }
 

src/applications/search/engine/PhabricatorApplicationSearchEngine.php

@@ -1129,7 +1129,7 @@ abstract class PhabricatorApplicationSearchEngine extends Phobject {
     $attachments = $this->getConduitSearchAttachments();
 
     // TODO: Validate this better.
-    $attachment_specs = $request->getValue('attachments');
+    $attachment_specs = $request->getValue('attachments', array());
     $attachments = array_select_keys(
       $attachments,
       array_keys($attachment_specs));
@@ -1203,12 +1203,23 @@ abstract class PhabricatorApplicationSearchEngine extends Phobject {
     $extensions = $this->getConduitFieldExtensions();
     $object = $this->newQuery()->newResultObject();
 
-    $specifications = array();
+    $map = array();
     foreach ($extensions as $extension) {
-      $specifications += $extension->getFieldSpecificationsForConduit($object);
+      $specifications = $extension->getFieldSpecificationsForConduit($object);
+      foreach ($specifications as $specification) {
+        $key = $specification->getKey();
+        if (isset($map[$key])) {
+          throw new Exception(
+            pht(
+              'Two field specifications share the same key ("%s"). Each '.
+              'specification must have a unique key.',
+              $key));
+        }
+        $map[$key] = $specification;
+      }
     }
 
-    return $specifications;
+    return $map;
   }
 
   private function getEngineExtensions() {

src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php

@@ -373,8 +373,8 @@ EOTEXT
 
     $rows = array();
     foreach ($specs as $key => $spec) {
-      $type = idx($spec, 'type');
+      $type = $spec->getType();
-      $description = idx($spec, 'description');
+      $description = $spec->getDescription();
       $rows[] = array(
         $key,
         $type,

src/applications/search/engineextension/PhabricatorLiskSearchEngineExtension.php

@@ -31,16 +31,16 @@ final class PhabricatorLiskSearchEngineExtension
 
   public function getFieldSpecificationsForConduit($object) {
     return array(
-      'dateCreated' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'int',
+        ->setKey('dateCreated')
-        'description' => pht(
+        ->setType('int')
-          'Epoch timestamp when the object was created.'),
+        ->setDescription(
-      ),
+          pht('Epoch timestamp when the object was created.')),
-      'dateModified' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'int',
+        ->setKey('dateModified')
-        'description' => pht(
+        ->setType('int')
-          'Epoch timestamp when the object was last updated.'),
+        ->setDescription(
-      ),
+          pht('Epoch timestamp when the object was last updated.')),
     );
   }
 

src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php

@@ -55,11 +55,11 @@ final class PhabricatorSpacesSearchEngineExtension
 
   public function getFieldSpecificationsForConduit($object) {
     return array(
-      'spacePHID' => array(
+      id(new PhabricatorConduitSearchFieldSpecification())
-        'type' => 'phid?',
+        ->setKey('spacePHID')
-        'description' => pht(
+        ->setType('phid?')
-          'PHID of the policy space this object is part of.'),
+        ->setDescription(
-      ),
+          pht('PHID of the policy space this object is part of.')),
     );
   }
 

src/infrastructure/customfield/engineextension/PhabricatorCustomFieldSearchEngineExtension.php

@@ -69,10 +69,12 @@ final class PhabricatorCustomFieldSearchEngineExtension
     $map = array();
     foreach ($fields->getFields() as $field) {
       $key = $field->getModernFieldKey();
-      $map[$key] = array(
+
-        'type' => 'wild',
+      // TODO: These should have proper types.
-        'description' => $field->getFieldDescription(),
+      $map[] = id(new PhabricatorConduitSearchFieldSpecification())
-      );
+        ->setKey($key)
+        ->setType('wild')
+        ->setDescription($field->getFieldDescription());
     }
 
     return $map;