Add a bin/config set <key> --stdin < value.json flag to make CLI configuration of complex values easier

Summary:
Depends on D19003. Ref T12677. Ref T13053. For the first time, we're requiring CLI configuration of a complex value (not just a string, integer, bool, etc) to do something fairly standard (send mail).

Users sometimes have very reasonable difficulty figuring out how to `./bin/config set key <some big JSON mess>`. Provide an easy way to handle this and make sure it gets appropriate callouts in the documentation.

(Also, hide the `cluster.mailers` value rather than just locking it, since it may have API keys or SMTP passwords.)

Test Plan: Read documentation, used old and new flags to set configuration.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13053, T12677

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

src/applications/config/management/PhabricatorConfigManagementSetWorkflow.php

@@ -6,7 +6,9 @@ final class PhabricatorConfigManagementSetWorkflow
   protected function didConstruct() {
     $this
       ->setName('set')
-      ->setExamples('**set** __key__ __value__')
+      ->setExamples(
+        "**set** __key__ __value__\n".
+        "**set** __key__ --stdin < value.json")
       ->setSynopsis(pht('Set a local configuration value.'))
       ->setArguments(
         array(
@@ -16,6 +18,10 @@ final class PhabricatorConfigManagementSetWorkflow
               'Update configuration in the database instead of '.
               'in local configuration.'),
           ),
+          array(
+            'name' => 'stdin',
+            'help' => pht('Read option value from stdin.'),
+          ),
           array(
             'name'      => 'args',
             'wildcard'  => true,
@@ -31,22 +37,36 @@ final class PhabricatorConfigManagementSetWorkflow
         pht('Specify a configuration key and a value to set it to.'));
     }
 
+    $is_stdin = $args->getArg('stdin');
+
     $key = $argv[0];
 
-    if (count($argv) == 1) {
-      throw new PhutilArgumentUsageException(
-        pht(
-          "Specify a value to set the key '%s' to.",
-          $key));
+    if ($is_stdin) {
+      if (count($argv) > 1) {
+        throw new PhutilArgumentUsageException(
+          pht(
+            'Too many arguments: expected only a key when using "--stdin".'));
+      }
+
+      fprintf(STDERR, tsprintf("%s\n", pht('Reading value from stdin...')));
+      $value = file_get_contents('php://stdin');
+    } else {
+      if (count($argv) == 1) {
+        throw new PhutilArgumentUsageException(
+          pht(
+            "Specify a value to set the key '%s' to.",
+            $key));
+      }
+
+      if (count($argv) > 2) {
+        throw new PhutilArgumentUsageException(
+          pht(
+            'Too many arguments: expected one key and one value.'));
+      }
+
+      $value = $argv[1];
     }
 
-    $value = $argv[1];
-
-    if (count($argv) > 2) {
-      throw new PhutilArgumentUsageException(
-        pht(
-          'Too many arguments: expected one key and one value.'));
-    }
 
     $options = PhabricatorApplicationConfigOptions::loadAllOptions();
     if (empty($options[$key])) {

src/applications/config/option/PhabricatorMetaMTAConfigOptions.php

@@ -202,7 +202,7 @@ EODOC
 
     return array(
       $this->newOption('cluster.mailers', 'cluster.mailers', null)
-        ->setLocked(true)
+        ->setHidden(true)
         ->setDescription($mailers_description),
       $this->newOption(
         'metamta.default-address',

src/docs/user/configuration/configuration_locked.diviner

@@ -27,6 +27,24 @@ can edit it from the CLI instead, with `bin/config`:
 phabricator/ $ ./bin/config set <key> <value>
 ```
 
+Some configuration options take complicated values which can be difficult
+to escape properly for the shell. The easiest way to set these options is
+to use the `--stdin` flag. First, put your desired value in a `config.json`
+file:
+
+```name=config.json, lang=json
+{
+  "duck": "quack",
+  "cow": "moo"
+}
+```
+
+Then, set it with `--stdin` like this:
+
+```
+phabricator/ $ ./bin/config set <key> --stdin < config.json
+```
+
 A few settings have alternate CLI tools. Refer to the setting page for
 details.
 
@@ -98,4 +116,6 @@ Next Steps
 
 Continue by:
 
+  - learning more about advanced options with
+    @{Configuration User Guide: Advanced Configuration}; or
   - returning to the @{article: Configuration Guide}.

src/docs/user/configuration/configuring_outbound_email.diviner

@@ -101,6 +101,40 @@ Once you've selected a mailer, find the corresponding section below for
 instructions on configuring it.
 
 
+Setting Complex Configuration
+=============================
+
+Mailers can not be edited from the web UI. If mailers could be edited from
+the web UI, it would give an attacker who compromised an administrator account
+a lot of power: they could redirect mail to a server they control and then
+intercept mail for any other account, including password reset mail.
+
+For more information about locked configuration options, see
+@{article:Configuration Guide: Locked and Hidden Configuration}.
+
+Setting `cluster.mailers` from the command line using `bin/config set` can be
+tricky because of shell escaping. The easiest way to do it is to use the
+`--stdin` flag. First, put your desired configuration in a file like this:
+
+```lang=json, name=mailers.json
+[
+  {
+    "key": "test-mailer",
+    "type": "test"
+  }
+]
+```
+
+Then set the value like this:
+
+```
+phabricator/ $ ./bin/config set --stdin < mailers.json
+```
+
+For alternatives and more information on configuration, see
+@{article:Configuration User Guide: Advanced Configuration}
+
+
 Mailer: Mailgun
 ===============