In email, render dates with an explicit timezone offset

Summary:
Fixes T10633. When generating email about a transaction which adjusts a date, render the offset explicitly (like "UTC-7").

This makes it more clear in cases like this:

  - mail is being sent to multiple users, and not necessarily using the viewer's settings;
  - you get some mail while travelling and aren't sure which timezone setting it generated under.

Test Plan: Rendered in text mode, saw UTC offset.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T10633

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

src/applications/people/storage/PhabricatorUser.php

@@ -832,6 +832,14 @@ final class PhabricatorUser
     return $offset;
   }
 
+  public function getTimeZoneOffsetInHours() {
+    $offset = $this->getTimeZoneOffset();
+    $offset = (int)round($offset / 60);
+    $offset = -$offset;
+
+    return $offset;
+  }
+
   public function formatShortDateTime($when, $now = null) {
     if ($now === null) {
       $now = PhabricatorTime::getNow();

src/applications/transactions/storage/PhabricatorModularTransactionType.php

@@ -141,8 +141,7 @@ abstract class PhabricatorModularTransactionType
     $viewer = $this->getViewer();
     $display = $viewer->renderHandle($phid);
 
-    $rendering_target = $this->getStorage()->getRenderingTarget();
-    if ($rendering_target == PhabricatorApplicationTransaction::TARGET_TEXT) {
+    if ($this->isTextMode()) {
       $display->setAsText(true);
     }
 
@@ -154,8 +153,7 @@ abstract class PhabricatorModularTransactionType
     $display = $viewer->renderHandleList($phids)
       ->setAsInline(true);
 
-    $rendering_target = $this->getStorage()->getRenderingTarget();
-    if ($rendering_target == PhabricatorApplicationTransaction::TARGET_TEXT) {
+    if ($this->isTextMode()) {
       $display->setAsText(true);
     }
 
@@ -163,8 +161,7 @@ abstract class PhabricatorModularTransactionType
   }
 
   final protected function renderValue($value) {
-    $rendering_target = $this->getStorage()->getRenderingTarget();
-    if ($rendering_target == PhabricatorApplicationTransaction::TARGET_TEXT) {
+    if ($this->isTextMode()) {
       return sprintf('"%s"', $value);
     }
 
@@ -189,7 +186,19 @@ abstract class PhabricatorModularTransactionType
 
     $display = phabricator_datetime($epoch, $viewer);
 
-    // TODO: When rendering for email, include the UTC offset. See T10633.
+    // When rendering to text, we explicitly render the offset from UTC to
+    // provide context to the date: the mail may be generating with the
+    // server's settings, or the user may later refer back to it after changing
+    // timezones.
+
+    if ($this->isTextMode()) {
+      $offset = $viewer->getTimeZoneOffsetInHours();
+      if ($offset >= 0) {
+        $display = pht('%s (UTC+%d)', $display, $offset);
+      } else {
+        $display = pht('%s (UTC-%d)', $display, abs($offset));
+      }
+    }
 
     return $this->renderValue($display);
   }
@@ -231,5 +240,9 @@ abstract class PhabricatorModularTransactionType
     return !strlen($value);
   }
 
+  private function isTextMode() {
+    $target = $this->getStorage()->getRenderingTarget();
+    return ($target == PhabricatorApplicationTransaction::TARGET_TEXT);
+  }
 
 }