Show how to call Conduit API methods from clients

Summary: Fixes T3628. Ref T5955.

Test Plan:
On the method page, you see a generic example:

{F396471}

After making a call, you see a specific example with your parameters:

{F396472}

{F396474}

{F396475}

Reviewers: chad, btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T3628, T5955

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

src/applications/conduit/controller/PhabricatorConduitController.php

@@ -24,4 +24,250 @@ abstract class PhabricatorConduitController extends PhabricatorController {
     return $this->buildSideNavView()->getMenu();
   }
 
+  protected function renderExampleBox(ConduitAPIMethod $method, $params) {
+    $arc_example = id(new PHUIPropertyListView())
+      ->addRawContent($this->renderExample($method, 'arc', $params));
+
+    $curl_example = id(new PHUIPropertyListView())
+      ->addRawContent($this->renderExample($method, 'curl', $params));
+
+    $php_example = id(new PHUIPropertyListView())
+      ->addRawContent($this->renderExample($method, 'php', $params));
+
+    $panel_link = phutil_tag(
+      'a',
+      array(
+        'href' => '/settings/panel/apitokens/',
+      ),
+      pht('Conduit API Tokens'));
+
+    $panel_link = phutil_tag('strong', array(), $panel_link);
+
+    $messages = array(
+      pht(
+        'Use the %s panel in Settings to generate or manage API tokens.',
+        $panel_link),
+    );
+
+    $info_view = id(new PHUIInfoView())
+      ->setErrors($messages)
+      ->setSeverity(PHUIInfoView::SEVERITY_NOTICE);
+
+    return id(new PHUIObjectBoxView())
+      ->setHeaderText(pht('Examples'))
+      ->setInfoView($info_view)
+      ->addPropertyList($arc_example, pht('arc call-conduit'))
+      ->addPropertyList($curl_example, pht('cURL'))
+      ->addPropertyList($php_example, pht('PHP'));
+  }
+
+  private function renderExample(
+    ConduitAPIMethod $method,
+    $kind,
+    $params) {
+
+    switch ($kind) {
+      case 'arc':
+        $example = $this->buildArcanistExample($method, $params);
+        break;
+      case 'php':
+        $example = $this->buildPHPExample($method, $params);
+        break;
+      case 'curl':
+        $example = $this->buildCURLExample($method, $params);
+        break;
+      default:
+        throw new Exception(pht('Conduit client "%s" is not known.', $kind));
+    }
+
+    return $example;
+  }
+
+  private function buildArcanistExample(
+    ConduitAPIMethod $method,
+    $params) {
+
+    $parts = array();
+
+    $parts[] = '$ echo ';
+    if ($params === null) {
+      $parts[] = phutil_tag('strong', array(), '<json-parameters>');
+    } else {
+      $params = $this->simplifyParams($params);
+      $params = id(new PhutilJSON())->encodeFormatted($params);
+      $params = trim($params);
+      $params = csprintf('%s', $params);
+      $parts[] = phutil_tag('strong', array('class' => 'real'), $params);
+    }
+
+    $parts[] = ' | ';
+    $parts[] = 'arc call-conduit ';
+
+    $parts[] = '--conduit-uri ';
+    $parts[] = phutil_tag(
+      'strong',
+      array('class' => 'real'),
+      PhabricatorEnv::getURI('/'));
+    $parts[] = ' ';
+
+    $parts[] = '--conduit-token ';
+    $parts[] = phutil_tag('strong', array(), '<conduit-token>');
+    $parts[] = ' ';
+
+    $parts[] = $method->getAPIMethodName();
+
+    return $this->renderExampleCode($parts);
+  }
+
+  private function buildPHPExample(
+    ConduitAPIMethod $method,
+    $params) {
+
+    $parts = array();
+
+    $libphutil_path = 'path/to/libphutil/src/__phutil_library_init__.php';
+
+    $parts[] = '<?php';
+    $parts[] = "\n\n";
+
+    $parts[] = 'require_once ';
+    $parts[] = phutil_var_export($libphutil_path, true);
+    $parts[] = ";\n\n";
+
+    $parts[] = '$api_token = "';
+    $parts[] = phutil_tag('strong', array(), pht('<api-token>'));
+    $parts[] = "\";\n";
+
+    $parts[] = '$api_parameters = ';
+    if ($params === null) {
+      $parts[] = 'array(';
+      $parts[] = phutil_tag('strong', array(), pht('<parameters>'));
+      $parts[] = ');';
+    } else {
+      $params = $this->simplifyParams($params);
+      $params = phutil_var_export($params, true);
+      $parts[] = phutil_tag('strong', array('class' => 'real'), $params);
+      $parts[] = ';';
+    }
+    $parts[] = "\n\n";
+
+    $parts[] = '$client = new ConduitClient(';
+    $parts[] = phutil_tag(
+      'strong',
+      array('class' => 'real'),
+      phutil_var_export(PhabricatorEnv::getURI('/'), true));
+    $parts[] = ");\n";
+
+    $parts[] = '$client->setConduitToken($api_token);';
+    $parts[] = "\n\n";
+
+    $parts[] = '$result = $client->callMethodSynchronous(';
+    $parts[] = phutil_tag(
+      'strong',
+      array('class' => 'real'),
+      phutil_var_export($method->getAPIMethodName(), true));
+    $parts[] = ', ';
+    $parts[] = '$api_parameters';
+    $parts[] = ");\n";
+
+    $parts[] = 'print_r($result);';
+
+    return $this->renderExampleCode($parts);
+  }
+
+  private function buildCURLExample(
+    ConduitAPIMethod $method,
+    $params) {
+
+    $call_uri = '/api/'.$method->getAPIMethodName();
+
+    $parts = array();
+
+    $linebreak = array('\\', phutil_tag('br'), '    ');
+
+    $parts[] = '$ curl ';
+    $parts[] = phutil_tag(
+      'strong',
+      array('class' => 'real'),
+      csprintf('%R', PhabricatorEnv::getURI($call_uri)));
+    $parts[] = ' ';
+    $parts[] = $linebreak;
+
+    $parts[] = '-d api.token=';
+    $parts[] = phutil_tag('strong', array(), 'api-token');
+    $parts[] = ' ';
+    $parts[] = $linebreak;
+
+    if ($params === null) {
+      $parts[] = '-d ';
+      $parts[] = phutil_tag('strong', array(), 'param');
+      $parts[] = '=';
+      $parts[] = phutil_tag('strong', array(), 'value');
+      $parts[] = ' ';
+      $parts[] = $linebreak;
+      $parts[] = phutil_tag('strong', array(), '...');
+    } else {
+      $lines = array();
+      $params = $this->simplifyParams($params);
+
+      foreach ($params as $key => $value) {
+        $pieces = $this->getQueryStringParts(null, $key, $value);
+        foreach ($pieces as $piece) {
+          $lines[] = array(
+            '-d ',
+            phutil_tag('strong', array('class' => 'real'), $piece),
+          );
+        }
+      }
+
+      $parts[] = phutil_implode_html(array(' ', $linebreak), $lines);
+    }
+
+    return $this->renderExampleCode($parts);
+  }
+
+  private function renderExampleCode($example) {
+    require_celerity_resource('conduit-api-css');
+
+    return phutil_tag(
+      'div',
+      array(
+        'class' => 'PhabricatorMonospaced conduit-api-example-code',
+      ),
+      $example);
+  }
+
+  private function simplifyParams(array $params) {
+    foreach ($params as $key => $value) {
+      if ($value === null) {
+        unset($params[$key]);
+      }
+    }
+    return $params;
+  }
+
+  private function getQueryStringParts($prefix, $key, $value) {
+    if ($prefix === null) {
+      $head = phutil_escape_uri($key);
+    } else {
+      $head = $prefix.'['.phutil_escape_uri($key).']';
+    }
+
+    if (!is_array($value)) {
+      return array(
+        $head.'='.phutil_escape_uri($value),
+      );
+    }
+
+    $results = array();
+    foreach ($value as $subkey => $subvalue) {
+      $subparts = $this->getQueryStringParts($head, $subkey, $subvalue);
+      foreach ($subparts as $subpart) {
+        $results[] = $subpart;
+      }
+    }
+
+    return $results;
+  }
+
 }