From 0de6210808d7de78b0af0bea4e45f8537435be85 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Sun, 28 Jan 2018 18:32:22 -0800
Subject: [PATCH] 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
---
 .../PhabricatorApplicationSearchController.php |  1 +
 .../export/PhabricatorCSVExportFormat.php      | 17 +++++++++++++++--
 .../export/PhabricatorExportFormat.php         |  4 ++++
 .../export/PhabricatorTextExportFormat.php     | 18 +++++++++++++++---
 4 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/applications/search/controller/PhabricatorApplicationSearchController.php b/src/applications/search/controller/PhabricatorApplicationSearchController.php
index 037a626f26..0402102e2b 100644
--- a/src/applications/search/controller/PhabricatorApplicationSearchController.php
+++ b/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]);
         }
diff --git a/src/infrastructure/export/PhabricatorCSVExportFormat.php b/src/infrastructure/export/PhabricatorCSVExportFormat.php
index d9662467ec..67f0a4963a 100644
--- a/src/infrastructure/export/PhabricatorCSVExportFormat.php
+++ b/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() {
diff --git a/src/infrastructure/export/PhabricatorExportFormat.php b/src/infrastructure/export/PhabricatorExportFormat.php
index a1da4e90d8..9a8e035c58 100644
--- a/src/infrastructure/export/PhabricatorExportFormat.php
+++ b/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();
 
diff --git a/src/infrastructure/export/PhabricatorTextExportFormat.php b/src/infrastructure/export/PhabricatorTextExportFormat.php
index ec308f2eb5..d51e199f91 100644
--- a/src/infrastructure/export/PhabricatorTextExportFormat.php
+++ b/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() {