FastSitePHP\Net\Email

Email Message API

This classes is used for sending emails along with the [SmtpClient] class. See docs in [SmtpClient] for more.

In general this classes provides getter/setter functions for common email fields and the format of email addresses and header fields are validated when set. Unicode Email Addresses are supported when [allowUnicodeEmails(true)] is called.

源代码

相关链接

• https://en.wikipedia.org/wiki/MIME
• https://en.wikipedia.org/wiki/Email_address

示例代码

// Define Email Settings
$from = 'noreply@example.com';
$to = 'user.name@example.com';
$subject = 'Email Test from FastSitePHP at ' . date(DATE_RFC2822);
$body = '<h1>Email Title</h1><p style="color:blue;">This is a test.</p>';

// Create an Email Object
$email = new \FastSitePHP\Net\Email($from, $to, $subject, $body);

// The Email Class also has many additional settings and can be created
// without specifying any parameters. When setting [From] or [Reply-To]
// email addresses on of the following formats can be used:
//   String: 'Email Address'
//   Array: ['Email', 'Name']
// And when specifying who to send email to any of the formats can be used:
//   String 'Email Address'
//   Array: ['Email', 'Name']
//   Array: ['Email Address 1', 'Email Address 2', '...']
/*
$email = new \FastSitePHP\Net\Email();
$email
    ->from(['noreply@example.com', 'No Reply'])
    ->replyTo('test@example.com')
    ->to(['email1@example.com', 'email2@example.com'])
    ->cc('email3@example.com')
    ->bcc('email4@example.com')
    ->priority('High')
    ->header('X-Transaction-ID', '123abc');
*/

// File attachements are also supported:
//
// $email->attachFile($file_path);

// SMTP Servers that support Unicode Emails can use [allowUnicodeEmails(true)].
// When used the SMTP Client sends a SMTPUTF8 option if the server supports it.
//
// $email->allowUnicodeEmails(true)->from('无回复@example.com');

// SMTP Settings
$host = 'smtp.example.com';
$port = 25;
$auth_user = null;
$auth_pass = null;

// Create SMTP Client and Send Email.
// Once the variable for the SMTP Client is not longer used (or set to null)
// then it automatically sends a 'QUIT' command to the SMTP Server and closes
// the connection.
$smtp = new \FastSitePHP\Net\SmtpClient($host, $port);
if ($auth_user !== null) {
    $smtp->auth($auth_user, $auth_pass);
}
$smtp->send($email);
$smtp = null;

// Additional options can be specified for timeout (in seconds) and for logging
$timeout = 2;
$debug_callback = function($message) {
    echo '[' . date('H:i:s') . '] ' . trim($message) . "\n";
};

// The [SmtpClient] Class also supports an easy to use API for communicating
// with SMTP Servers. In this example Gmail is used and several commands are
// performed. Messages are logged to the [$debug_callback] function.
$host = 'smtp.gmail.com';
$port = 587;
$smtp2 = new \FastSitePHP\Net\SmtpClient($host, $port, $timeout, $debug_callback);
$smtp2->help();
$smtp2->noop();
$smtp2->quit();
$smtp2->close();

// One or more emails can also be sent using App Config Values or System
// Enviroment Variables. This type of setup can be used to prevent sensitive
// authentication info from being saved with the main code logic.
/*
$app->config['SMTP_HOST'] = $host;
$app->config['SMTP_PORT'] = $port;
$app->config['SMTP_TIMEOUT'] = $timeout;
$app->config['SMTP_USER'] = $auth_user;
$app->config['SMTP_PASSWORD'] = $auth_pass;

\FastSitePHP\Net\SmtpClient::sendEmails([$email]);
*/

方法

__construct($from = null, $to = null, $subject = null, $body = null)

Class Constructor Key email fields can be defined when an object is created

from($new_value = null)

Get or set the [From] Email Address, this function accepts a string with an Email address or an array with ['Email', 'Name'].

返回类型: null | string | $this

replyTo($new_value = null)

Get or set the [Reply-To] Email Address, this function accepts a string with an Email address or an array with ['Email', 'Name'].

[Reply-To] does not show by default when viewing an Email, however if a user clicks [Reply] then it appears. This is useful if you want to send the email from a no-reply email but still allow a user to reply.

返回类型: null | string | $this

to($new_value = null)

Get or set [To] Email Addresses. This function can set one or many email addresses at the same time.

Accepted options:
    Null - Returns a list of Email Address Strings to Send to.
    Array of [Email Address Strings]
    'email address'
    Array with ['Email', 'Name']

返回类型: array | $this

cc($new_value = null)

Get or set [CC] Email Addresses. This function uses the same format as the [to()] function.

返回类型: array | $this

bcc($new_value = null)

Get or set [BCC] Email Addresses. This function uses the same format as the [to()] function.

返回类型: array | $this

subject($new_value = null)

Get or set the Subject of the email.

返回类型: null | string | $this

body($new_value = null)

Get or set the Body of the email.

返回类型: null | string | $this

isHtml($new_value = null)

Get or set the type of email to send:
    HTML = true (Default)
    Text = false

返回类型: bool | $this

priority($new_value = null)

Sends both [X-Priority] and [Importance] headers. When setting specify one of ['High', 'Normal', or 'Low'].

返回类型: null | string | $this

header($name, $new_value = null)

Get or set a Custom Email Header

返回类型: $this | null | string

• https://www.iana.org/assignments/message-headers/message-headers.xhtml

safeHeaderNames($new_value = null)

By default only characters [A-Z], [a-z], [0-9], and [-] are allowed for Custom Header Field Names when using the [header()] function. Setting this value to false will allow any character other than New-Lines (CR, LF), Null (char 0), and [:] to be used.

返回类型: bool | $this

attachFile($file_path)

Add a file attachment to the email.

IMPORTANT - File paths should generally not be passed as user parameters because a user could specify files other than the intended file. If an App does need to allow the user to specify a file then the code should be carefully reviewed and tested for security.

Typical usage of this feature would be having a script generate a report and then the report gets attached to an email sent to users on an automated schedule.

返回类型: $this

allowUnicodeEmails($new_value = null)

Set to true to allow Unicode Emails to be sent. When the [SmtpClient] Class sends the email it checks this and if set to [true] sends the option SMTPUTF8 if supported by the SMTP Server.

Setting this value is only required if using Unicode Email Addresses and it is not required for sending content with Unicode characters (Subject, Body, Attachement File Names, Headers, etc).

This function defaults to false so that email address validation uses strict rules.

返回类型: bool | $this

encodeFileNames($new_value = null)

Get or set whether attached file names should be UTF-8 encoded. Defaults to false.

If set to true then the following MIME Header:
  "Content-Disposition: attachment; filename*=UTF-8''{encoded_name}" is included in the email message. For modern SMTP Servers and widely used email providers this is generally not needed even when the file name includes Unicode Characters.

返回类型: bool | $this

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
• https://tools.ietf.org/html/rfc5987

message()

Return the Email message as a String encoded as UTF-8 using Base64 for the [SmtpClient] to send with the DATA command. This function is public but generally only needs to be called internally by the [SmtpClient] Class.

返回类型: string