3 * @copyright Copyright (C) 2010-2023, the Friendica project
5 * @license GNU AGPL version 3 or any later version
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Affero General Public License as
9 * published by the Free Software Foundation, either version 3 of the
10 * License, or (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Affero General Public License for more details.
17 * You should have received a copy of the GNU Affero General Public License
18 * along with this program. If not, see <https://www.gnu.org/licenses/>.
22 namespace Friendica\Util\EMailer;
26 use Friendica\App\BaseURL;
27 use Friendica\Core\Config\Capability\IManageConfigValues;
28 use Friendica\Core\L10n;
29 use Friendica\Core\Renderer;
30 use Friendica\Model\User;
31 use Friendica\Network\HTTPException\UnprocessableEntityException;
32 use Friendica\Object\Email;
33 use Friendica\Object\EMail\IEmail;
34 use Psr\Log\LoggerInterface;
37 * A base class for building new emails
39 abstract class MailBuilder
41 /** @var string The default email banner in case nothing else is defined */
42 const DEFAULT_EMAIL_BANNER = 'images/friendica-32.png';
46 /** @var IManageConfigValues */
50 /** @var LoggerInterface */
53 /** @var string[][] */
57 protected $senderName = null;
59 protected $senderAddress = null;
61 protected $senderNoReply = null;
64 protected $recipientAddress = null;
66 protected $recipientUid = null;
68 public function __construct(L10n $l10n, BaseURL $baseUrl, IManageConfigValues $config, LoggerInterface $logger)
71 $this->baseUrl = $baseUrl;
72 $this->config = $config;
73 $this->logger = $logger;
75 $hostname = $baseUrl->getHost();
76 if (strpos($hostname, ':')) {
77 $hostname = substr($hostname, 0, strpos($hostname, ':'));
81 'Precedence' => ['list'],
82 'X-Friendica-Host' => [$hostname],
83 'X-Friendica-Platform' => [App::PLATFORM],
84 'X-Friendica-Version' => [App::VERSION],
85 'List-ID' => ['<notification.' . $hostname . '>'],
86 'List-Archive' => ['<' . $baseUrl . '/notifications/system>'],
91 * Gets the subject of the concrete builder, which inherits this base class
95 abstract protected function getSubject();
98 * Gets the HTML version of the body of the concrete builder, which inherits this base class
102 abstract protected function getHtmlMessage();
105 * Gets the Plaintext version of the body of the concrete builder, which inherits this base class
109 abstract protected function getPlaintextMessage();
112 * Adds the User ID to the email in case the mail sending needs additional properties of this user
114 * @param array $user The user entity/array, for which the email should be sent
117 * @todo Once the user array is replaced with a user entity, replace this array parameter as well
119 public function forUser(array $user)
121 $this->recipientUid = $user['uid'] ?? 0;
123 $this->l10n = isset($user['language']) ? $this->l10n->withLang($user['language']) : $this->l10n;
124 } catch (Exception $e) {
125 $this->logger->warning('cannot use language.', ['user' => $user, 'exception' => $e]);
132 * Adds the sender to the email (if not called/set, the sender will get loaded with the help of the user id)
134 * @param string $name The name of the sender
135 * @param string $address The (email) address of the sender
136 * @param string|null $noReply Optional "no-reply" (email) address (if not set, it's the same as the address)
140 public function withSender(string $name, string $address, string $noReply = null)
142 $this->senderName = $name;
143 $this->senderAddress = $address;
144 $this->senderNoReply = $noReply ?? $this->senderNoReply;
150 * Adds a recipient to the email
152 * @param string $address The (email) address of the recipient
156 public function withRecipient(string $address)
158 $this->recipientAddress = $address;
164 * Returns the current headers
168 public function getHeaders(): array
170 return $this->headers;
178 * 'Header1' => ['value1', 'value2', ...],
179 * 'Header2' => ['value3', 'value4', ...],
183 * @param string[][] $headers
186 public function withHeaders(array $headers): MailBuilder
188 $this->headers = $headers;
194 * Adds a value to a header
196 * @param string $name The header name
197 * @param string $value The value of the header to add
201 public function addHeader(string $name, string $value)
203 $this->headers[$name][] = $value;
209 * Sets a value to a header (overwrites existing values)
211 * @param string $name The header name
212 * @param string $value The value to set
216 public function setHeader(string $name, string $value)
218 $this->headers[$name] = [$value];
224 * Build a email based on the given attributes
226 * @param bool $raw True, if the email shouldn't get extended by the default email-template
228 * @return IEmail A new generated email
230 * @throws UnprocessableEntityException
233 public function build(bool $raw = false)
235 if ((empty($this->recipientAddress)) &&
236 !empty($this->recipientUid)) {
237 $user = User::getById($this->recipientUid, ['email']);
239 if (!empty($user['email'])) {
240 $this->recipientAddress = $user['email'];
244 if (empty($this->recipientAddress)) {
245 throw new UnprocessableEntityException('Recipient address is missing.');
248 if (empty($this->senderAddress) || empty($this->senderName)) {
249 throw new UnprocessableEntityException('Sender address or name is missing.');
252 $this->senderNoReply = $this->senderNoReply ?? $this->senderAddress;
254 $msgHtml = $this->getHtmlMessage() ?? '';
257 // load the template for private message notifications
258 $tpl = Renderer::getMarkupTemplate('email/html.tpl');
259 $msgHtml = Renderer::replaceMacros($tpl, [
260 '$title' => $this->l10n->t('Friendica Notification'),
261 '$product' => App::PLATFORM,
262 '$htmlversion' => $msgHtml,
263 '$sitename' => $this->config->get('config', 'sitename'),
264 '$banner' => $this->config->get('system', 'email_banner',
265 $this->baseUrl . DIRECTORY_SEPARATOR . self::DEFAULT_EMAIL_BANNER),
271 $this->senderAddress,
272 $this->senderNoReply,
273 $this->recipientAddress,
274 $this->getSubject() ?? '',
276 $this->getPlaintextMessage() ?? '',
278 $this->recipientUid ?? null);