CakePHP Email class.
This class is used for sending Internet Message Format based on the standard outlined in http://www.rfc-editor.org/rfc/rfc2822.txt
Configuration for Email is managed by Email::config() and Email::configTransport(). Email::config() can be used to add or read a configuration profile for Email instances. Once made configuration profiles can be used to re-use across various email messages your application sends.
__construct( array|string|null $config null )
Constructor
$config
optional null _addEmail( string $varName , string|array $email , string $name )
Add email
$varName
$email
$name
mixed
InvalidArgumentException
_applyConfig( string|array $config )
Apply the config to an instance
$config
InvalidArgumentException
_attachFiles( string|null $boundary null )
Attach non-embedded files by adding file contents inside boundaries.
$boundary
optional null array
_attachInlineFiles( string|null $boundary null )
Attach inline/embedded files to the message.
$boundary
optional null array
_checkViewVars( mixed $item , string $key )
Iterates through hash to clean up and normalize.
$item
$key
_constructTransport( string $name )
Build a transport instance from configuration data.
$name
Cake\Mailer\AbstractTransport
InvalidArgumentException
_encode( string $text )
Encode the specified string using the current charset
$text
string
_encodeString( string $text , string $charset )
Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists
$text
$charset
string
_formatAddress( array $address )
Format addresses
If the address contains non alphanumeric/whitespace characters, it will be quoted as characters like :
and ,
are known to cause issues in address header fields.
$address
array
_getContentTransferEncoding( )
Return the Content-Transfer Encoding value based on the set charset
string
_getContentTypeCharset( )
Return charset value for Content-Type.
Checks fallback/compatibility types which include workarounds for legacy japanese character sets.
string
_getTypes( )
Gets the text body types that are in this email message
array
_logDelivery( array $contents )
Log the email message delivery.
$contents
_readFile( string $path )
Read the file contents and return a base64 version of the file contents.
$path
string
_render( array $content )
Render the body of the email.
$content
array
_renderTemplates( string $content )
Build and set all the view properties needed to render the templated emails. If there is no template set, the $content will be returned in a hash of the text content types for the email.
$content
array
_setEmail( string $varName , string|array $email , string $name )
Set email
$varName
$email
$name
mixed
InvalidArgumentException
_setEmailSingle( string $varName , string|array $email , string $name , string $throwMessage )
Set only 1 email
$varName
$email
$name
$throwMessage
mixed
InvalidArgumentException
_validateEmail( string $email )
Validate email address
$email
InvalidArgumentException
_wrap( string $message , integer $wrapLength Cake\Mailer\Email::LINE_LENGTH_MUST )
Wrap the message to follow the RFC 2822 - 2.1.1
$message
$wrapLength
optional Cake\Mailer\Email::LINE_LENGTH_MUST
array
addAttachments( string|array $attachments )
Add attachments
$attachments
mixed
InvalidArgumentException
Cake\Mailer\Email::attachments()
addBcc( string|array $email , string|null $name null )
Add Bcc
$email
$name
optional null mixed
addCc( string|array $email , string|null $name null )
Add Cc
$email
$name
optional null mixed
addHeaders( array $headers )
Add header for the message
$headers
mixed
addTo( string|array $email , string|null $name null )
Add To
$email
$name
optional null mixed
attachments( string|array|null $attachments null )
Add attachments to the email message
Attachments can be defined in a few forms depending on how much control you need:
Attach a single file:
$email->attachments('path/to/file');
Attach a file with a different filename:
$email->attachments(['custom_name.txt' => 'path/to/file.txt']);
Attach a file and specify additional properties:
$email->attachments(['custom_name.png' => [ 'file' => 'path/to/file', 'mimetype' => 'image/png', 'contentId' => 'abc123', 'contentDisposition' => false ] ]);
Attach a file from string and specify additional properties:
$email->attachments(['custom_name.png' => [ 'data' => file_get_contents('path/to/file'), 'mimetype' => 'image/png' ] ]);
The contentId
key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" />
to display the image inline.
The contentDisposition
key allows you to disable the Content-Disposition
header, this can improve attachment compatibility with outlook email clients.
$attachments
optional null array|$this
InvalidArgumentException
bcc( string|array|null $email null , string|null $name null )
Bcc
$email
optional null $name
optional null array|$this
cc( string|array|null $email null , string|null $name null )
Cc
$email
optional null $name
optional null array|$this
charset( string|null $charset null )
Charset setter/getter
$charset
optional null string
configTransport( string|array $key , array|Cake\Mailer\AbstractTransport|null $config null )
Add or read transport configuration.
Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.
When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.
The className
is used to define the class to use for a transport. It can either be a short name, or a fully qualified classname
$key
Cake\Mailer\AbstractTransport
|null $config
optional null array|null
BadMethodCallException
configuredTransport( )
Returns an array containing the named transport configurations
array
createFromArray( array $config )
Configures an email instance object from serialized config.
$config
Cake\Mailer\Email
deliver( string|array $to null , string $subject null , string|array $message null , string|array $transportConfig 'fast' , boolean $send true )
Static method to fast create an instance of \Cake\Mailer\Email
$to
optional null $subject
optional null $message
optional null $transportConfig
optional 'fast' $send
optional true Cake\Mailer\Email
InvalidArgumentException
domain( string|null $domain null )
Domain as top level (the part after @)
$domain
optional null string|$this
dropTransport( string $key )
Delete transport configuration.
$key
emailFormat( string|null $format null )
Email format
$format
optional null string|$this
InvalidArgumentException
emailPattern( string|boolean|null $regex false )
EmailPattern setter/getter
$regex
optional false string|$this
from( string|array|null $email null , string|null $name null )
From
$email
optional null $name
optional null array|$this
InvalidArgumentException
getHeaders( array $include [] )
Get list of headers
from
replyTo
readReceipt
returnPath
to
cc
bcc
subject
$include
optional [] array
headerCharset( string|null $charset null )
HeaderCharset setter/getter
$charset
optional null string
helpers( array|null $helpers null )
Helpers to be used in render
$helpers
optional null array|$this
jsonSerialize( )
Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.
It has certain limitations for viewVars that are good to know:
- ORM\Query executed and stored as resultset - SimpleXmlElements stored as associative array - Exceptions stored as strings - Resources, \Closure and \PDO are not supported.
array
Exception
JsonSerializable::jsonSerialize()
message( string|null $type null )
Get generated message (used by transport classes)
$type
optional null string|array
messageId( boolean|string|null $message null )
Message-ID
$message
optional null boolean|string|$this
InvalidArgumentException
profile( null|string|array $config null )
Get/Set the configuration profile to use for this instance.
$config
optional null string|array|$this
readReceipt( string|array|null $email null , string|null $name null )
Read Receipt (Disposition-Notification-To header)
$email
optional null $name
optional null array|$this
InvalidArgumentException
replyTo( string|array|null $email null , string|null $name null )
Reply-To
$email
optional null $name
optional null array|$this
InvalidArgumentException
reset( )
Reset all the internal variables to be able to send out a new email.
mixed
returnPath( string|array|null $email null , string|null $name null )
Return Path
$email
optional null $name
optional null array|$this
InvalidArgumentException
send( string|array|null $content null )
Send an email using the specified content, template and layout
$content
optional null array
BadMethodCallException
sender( string|array|null $email null , string|null $name null )
Sender
$email
optional null $name
optional null array|$this
InvalidArgumentException
serialize( )
Serializes the Email object.
string
Serializable::serialize()
setHeaders( array $headers )
Sets headers for the message
$headers
mixed
subject( string|null $subject null )
Get/Set Subject.
$subject
optional null string|$this
template( boolean|string $template false , boolean|string $layout false )
Template and layout
$template
optional false $layout
optional false array|$this
theme( string|null $theme null )
Theme to use when rendering
$theme
optional null string|$this
to( string|array|null $email null , string|null $name null )
To
$email
optional null $name
optional null array|$this
transport( string|Cake\Mailer\AbstractTransport|null $name null )
Get/set the transport.
When setting the transport you can either use the name of a configured transport or supply a constructed transport.
Cake\Mailer\AbstractTransport
|null $name
optional null Cake\Mailer\AbstractTransport|$this
LogicException
InvalidArgumentException
unserialize( string $data )
Unserializes the Email object.
$data
Cake\Mailer\Email
Serializable::unserialize()
viewRender( string|null $viewClass null )
View class for render
$viewClass
optional null string|$this
viewVars( array|null $viewVars null )
Variables to be set on render
$viewVars
optional null array|$this
config( string|array $key , array $config null )
This method can be used to define configuration adapters for an application or read existing configuration.
To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.
Adapters will not be constructed until the first operation is done.
Assuming that the class' name is Cache
the following scenarios are supported:
Reading config data back:
Cache::config('default');
Setting a cache engine up.
Cache::config('default', $settings);
Injecting a constructed adapter in:
Cache::config('default', $instance);
Configure multiple adapters at once:
Cache::config($arrayOfConfig);
$key
$config
optional null array|null
BadMethodCallException
configured( )
Returns an array containing the named configurations
array
drop( string $config )
Drops a constructed adapter.
If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.
If the implementing objects supports a $_registry
object the named configuration will also be unloaded from the registry.
$config
boolean
dsnClassMap( array $map null )
Returns or updates the DSN class map for this class
$map
optional null array
parseDsn( string $dsn )
Parses a DSN into a valid connection configuration
This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:
$dsn = 'mysql://user:pass@localhost/database?'; $config = ConnectionManager::parseDsn($dsn); $dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS'; $config = Log::parseDsn($dsn); $dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null'; $config = Email::parseDsn($dsn); $dsn = 'file:///?className=\My\Cache\Engine\FileEngine'; $config = Cache::parseDsn($dsn); $dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/'; $config = Cache::parseDsn($dsn);
For all classes, the value of scheme
is set as the value of both the className
unless they have been otherwise specified.
Note that querystring arguments are also parsed and set as values in the returned configuration.
$dsn
array
InvalidArgumentException
createView( string|null $viewClass null )
Constructs the view class instance based on the current configuration.
$viewClass
optional null Cake\View\View
Cake\View\Exception\MissingViewException
set( string|array $name , string|array|null|boolean $value null )
Saves a variable or an associative array of variables for use inside a template.
$name
$value
optional null mixed
viewBuilder( )
Get the view builder being used.
Cake\View\ViewBuilder
viewOptions( string|array|null $options null , boolean $merge true )
Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView()
.
$options
optional null $merge
optional true true
.array
string | EMAIL_PATTERN Holds the regex pattern for email validation | '/^((?:[\p{L}0-9.!#$%&\'*+\/=?^_`{|}~-]+)*@[\p{L}0-9-.]+)$/ui' |
integer | LINE_LENGTH_MUST Line length - no must more - RFC 2822 - 2.1.1 | 998 |
integer | LINE_LENGTH_SHOULD Line length - no should more - RFC 2822 - 2.1.1 | 78 |
string | MESSAGE_HTML Type of message - HTML | 'html' |
string | MESSAGE_TEXT Type of message - TEXT | 'text' |
public string
The name of default View class.
$this->viewBuilder()->className()
instead.null
© 2005–2016 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
http://api.cakephp.org/3.1/class-Cake.Mailer.Email.html