Allow installs to customize mail body guidance in the "Email Login" and "Set Password" emails

Summary:
Depends on D20662. Ref T13343. Installs may reasonably want to change the guidance users receive in "Email Login"/"Forgot Password" email.

(In an upcoming change I plan to supply a piece of default guidance, but Auth Messages need a few tweaks for this.)

There's probably little reason to provide guidance on the "Set Password" flow, but any guidance one might issue on the "Email Login" flow probably doesn't make sense on the "Set Password" flow, so I've included it mostly to make it clear that this is a different flow from a user perspective.

Test Plan:
  - Set custom "Email Login" and "Set Password" messages.
  - Generated "Email Login" mail by using the "Login via email" link on the login screen.
  - Generated "Set Password" email by trying to set a password on an account with no password yet.
  - Saw my custom messages in the resulting mail bodies.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13343

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

src/__phutil_library_map__.php

@@ -2265,6 +2265,8 @@ phutil_register_library_map(array(
     'PhabricatorAuthDisableController' => 'applications/auth/controller/config/PhabricatorAuthDisableController.php',
     'PhabricatorAuthDowngradeSessionController' => 'applications/auth/controller/PhabricatorAuthDowngradeSessionController.php',
     'PhabricatorAuthEditController' => 'applications/auth/controller/config/PhabricatorAuthEditController.php',
+    'PhabricatorAuthEmailLoginMessageType' => 'applications/auth/message/PhabricatorAuthEmailLoginMessageType.php',
+    'PhabricatorAuthEmailSetPasswordMessageType' => 'applications/auth/message/PhabricatorAuthEmailSetPasswordMessageType.php',
     'PhabricatorAuthFactor' => 'applications/auth/factor/PhabricatorAuthFactor.php',
     'PhabricatorAuthFactorConfig' => 'applications/auth/storage/PhabricatorAuthFactorConfig.php',
     'PhabricatorAuthFactorConfigQuery' => 'applications/auth/query/PhabricatorAuthFactorConfigQuery.php',
@@ -8220,6 +8222,8 @@ phutil_register_library_map(array(
     'PhabricatorAuthDisableController' => 'PhabricatorAuthProviderConfigController',
     'PhabricatorAuthDowngradeSessionController' => 'PhabricatorAuthController',
     'PhabricatorAuthEditController' => 'PhabricatorAuthProviderConfigController',
+    'PhabricatorAuthEmailLoginMessageType' => 'PhabricatorAuthMessageType',
+    'PhabricatorAuthEmailSetPasswordMessageType' => 'PhabricatorAuthMessageType',
     'PhabricatorAuthFactor' => 'Phobject',
     'PhabricatorAuthFactorConfig' => array(
       'PhabricatorAuthDAO',

src/applications/auth/message/PhabricatorAuthEmailLoginMessageType.php

@@ -0,0 +1,18 @@
+<?php
+
+final class PhabricatorAuthEmailLoginMessageType
+  extends PhabricatorAuthMessageType {
+
+  const MESSAGEKEY = 'mail.login';
+
+  public function getDisplayName() {
+    return pht('Mail Body: Email Login');
+  }
+
+  public function getShortDescription() {
+    return pht(
+      'Guidance in the message body when users request an email link '.
+      'to access their account.');
+  }
+
+}

src/applications/auth/message/PhabricatorAuthEmailSetPasswordMessageType.php

@@ -0,0 +1,18 @@
+<?php
+
+final class PhabricatorAuthEmailSetPasswordMessageType
+  extends PhabricatorAuthMessageType {
+
+  const MESSAGEKEY = 'mail.set-password';
+
+  public function getDisplayName() {
+    return pht('Mail Body: Set Password');
+  }
+
+  public function getShortDescription() {
+    return pht(
+      'Guidance in the message body when users set a password on an account '.
+      'which did not previously have a password.');
+  }
+
+}

src/applications/auth/message/PhabricatorAuthMessageType.php

@@ -28,5 +28,6 @@ abstract class PhabricatorAuthMessageType
   }
 
   abstract public function getDisplayName();
+  abstract public function getShortDescription();
 
 }

src/applications/auth/message/PhabricatorAuthWelcomeMailMessageType.php

@@ -6,7 +6,7 @@ final class PhabricatorAuthWelcomeMailMessageType
   const MESSAGEKEY = 'mail.welcome';
 
   public function getDisplayName() {
-    return pht('Welcome Email Body');
+    return pht('Mail Body: Welcome');
   }
 
   public function getShortDescription() {

src/applications/auth/storage/PhabricatorAuthMessage.php

@@ -45,7 +45,7 @@ final class PhabricatorAuthMessage
   }
 
   public function getURI() {
-    return urisprintf('/auth/message/%s', $this->getID());
+    return urisprintf('/auth/message/%s/', $this->getID());
   }
 
   public function attachMessageType(PhabricatorAuthMessageType $type) {

src/applications/people/mail/PhabricatorPeopleEmailLoginMailEngine.php

@@ -43,19 +43,34 @@ final class PhabricatorPeopleEmailLoginMailEngine
     $is_serious = PhabricatorEnv::getEnvConfig('phabricator.serious-business');
     $have_passwords = $this->isPasswordAuthEnabled();
 
+    $body = array();
+
+    if ($is_set_password) {
+      $message_key = PhabricatorAuthEmailSetPasswordMessageType::MESSAGEKEY;
+    } else {
+      $message_key = PhabricatorAuthEmailLoginMessageType::MESSAGEKEY;
+    }
+
+    $message_body = PhabricatorAuthMessage::loadMessageText(
+      $recipient,
+      $message_key);
+    if (strlen($message_body)) {
+      $body[] = $this->newRemarkupText($message_body);
+    }
+
     if ($have_passwords) {
       if ($is_set_password) {
-        $body = pht(
+        $body[] = pht(
           'You can use this link to set a password on your account:'.
           "\n\n  %s\n",
           $login_uri);
       } else if ($is_serious) {
-        $body = pht(
+        $body[] = pht(
           "You can use this link to reset your Phabricator password:".
           "\n\n  %s\n",
           $login_uri);
       } else {
-        $body = pht(
+        $body[] = pht(
           "Condolences on forgetting your password. You can use this ".
           "link to reset it:\n\n".
           "  %s\n\n".
@@ -68,7 +83,7 @@ final class PhabricatorPeopleEmailLoginMailEngine
 
       }
     } else {
-      $body = pht(
+      $body[] = pht(
         "You can use this login link to regain access to your Phabricator ".
         "account:".
         "\n\n".
@@ -76,6 +91,8 @@ final class PhabricatorPeopleEmailLoginMailEngine
         $login_uri);
     }
 
+    $body = implode("\n\n", $body);
+
     return id(new PhabricatorMetaMTAMail())
       ->setSubject($subject)
       ->setBody($body);