class Mail in Drupal 9

Provides helpers to ensure emails are compliant with RFCs.

Hierarchy

• class \Drupal\Component\Utility\Mail

Related topics

Utility classes and functions

Overview of utility classes and functions for developers.

1 file declares its use of Mail

MailTest.php in core/tests/Drupal/Tests/Component/Utility/MailTest.php

1 string reference to 'Mail'

core.data_types.schema.yml in core/config/schema/core.data_types.schema.yml

core/config/schema/core.data_types.schema.yml

File

core/lib/Drupal/Component/Utility/Mail.php, line 12

Namespace

Drupal\Component\Utility

class Mail {

  /**
   * RFC-2822 "specials" characters.
   */
  const RFC_2822_SPECIALS = '()<>[]:;@\\,."';

  /**
   * Return a RFC-2822 compliant "display-name" component.
   *
   * The "display-name" component is used in mail header "Originator" fields
   * (From, Sender, Reply-to) to give a human-friendly description of the
   * address, i.e. From: My Display Name <[e-mail]>. RFC-822 and
   * RFC-2822 define its syntax and rules. This method gets as input a string
   * to be used as "display-name" and formats it to be RFC compliant.
   *
   * @param string $string
   *   A string to be used as "display-name".
   *
   * @return string
   *   A RFC compliant version of the string, ready to be used as
   *   "display-name" in mail originator header fields.
   *
   * @deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use
   *   \Symfony\Component\Mime\Header\MailboxHeader instead.
   *
   * @see https://www.drupal.org/node/3207439
   */
  public static function formatDisplayName($string) {
    @trigger_error('\\Drupal\\Component\\Utility\\Mail::formatDisplayName() is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use \\Symfony\\Component\\Mime\\Header\\MailboxHeader instead. See https://www.drupal.org/node/3207439', E_USER_DEPRECATED);

    // Make sure we don't process html-encoded characters. They may create
    // unneeded trouble if left encoded, besides they will be correctly
    // processed if decoded.
    $string = Html::decodeEntities($string);

    // If string contains non-ASCII characters it must be (short) encoded
    // according to RFC-2047. The output of a "B" (Base64) encoded-word is
    // always safe to be used as display-name.
    $safe_display_name = Unicode::mimeHeaderEncode($string, TRUE);

    // Encoded-words are always safe to be used as display-name because don't
    // contain any RFC 2822 "specials" characters. However
    // Unicode::mimeHeaderEncode() encodes a string only if it contains any
    // non-ASCII characters, and leaves its value untouched (un-encoded) if
    // ASCII only. For this reason in order to produce a valid display-name we
    // still need to make sure there are no "specials" characters left.
    if (preg_match('/[' . preg_quote(Mail::RFC_2822_SPECIALS) . ']/', $safe_display_name)) {

      // If string is already quoted, it may or may not be escaped properly, so
      // don't trust it and reset.
      if (preg_match('/^"(.+)"$/', $safe_display_name, $matches)) {
        $safe_display_name = str_replace([
          '\\\\',
          '\\"',
        ], [
          '\\',
          '"',
        ], $matches[1]);
      }

      // Transform the string in a RFC-2822 "quoted-string" by wrapping it in
      // double-quotes. Also make sure '"' and '\' occurrences are escaped.
      $safe_display_name = '"' . str_replace([
        '\\',
        '"',
      ], [
        '\\\\',
        '\\"',
      ], $safe_display_name) . '"';
    }
    return $safe_display_name;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
Mail::formatDisplayName Deprecated	public static	function	Return a RFC-2822 compliant "display-name" component.
Mail::RFC_2822_SPECIALS		constant	RFC-2822 "specials" characters.