No OneTemporary
Actions

Size

13 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/applications/differential/mail/base/DifferentialMail.php b/src/applications/differential/mail/base/DifferentialMail.php
	index 51eab73957..6e506d6486 100644
	--- a/src/applications/differential/mail/base/DifferentialMail.php
	+++ b/src/applications/differential/mail/base/DifferentialMail.php
	@@ -1,381 +1,379 @@
	<?php

	/*
	* Copyright 2012 Facebook, Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	abstract class DifferentialMail {

	protected $to = array();
	protected $cc = array();

	protected $actorHandle;

	protected $revision;
	protected $comment;
	protected $changesets;
	protected $inlineComments;
	protected $isFirstMailAboutRevision;
	protected $isFirstMailToRecipients;
	protected $heraldTranscriptURI;
	protected $heraldRulesHeader;
	protected $replyHandler;
	protected $parentMessageID;

	abstract protected function renderSubject();
	abstract protected function renderBody();

	public function setActorHandle($actor_handle) {
	$this->actorHandle = $actor_handle;
	return $this;
	}

	public function getActorHandle() {
	return $this->actorHandle;
	}

	protected function getActorName() {
	$handle = $this->getActorHandle();
	if ($handle) {
	return $handle->getName();
	}
	return '???';
	}

	public function setParentMessageID($parent_message_id) {
	$this->parentMessageID = $parent_message_id;
	return $this;
	}

	public function setXHeraldRulesHeader($header) {
	$this->heraldRulesHeader = $header;
	return $this;
	}

	public function send() {
	$to_phids = $this->getToPHIDs();
	if (!$to_phids) {
	throw new Exception('No "To:" users provided!');
	}

	$cc_phids = $this->getCCPHIDs();
	$subject = $this->buildSubject();
	$body = $this->buildBody();
	$attachments = $this->buildAttachments();

	$template = new PhabricatorMetaMTAMail();
	$actor_handle = $this->getActorHandle();
	$reply_handler = $this->getReplyHandler();

	if ($actor_handle) {
	$template->setFrom($actor_handle->getPHID());
	}

	$template
	->setSubject($subject)
	->setBody($body)
	->setIsHTML($this->shouldMarkMailAsHTML())
	->setParentMessageID($this->parentMessageID)
	->addHeader('Thread-Topic', $this->getRevision()->getTitle());

	$template->setAttachments($attachments);

	$template->setThreadID(
	$this->getThreadID(),
	$this->isFirstMailAboutRevision());

	if ($this->heraldRulesHeader) {
	$template->addHeader('X-Herald-Rules', $this->heraldRulesHeader);
	}

	$revision = $this->revision;
	if ($revision) {
	if ($revision->getAuthorPHID()) {
	$template->addHeader(
	'X-Differential-Author',
	'<'.$revision->getAuthorPHID().'>');
	}
	if ($revision->getReviewers()) {
	$template->addHeader(
	'X-Differential-Reviewers',
	'<'.implode('>, <', $revision->getReviewers()).'>');
	}
	if ($revision->getCCPHIDs()) {
	$template->addHeader(
	'X-Differential-CCs',
	'<'.implode('>, <', $revision->getCCPHIDs()).'>');
	}
	}

	$template->setIsBulk(true);
	$template->setRelatedPHID($this->getRevision()->getPHID());

	$mailtags = $this->getMailTags();
	if ($mailtags) {
	$template->setMailTags($mailtags);
	}

	$phids = array();
	foreach ($to_phids as $phid) {
	$phids[$phid] = true;
	}
	foreach ($cc_phids as $phid) {
	$phids[$phid] = true;
	}
	$phids = array_keys($phids);

	$handles = id(new PhabricatorObjectHandleData($phids))->loadHandles();

	$event = new PhabricatorEvent(
	PhabricatorEventType::TYPE_DIFFERENTIAL_WILLSENDMAIL,
	array(
	'mail' => $template,
	)
	);
	PhutilEventEngine::dispatchEvent($event);

	$template = $event->getValue('mail');

	$mails = $reply_handler->multiplexMail(
	$template,
	array_select_keys($handles, $to_phids),
	array_select_keys($handles, $cc_phids));

	foreach ($mails as $mail) {
	$mail->saveAndSend();
	}
	}

	protected function getMailTags() {
	return array();
	}

	protected function getSubjectPrefix() {
	return PhabricatorEnv::getEnvConfig('metamta.differential.subject-prefix');
	}

	protected function buildSubject() {
	return trim($this->getSubjectPrefix().' '.$this->renderSubject());
	}

	protected function shouldMarkMailAsHTML() {
	return false;
	}

	protected function buildBody() {

	$body = $this->renderBody();

	$reply_handler = $this->getReplyHandler();
	$reply_instructions = $reply_handler->getReplyHandlerInstructions();
	if ($reply_instructions) {
	$body .=
	"\nREPLY HANDLER ACTIONS\n".
	" {$reply_instructions}\n";
	}

	if ($this->getHeraldTranscriptURI() && $this->isFirstMailToRecipients()) {
	$manage_uri = PhabricatorEnv::getProductionURI(
	'/herald/view/differential/');

	$xscript_uri = $this->getHeraldTranscriptURI();
	$body .= <<<EOTEXT

	MANAGE HERALD DIFFERENTIAL RULES
	{$manage_uri}

	WHY DID I GET THIS EMAIL?
	{$xscript_uri}

	-Tip: use the X-Herald-Rules header to filter Herald messages in your client.
	-
	EOTEXT;
	}

	return $body;
	}

	/**
	* You can override this method in a subclass and return array of attachments
	* to be sent with the email. Each attachment is an instance of
	* PhabricatorMetaMTAAttachment.
	*/
	protected function buildAttachments() {
	return array();
	}

	public function getReplyHandler() {
	if ($this->replyHandler) {
	return $this->replyHandler;
	}

	$handler_class = PhabricatorEnv::getEnvConfig(
	'metamta.differential.reply-handler');

	$reply_handler = self::newReplyHandlerForRevision($this->getRevision());

	$this->replyHandler = $reply_handler;

	return $this->replyHandler;
	}

	public static function newReplyHandlerForRevision(
	DifferentialRevision $revision) {

	$handler_class = PhabricatorEnv::getEnvConfig(
	'metamta.differential.reply-handler');

	$reply_handler = newv($handler_class, array());
	$reply_handler->setMailReceiver($revision);

	return $reply_handler;
	}


	protected function formatText($text) {
	$text = explode("\n", $text);
	foreach ($text as &$line) {
	$line = rtrim(' '.$line);
	}
	unset($line);
	return implode("\n", $text);
	}

	public function setToPHIDs(array $to) {
	$this->to = $this->filterContactPHIDs($to);
	return $this;
	}

	public function setCCPHIDs(array $cc) {
	$this->cc = $this->filterContactPHIDs($cc);
	return $this;
	}

	protected function filterContactPHIDs(array $phids) {
	return $phids;

	// TODO: actually do this?

	// Differential revisions use Subscriptions for CCs, so any arbitrary
	// PHID can end up CC'd to them. Only try to actually send email PHIDs
	// which have ToolsHandle types that are marked emailable. If we don't
	// filter here, sending the email will fail.
	/*
	$handles = array();
	prep(new ToolsHandleData($phids, $handles));
	foreach ($handles as $phid => $handle) {
	if (!$handle->isEmailable()) {
	unset($handles[$phid]);
	}
	}
	return array_keys($handles);
	*/
	}

	protected function getToPHIDs() {
	return $this->to;
	}

	protected function getCCPHIDs() {
	return $this->cc;
	}

	public function setRevision($revision) {
	$this->revision = $revision;
	return $this;
	}

	public function getRevision() {
	return $this->revision;
	}

	protected function getThreadID() {
	$phid = $this->getRevision()->getPHID();
	$domain = PhabricatorEnv::getEnvConfig('metamta.domain');
	return "<differential-rev-{$phid}-req@{$domain}>";
	}

	public function setComment($comment) {
	$this->comment = $comment;
	return $this;
	}

	public function getComment() {
	return $this->comment;
	}

	public function setChangesets($changesets) {
	$this->changesets = $changesets;
	return $this;
	}

	public function getChangesets() {
	return $this->changesets;
	}

	public function setInlineComments(array $inline_comments) {
	$this->inlineComments = $inline_comments;
	return $this;
	}

	public function getInlineComments() {
	return $this->inlineComments;
	}

	public function renderRevisionDetailLink() {
	$uri = $this->getRevisionURI();
	return "REVISION DETAIL\n {$uri}";
	}

	public function getRevisionURI() {
	return PhabricatorEnv::getProductionURI('/D'.$this->getRevision()->getID());
	}

	public function setIsFirstMailToRecipients($first) {
	$this->isFirstMailToRecipients = $first;
	return $this;
	}

	public function isFirstMailToRecipients() {
	return $this->isFirstMailToRecipients;
	}

	public function setIsFirstMailAboutRevision($first) {
	$this->isFirstMailAboutRevision = $first;
	return $this;
	}

	public function isFirstMailAboutRevision() {
	return $this->isFirstMailAboutRevision;
	}

	public function setHeraldTranscriptURI($herald_transcript_uri) {
	$this->heraldTranscriptURI = $herald_transcript_uri;
	return $this;
	}

	public function getHeraldTranscriptURI() {
	return $this->heraldTranscriptURI;
	}

	protected function renderHandleList(array $handles, array $phids) {
	$names = array();
	foreach ($phids as $phid) {
	$names[] = $handles[$phid]->getName();
	}
	return implode(', ', $names);
	}

	}
	diff --git a/src/docs/userguide/mail_rules.diviner b/src/docs/userguide/mail_rules.diviner
	new file mode 100644
	index 0000000000..07bb07bc51
	--- /dev/null
	+++ b/src/docs/userguide/mail_rules.diviner
	@@ -0,0 +1,72 @@
	+@title User Guide: Managing Phabricator Email
	+@group userguide
	+
	+How to effectively manage Phabricator email notifications.
	+
	+= Overview =
	+
	+Phabricator uses email as a major notification channel, but the amount of email
	+it sends can seem overwhelming if you're working on an active team. This
	+document discusses some strategies for managing email.
	+
	+By far the best approach to managing mail is to write mail rules to
	+categorize mail. Essentially all modern mail clients allow you to quickly
	+write sophisticated rules to route, categorize, or delete email.
	+
	+= Reducing Email =
	+
	+You can reduce the amount of email you receive by turning off some types of
	+email in ##Settings -> Email Preferences##. For example, you can turn off email
	+produced by your own actions (like when you comment on a revision), and some
	+types of less-important notifications about events.
	+
	+= Mail Rules =
	+
	+The best approach to managing mail is to write mail rules. Simply writing rules
	+to move mail from Differential, Maniphest and Herald to separate folders will
	+vastly simplify mail management.
	+
	+Phabricator also sets a large number of headers (see below) which can allow you
	+to write more sophisticated mail rules.
	+
	+= Mail Headers =
	+
	+Phabricator sends a variety of mail headers that can be useful in crafting rules
	+to route and manage mail.
	+
	+Many of these headers contain lists. A list containing two items, ##1## and
	+##15## will generally be formatted like this:
	+
	+ X-Header: <1>, <15>
	+
	+The intent is to allow you to write a rule which matches against "<1>". If you
	+just match against "1", you'll incorrectly match "15", but matching "<1>" will
	+correctly match only "<1>".
	+
	+The headers Phabricator adds to mail are:
	+
	+ - ##X-Phabricator-Sent-This-Message##: this is attached to all mail
	+ Phabricator sends. You can use it to differentiate between email from
	+ Phabricator and replies/forwards of Phabricator mail from human beings.
	+ - ##X-Phabricator-To##: this is attached to all mail Phabricator sends.
	+ It this shows the PHIDs of the original "To" line, before any mutation
	+ by the mailer configuration.
	+ - ##X-Phabricator-Cc##: this is attached to all mail Phabricator sends.
	+ It shows the PHIDs of the original "Cc" line, before any mutation by the
	+ mailer configuration.
	+ - ##X-Differential-Author##: this is attached to Differential mail and shows
	+ the revision's author. You can use it to filter mail about your revisions
	+ (or other users' revisions).
	+ - ##X-Differential-Reviewers##: this is attached to Differential mail and
	+ shows the reviewers. You can use it to filter mail about revisions you
	+ are reviewing, versus revisions you are explicitly CC'd on or CC'd as
	+ a result of Herald rules.
	+ - ##X-Differential-CCs##: this is attached to Differential mail and shows
	+ the explicit CCs on the revision.
	+ - ##X-Phabricator-Mail-Tags##: this is attached to some mail and has
	+ a list of descriptors about the mail. (This is fairly new and subject
	+ to some change.)
	+ - ##X-Herald-Rules##: this is attached to some mail and shows Herald rule
	+ IDs which have triggered for the object. You can use this to sort or
	+ categorize mail that has triggered specific rules.
	+

File Metadata

Mime Type: text/x-diff
Expires: Sat, Sep 20, 8:06 AM (1 d, 27 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 241528
Default Alt Text: (13 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions