annotate core/lib/Drupal/Component/Utility/Mail.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@17 1 <?php
Chris@17 2
Chris@17 3 namespace Drupal\Component\Utility;
Chris@17 4
Chris@17 5 /**
Chris@17 6 * Provides helpers to ensure emails are compliant with RFCs.
Chris@17 7 *
Chris@17 8 * @ingroup utility
Chris@17 9 */
Chris@17 10 class Mail {
Chris@17 11
Chris@17 12 /**
Chris@17 13 * RFC-2822 "specials" characters.
Chris@17 14 */
Chris@17 15 const RFC_2822_SPECIALS = '()<>[]:;@\,."';
Chris@17 16
Chris@17 17 /**
Chris@17 18 * Return a RFC-2822 compliant "display-name" component.
Chris@17 19 *
Chris@17 20 * The "display-name" component is used in mail header "Originator" fields
Chris@17 21 * (From, Sender, Reply-to) to give a human-friendly description of the
Chris@17 22 * address, i.e. From: My Display Name <xyz@example.org>. RFC-822 and
Chris@17 23 * RFC-2822 define its syntax and rules. This method gets as input a string
Chris@17 24 * to be used as "display-name" and formats it to be RFC compliant.
Chris@17 25 *
Chris@17 26 * @param string $string
Chris@17 27 * A string to be used as "display-name".
Chris@17 28 *
Chris@17 29 * @return string
Chris@17 30 * A RFC compliant version of the string, ready to be used as
Chris@17 31 * "display-name" in mail originator header fields.
Chris@17 32 */
Chris@17 33 public static function formatDisplayName($string) {
Chris@17 34 // Make sure we don't process html-encoded characters. They may create
Chris@17 35 // unneeded trouble if left encoded, besides they will be correctly
Chris@17 36 // processed if decoded.
Chris@17 37 $string = Html::decodeEntities($string);
Chris@17 38
Chris@17 39 // If string contains non-ASCII characters it must be (short) encoded
Chris@17 40 // according to RFC-2047. The output of a "B" (Base64) encoded-word is
Chris@17 41 // always safe to be used as display-name.
Chris@17 42 $safe_display_name = Unicode::mimeHeaderEncode($string, TRUE);
Chris@17 43
Chris@17 44 // Encoded-words are always safe to be used as display-name because don't
Chris@17 45 // contain any RFC 2822 "specials" characters. However
Chris@17 46 // Unicode::mimeHeaderEncode() encodes a string only if it contains any
Chris@17 47 // non-ASCII characters, and leaves its value untouched (un-encoded) if
Chris@17 48 // ASCII only. For this reason in order to produce a valid display-name we
Chris@17 49 // still need to make sure there are no "specials" characters left.
Chris@17 50 if (preg_match('/[' . preg_quote(Mail::RFC_2822_SPECIALS) . ']/', $safe_display_name)) {
Chris@17 51
Chris@17 52 // If string is already quoted, it may or may not be escaped properly, so
Chris@17 53 // don't trust it and reset.
Chris@17 54 if (preg_match('/^"(.+)"$/', $safe_display_name, $matches)) {
Chris@17 55 $safe_display_name = str_replace(['\\\\', '\\"'], ['\\', '"'], $matches[1]);
Chris@17 56 }
Chris@17 57
Chris@17 58 // Transform the string in a RFC-2822 "quoted-string" by wrapping it in
Chris@17 59 // double-quotes. Also make sure '"' and '\' occurrences are escaped.
Chris@17 60 $safe_display_name = '"' . str_replace(['\\', '"'], ['\\\\', '\\"'], $safe_display_name) . '"';
Chris@17 61
Chris@17 62 }
Chris@17 63
Chris@17 64 return $safe_display_name;
Chris@17 65 }
Chris@17 66
Chris@17 67 }