src/applications/harbormaster/conduit/HarbormasterCreateArtifactConduitAPIMethod.php

   1 <?php
   2
   3 final class HarbormasterCreateArtifactConduitAPIMethod
   4   extends HarbormasterConduitAPIMethod {
   5
   6   public function getAPIMethodName() {
   7     return 'harbormaster.createartifact';
   8   }
   9
  10   public function getMethodSummary() {
  11     return pht('Create a build artifact.');
  12   }
  13
  14   public function getMethodDescription() {
  15     $types = HarbormasterArtifact::getAllArtifactTypes();
  16     $types = msort($types, 'getArtifactTypeName');
  17
  18     $head_key = pht('Key');
  19     $head_type = pht('Type');
  20     $head_desc = pht('Description');
  21     $head_atype = pht('Artifact Type');
  22     $head_name = pht('Name');
  23     $head_summary = pht('Summary');
  24
  25     $out = array();
  26     $out[] = pht(
  27       'Use this method to attach artifacts to build targets while running '.
  28       'builds. Artifacts can be used to carry data through a complex build '.
  29       'workflow, provide extra information to users, or store build results.');
  30     $out[] = null;
  31     $out[] = pht(
  32       'When creating an artifact, you will choose an `artifactType` from '.
  33       'this table. These types of artifacts are supported:');
  34
  35     $out[] = "| {$head_atype} | {$head_name} | {$head_summary} |";
  36     $out[] = '|-------------|--------------|--------------|';
  37     foreach ($types as $type) {
  38       $type_name = $type->getArtifactTypeName();
  39       $type_const = $type->getArtifactConstant();
  40       $type_summary = $type->getArtifactTypeSummary();
  41       $out[] = "| `{$type_const}` | **{$type_name}** | {$type_summary} |";
  42     }
  43
  44     $out[] = null;
  45     $out[] = pht(
  46       'Each artifact also needs an `artifactKey`, which names the artifact. '.
  47       'Finally, you will provide some `artifactData` to fill in the content '.
  48       'of the artifact. The data you provide depends on what type of artifact '.
  49       'you are creating.');
  50
  51     foreach ($types as $type) {
  52       $type_name = $type->getArtifactTypeName();
  53       $type_const = $type->getArtifactConstant();
  54
  55       $out[] = $type_name;
  56       $out[] = '--------------------------';
  57       $out[] = null;
  58       $out[] = $type->getArtifactTypeDescription();
  59       $out[] = null;
  60       $out[] = pht(
  61         'Create an artifact of this type by passing `%s` as the '.
  62         '`artifactType`. When creating an artifact of this type, provide '.
  63         'these parameters as a dictionary to `artifactData`:',
  64         $type_const);
  65
  66       $spec = $type->getArtifactParameterSpecification();
  67       $desc = $type->getArtifactParameterDescriptions();
  68       $out[] = "| {$head_key} | {$head_type} | {$head_desc} |";
  69       $out[] = '|-------------|--------------|--------------|';
  70       foreach ($spec as $key => $key_type) {
  71         $key_desc = idx($desc, $key);
  72         $out[] = "| `{$key}` | //{$key_type}// | {$key_desc} |";
  73       }
  74
  75       $example = $type->getArtifactDataExample();
  76       if ($example !== null) {
  77         $json = new PhutilJSON();
  78         $rendered = $json->encodeFormatted($example);
  79
  80         $out[] = pht('For example:');
  81         $out[] = '```lang=json';
  82         $out[] = $rendered;
  83         $out[] = '```';
  84       }
  85     }
  86
  87     return implode("\n", $out);
  88   }
  89
  90   protected function defineParamTypes() {
  91     return array(
  92       'buildTargetPHID' => 'phid',
  93       'artifactKey' => 'string',
  94       'artifactType' => 'string',
  95       'artifactData' => 'map<string, wild>',
  96     );
  97   }
  98
  99   protected function defineReturnType() {
 100     return 'wild';
 101   }
 102
 103   protected function execute(ConduitAPIRequest $request) {
 104     $viewer = $request->getUser();
 105
 106     $build_target_phid = $request->getValue('buildTargetPHID');
 107     $build_target = id(new HarbormasterBuildTargetQuery())
 108       ->setViewer($viewer)
 109       ->withPHIDs(array($build_target_phid))
 110       ->executeOne();
 111     if (!$build_target) {
 112       throw new Exception(
 113         pht(
 114           'No such build target "%s"!',
 115           $build_target_phid));
 116     }
 117
 118     $artifact_type = $request->getValue('artifactType');
 119
 120     // Cast "artifactData" parameters to acceptable types if this request
 121     // is submitting raw HTTP parameters. This is not ideal. See T11887 for
 122     // discussion.
 123     $artifact_data = $request->getValue('artifactData');
 124     if (!$request->getIsStrictlyTyped()) {
 125       $impl = HarbormasterArtifact::getArtifactType($artifact_type);
 126       if ($impl) {
 127         foreach ($artifact_data as $key => $value) {
 128           $artifact_data[$key] = $impl->readArtifactHTTPParameter(
 129             $key,
 130             $value);
 131         }
 132       }
 133     }
 134
 135     $artifact = $build_target->createArtifact(
 136       $viewer,
 137       $request->getValue('artifactKey'),
 138       $artifact_type,
 139       $artifact_data);
 140
 141     return array(
 142       'data' => $this->returnArtifactList(array($artifact)),
 143     );
 144   }
 145
 146 }