@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
MetaMTA - update documentation and make config a tad easier
Summary: Fixes T7088. Mainly this updates the documentation but I also snuck in tweaking how the domain reply handler is built. This does two main things -- makes the behavior consistent as some applications who didn't override this behavior would send out emails with reply tos AND makes it easier for us to deprecate the custom domain thing on a per application basis, which is just silly. On that note, the main documentation doesn't get into how this can be overridden, though I left in that mini blurb on the config setting itself. We could deprecate this harder and LOCK things if you want as well.
Test Plan: read docs, looked good. reasoned through re-factor
Reviewers: epriestley
Reviewed By: epriestley
Subscribers: Korvin, epriestley
Maniphest Tasks: T7088
Differential Revision: https://secure.phabricator.com/D11725
+70
-45
+1
-1
src/applications/audit/mail/PhabricatorAuditReplyHandler.php
+1
-1
src/applications/audit/mail/PhabricatorAuditReplyHandler.php
+3
-2
src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
+3
-2
src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
···
243
243
$this->newOption(
244
244
'metamta.reply-handler-domain',
245
245
'string',
246
-
'phabricator.example.com')
246
+
null)
247
247
->setDescription(pht(
248
248
'Domain used for reply email addresses. Some applications can '.
249
-
'configure this domain.')),
249
+
'override this configuration with a different domain.'))
250
+
->addExample('phabricator.example.com', ''),
250
251
$this->newOption('metamta.reply.show-hints', 'bool', true)
251
252
->setBoolOptions(
252
253
array(
+1
-1
src/applications/differential/mail/DifferentialReplyHandler.php
+1
-1
src/applications/differential/mail/DifferentialReplyHandler.php
-4
src/applications/fund/mail/FundInitiativeReplyHandler.php
-4
src/applications/fund/mail/FundInitiativeReplyHandler.php
···
17
17
return $this->getDefaultPublicReplyHandlerEmailAddress('I');
18
18
}
19
19
20
-
public function getReplyHandlerDomain() {
21
-
return PhabricatorEnv::getEnvConfig('metamta.reply-handler-domain');
22
-
}
23
-
24
20
public function getReplyHandlerInstructions() {
25
21
if ($this->supportsReplies()) {
26
22
// TODO: Implement.
-5
src/applications/legalpad/mail/LegalpadReplyHandler.php
-5
src/applications/legalpad/mail/LegalpadReplyHandler.php
···
17
17
return $this->getDefaultPublicReplyHandlerEmailAddress('L');
18
18
}
19
19
20
-
public function getReplyHandlerDomain() {
21
-
return PhabricatorEnv::getEnvConfig(
22
-
'metamta.reply-handler-domain');
23
-
}
24
-
25
20
public function getReplyHandlerInstructions() {
26
21
if ($this->supportsReplies()) {
27
22
return pht('Reply to comment or !unsubscribe.');
+1
-1
src/applications/macro/mail/PhabricatorMacroReplyHandler.php
+1
-1
src/applications/macro/mail/PhabricatorMacroReplyHandler.php
+1
-1
src/applications/maniphest/mail/ManiphestReplyHandler.php
+1
-1
src/applications/maniphest/mail/ManiphestReplyHandler.php
+19
src/applications/meta/query/PhabricatorAppSearchEngine.php
+19
src/applications/meta/query/PhabricatorAppSearchEngine.php
···
32
32
$saved->setParameter(
33
33
'launchable',
34
34
$this->readBoolFromRequest($request, 'launchable'));
35
+
$saved->setParameter(
36
+
'appemails',
37
+
$this->readBoolFromRequest($request, 'appemails'));
35
38
36
39
return $saved;
37
40
}
···
71
74
$launchable = $saved->getParameter('launchable');
72
75
if ($launchable !== null) {
73
76
$query->withLaunchable($launchable);
77
+
}
78
+
79
+
$appemails = $saved->getParameter('appemails');
80
+
if ($appemails !== null) {
81
+
$query->withApplicationEmailSupport($appemails);
74
82
}
75
83
76
84
return $query;
···
129
137
'' => pht('Show All Applications'),
130
138
'true' => pht('Show Launchable Applications'),
131
139
'false' => pht('Show Non-Launchable Applications'),
140
+
)))
141
+
->appendChild(
142
+
id(new AphrontFormSelectControl())
143
+
->setLabel(pht('Application Emails'))
144
+
->setName('appemails')
145
+
->setValue($this->getBoolFromQuery($saved, 'appemails'))
146
+
->setOptions(
147
+
array(
148
+
'' => pht('Show All Applications'),
149
+
'true' => pht('Show Applications w/ App Email Support'),
150
+
'false' => pht('Show Applications w/o App Email Support'),
132
151
)));
133
152
}
134
153
+14
src/applications/meta/query/PhabricatorApplicationQuery.php
+14
src/applications/meta/query/PhabricatorApplicationQuery.php
···
10
10
private $unlisted;
11
11
private $classes;
12
12
private $launchable;
13
+
private $applicationEmailSupport;
13
14
private $phids;
14
15
15
16
const ORDER_APPLICATION = 'order:application';
···
44
45
45
46
public function withLaunchable($launchable) {
46
47
$this->launchable = $launchable;
48
+
return $this;
49
+
}
50
+
51
+
public function withApplicationEmailSupport($appemails) {
52
+
$this->applicationEmailSupport = $appemails;
47
53
return $this;
48
54
}
49
55
···
131
137
}
132
138
}
133
139
140
+
if ($this->applicationEmailSupport !== null) {
141
+
foreach ($apps as $key => $app) {
142
+
if ($app->supportsEmailIntegration() !=
143
+
$this->applicationEmailSupport) {
144
+
unset($apps[$key]);
145
+
}
146
+
}
147
+
}
134
148
135
149
switch ($this->order) {
136
150
case self::ORDER_NAME:
+11
src/applications/metamta/replyhandler/PhabricatorMailReplyHandler.php
+11
src/applications/metamta/replyhandler/PhabricatorMailReplyHandler.php
···
49
49
abstract public function getPrivateReplyHandlerEmailAddress(
50
50
PhabricatorObjectHandle $handle);
51
51
public function getReplyHandlerDomain() {
52
+
return $this->getDefaultReplyHandlerDomain();
53
+
}
54
+
protected function getCustomReplyHandlerDomainIfExists($config_key) {
55
+
$domain = PhabricatorEnv::getEnvConfig($config_key);
56
+
if ($domain) {
57
+
return $domain;
58
+
}
59
+
return $this->getDefaultReplyHandlerDomain();
60
+
}
61
+
private function getDefaultReplyHandlerDomain() {
52
62
return PhabricatorEnv::getEnvConfig(
53
63
'metamta.reply-handler-domain');
54
64
}
65
+
55
66
abstract public function getReplyHandlerInstructions();
56
67
abstract protected function receiveEmail(
57
68
PhabricatorMetaMTAReceivedMail $mail);
+1
-1
src/applications/pholio/mail/PholioReplyHandler.php
+1
-1
src/applications/pholio/mail/PholioReplyHandler.php
-4
src/applications/phortune/mail/PhortuneCartReplyHandler.php
-4
src/applications/phortune/mail/PhortuneCartReplyHandler.php
···
17
17
return $this->getDefaultPublicReplyHandlerEmailAddress('CART');
18
18
}
19
19
20
-
public function getReplyHandlerDomain() {
21
-
return PhabricatorEnv::getEnvConfig('metamta.reply-handler-domain');
22
-
}
23
-
24
20
public function getReplyHandlerInstructions() {
25
21
if ($this->supportsReplies()) {
26
22
// TODO: Implement.
-4
src/applications/phriction/mail/PhrictionReplyHandler.php
-4
src/applications/phriction/mail/PhrictionReplyHandler.php
···
20
20
PhrictionDocumentPHIDType::TYPECONST);
21
21
}
22
22
23
-
public function getReplyHandlerDomain() {
24
-
return PhabricatorEnv::getEnvConfig('metamta.reply-handler-domain');
25
-
}
26
-
27
23
public function getReplyHandlerInstructions() {
28
24
if ($this->supportsReplies()) {
29
25
// TODO: Implement.
+18
-21
src/docs/user/configuration/configuring_inbound_email.diviner
+18
-21
src/docs/user/configuration/configuring_inbound_email.diviner
···
2
2
@group config
3
3
4
4
This document contains instructions for configuring inbound email, so users
5
-
may update Differential and Maniphest by replying to messages and create
6
-
Maniphest tasks via email.
5
+
may interact with some Phabricator applications via email.
7
6
8
7
= Preamble =
9
8
···
33
32
requesting changes to revisions.
34
33
35
34
To change this behavior so that users can interact with objects in Phabricator
36
-
over email, set these configuration keys:
37
-
38
-
- ##metamta.differential.reply-handler-domain##: enables email replies for
39
-
Differential.
40
-
- ##metamta.maniphest.reply-handler-domain##: enables email replies for
41
-
Maniphest.
42
-
43
-
Set these keys to some domain which you configure according to the instructions
44
-
below, e.g. `phabricator.example.com`. You can set these both to the same
45
-
domain, and will generally want to. Once you set these keys, emails will use a
46
-
'Reply-To' like `T123+273+af310f9220ad@example.com`, which -- when
35
+
over email, change the configuration key `metamta.reply-handler-domain` to some
36
+
domain you configure according to the instructions below, e.g.
37
+
`phabricator.example.com`. Once you set this key, emails will use a
38
+
'Reply-To' like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
47
39
configured correctly, according to the instructions below -- will parse incoming
48
-
email and allow users to interact with Maniphest tasks and Differential
49
-
revisions over email.
40
+
email and allow users to interact with Differential revisions, Maniphest tasks,
41
+
etc. over email.
50
42
51
43
If you don't want Phabricator to take up an entire domain (or subdomain) you
52
44
can configure a general prefix so you can use a single mailbox to receive mail
···
56
48
character in an email-address is considered the receiver, and everything
57
49
after is essentially ignored.
58
50
59
-
You can also set up a task creation email address, like `bugs@example.com`,
60
-
which will create a Maniphest task out of any email which is set to it. To do
61
-
this, set `metamta.maniphest.public-create-email` in your configuration. This
62
-
has some mild security implications, see below.
51
+
You can also set up application email addresses to allow users to create
52
+
application objects via email. For example, you could configure
53
+
`bugs@phabricator.example.com` to create a Maniphest task out of any email
54
+
which is sent to it. To do this, see application settings for a given
55
+
application at
56
+
57
+
{nav icon=home, name=Home >
58
+
name=Applications >
59
+
icon=cog, name=Settings}
63
60
64
61
= Security =
65
62
···
93
90
will still contain a hash unique to the object it represents, so users who have
94
91
not received an email about an object can not blindly interact with it.
95
92
96
-
If you enable `metamta.maniphest.public-create-email`, that address also uses
97
-
the weaker "From" authentication mechanism.
93
+
If you enable application email addresses, those addresses also use the weaker
94
+
"From" authentication mechanism.
98
95
99
96
NOTE: Phabricator does not currently attempt to verify "From" addresses because
100
97
this is technically complex, seems unreasonably difficult in the general case,