Give data exporters a header row

Summary:
Depends on D18951. Ref T13049. When we export to CSV or plain text, add a header row in the first line of the file to explain what each column means. This often isn't obvious with PHIDs, etc.

JSON has keys and is essentially self-labeling, so don't do anything special.

Test Plan: Exported CSV and text, saw new headers. Exported JSON, no changes.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13049

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

src/applications/search/controller/PhabricatorApplicationSearchController.php

@@ -454,6 +454,7 @@ final class PhabricatorApplicationSearchController
         $field_list = $engine->newExportFieldList();
         $field_list = mpull($field_list, null, 'getKey');
 
+        $format->addHeaders($field_list);
         for ($ii = 0; $ii < count($objects); $ii++) {
           $format->addObject($objects[$ii], $field_list, $export_data[$ii]);
         }

src/infrastructure/export/PhabricatorCSVExportFormat.php

@@ -23,21 +23,34 @@ final class PhabricatorCSVExportFormat
     return 'text/csv';
   }
 
+  public function addHeaders(array $fields) {
+    $headers = mpull($fields, 'getLabel');
+    $this->addRow($headers);
+  }
+
   public function addObject($object, array $fields, array $map) {
     $values = array();
     foreach ($fields as $key => $field) {
       $value = $map[$key];
       $value = $field->getTextValue($value);
+      $values[] = $value;
+    }
 
+    $this->addRow($values);
+  }
+
+  private function addRow(array $values) {
+    $row = array();
+    foreach ($values as $value) {
       if (preg_match('/\s|,|\"/', $value)) {
         $value = str_replace('"', '""', $value);
         $value = '"'.$value.'"';
       }
 
-      $values[] = $value;
+      $row[] = $value;
     }
 
-    $this->rows[] = implode(',', $values);
+    $this->rows[] = implode(',', $row);
   }
 
   public function newFileData() {

src/infrastructure/export/PhabricatorExportFormat.php

@@ -22,6 +22,10 @@ abstract class PhabricatorExportFormat
   abstract public function getMIMEContentType();
   abstract public function getFileExtension();
 
+  public function addHeaders(array $fields) {
+    return;
+  }
+
   abstract public function addObject($object, array $fields, array $map);
   abstract public function newFileData();
 

src/infrastructure/export/PhabricatorTextExportFormat.php

@@ -23,17 +23,29 @@ final class PhabricatorTextExportFormat
     return 'text/plain';
   }
 
+  public function addHeaders(array $fields) {
+    $headers = mpull($fields, 'getLabel');
+    $this->addRow($headers);
+  }
+
   public function addObject($object, array $fields, array $map) {
     $values = array();
     foreach ($fields as $key => $field) {
       $value = $map[$key];
       $value = $field->getTextValue($value);
-      $value = addcslashes($value, "\0..\37\\\177..\377");
-
       $values[] = $value;
     }
 
-    $this->rows[] = implode("\t", $values);
+    $this->addRow($values);
+  }
+
+  private function addRow(array $values) {
+    $row = array();
+    foreach ($values as $value) {
+      $row[] = addcslashes($value, "\0..\37\\\177..\377");
+    }
+
+    $this->rows[] = implode("\t", $row);
   }
 
   public function newFileData() {