diff --git a/en/core-libraries/email.rst b/en/core-libraries/email.rst index 35a5201b05..fc3281770f 100644 --- a/en/core-libraries/email.rst +++ b/en/core-libraries/email.rst @@ -23,33 +23,33 @@ First of all, you should ensure the class is loaded:: After you've loaded ``Email``, you can send an email with the following:: $email = new Email('default'); - $email->setFrom(['me@example.com' => 'My Site']) - ->setTo('you@example.com') - ->setSubject('About') + $email->from(['me@example.com' => 'My Site']) + ->to('you@example.com') + ->subject('About') ->send('My message'); Since ``Email``'s setter methods return the instance of the class, you are able to set its properties with method chaining. -``Email`` has several methods for defining recipients - ``setTo()``, ``setCc()``, -``setBcc()``, ``addTo()``, ``addCc()`` and ``addBcc()``. The main difference being +``Email`` has several methods for defining recipients - ``to()``, ``cc()``, +``bcc()``, ``addTo()``, ``addCc()`` and ``addBcc()``. The main difference being that the first three will overwrite what was already set and the latter will just add more recipients to their respective field:: $email = new Email(); - $email->setTo('to@example.com', 'To Example'); + $email->to('to@example.com', 'To Example'); $email->addTo('to2@example.com', 'To2 Example'); // The email's To recipients are: to@example.com and to2@example.com - $email->setTo('test@example.com', 'ToTest Example'); + $email->to('test@example.com', 'ToTest Example'); // The email's To recipient is: test@example.com Choosing the Sender ------------------- When sending email on behalf of other people, it's often a good idea to define the -original sender using the Sender header. You can do so using ``setSender()``:: +original sender using the Sender header. You can do so using ``sender()``:: $email = new Email(); - $email->setSender('app@example.com', 'MyApp emailer'); + $email->sender('app@example.com', 'MyApp emailer'); .. note:: @@ -57,6 +57,9 @@ original sender using the Sender header. You can do so using ``setSender()``:: person's behalf. This prevents them from getting any messages about deliverability. +.. deprecated:: 3.4.0 + Use ``setSender()`` instead. + .. _email-configuration: Configuration @@ -73,11 +76,11 @@ By defining profiles and transports, you can keep your application code free of configuration data, and avoid duplication that makes maintenance and deployment more difficult. -To load a predefined configuration, you can use the ``setProfile()`` method or pass it +To load a predefined configuration, you can use the ``profile()`` method or pass it to the constructor of ``Email``:: $email = new Email(); - $email->setProfile('default'); + $email->profile('default'); // Or in constructor $email = new Email('default'); @@ -86,7 +89,7 @@ Instead of passing a string which matches a preset configuration name, you can also just load an array of options:: $email = new Email(); - $email->setProfile(['from' => 'me@example.org', 'transport' => 'my_custom']); + $email->profile(['from' => 'me@example.org', 'transport' => 'my_custom']); // Or in constructor $email = new Email(['from' => 'me@example.org', 'transport' => 'my_custom']); @@ -95,10 +98,14 @@ also just load an array of options:: The ``default`` email profile is automatically set when an ``Email`` instance is created. + +.. deprecated:: 3.4.0 + Use ``setProfile()`` instead of ``profile()``. + Configuring Transports ---------------------- -.. php:staticmethod:: setConfigTransport($key, $config) +.. php:staticmethod:: configTransport($key, $config) Email messages are delivered by transports. Different transports allow you to send messages via PHP's ``mail()`` function, SMTP servers, or not at all which @@ -109,12 +116,12 @@ change the configuration data. An example transport configuration looks like:: use Cake\Mailer\Email; // Sample Mail configuration - Email::setConfigTransport('default', [ + Email::configTransport('default', [ 'className' => 'Mail' ]); // Sample SMTP configuration. - Email::setConfigTransport('gmail', [ + Email::configTransport('gmail', [ 'host' => 'ssl://smtp.gmail.com', 'port' => 465, 'username' => 'my@gmail.com', @@ -128,7 +135,7 @@ enable TLS SMTP using the ``tls`` option:: use Cake\Mailer\Email; - Email::setConfigTransport('gmail', [ + Email::configTransport('gmail', [ 'host' => 'smtp.gmail.com', 'port' => 587, 'username' => 'my@gmail.com', @@ -153,13 +160,16 @@ The above configuration would enable TLS communication for email messages. Configuration options can also be provided as a :term:`DSN` string. This is useful when working with environment variables or :term:`PaaS` providers:: - Email::setConfigTransport('default', [ + Email::configTransport('default', [ 'url' => 'smtp://my@gmail.com:secret@smtp.gmail.com:465?tls=true', ]); When using a DSN string you can define any additional parameters/options as query string arguments. +.. deprecated:: 3.4.0 + Use ``setConfigTransport()`` instead of ``configTransport()``. + .. php:staticmethod:: dropTransport($key) Once configured, transports cannot be modified. In order to modify a transport @@ -174,38 +184,38 @@ Defining delivery profiles allows you to consolidate common email settings into re-usable profiles. Your application can have as many profiles as necessary. The following configuration keys are used: -- ``'from'``: Email or array of sender. See ``Email::setFrom()``. -- ``'sender'``: Email or array of real sender. See ``Email::setSender()``. -- ``'to'``: Email or array of destination. See ``Email::setTo()``. -- ``'cc'``: Email or array of carbon copy. See ``Email::setCc()``. -- ``'bcc'``: Email or array of blind carbon copy. See ``Email::setBcc()``. -- ``'replyTo'``: Email or array to reply the e-mail. See ``Email::setReplyTo()``. +- ``'from'``: Email or array of sender. See ``Email::from()``. +- ``'sender'``: Email or array of real sender. See ``Email::sender()``. +- ``'to'``: Email or array of destination. See ``Email::to()``. +- ``'cc'``: Email or array of carbon copy. See ``Email::cc()``. +- ``'bcc'``: Email or array of blind carbon copy. See ``Email::bcc()``. +- ``'replyTo'``: Email or array to reply the e-mail. See ``Email::replyTo()``. - ``'readReceipt'``: Email address or an array of addresses to receive the - receipt of read. See ``Email::setReadReceipt()``. + receipt of read. See ``Email::readReceipt()``. - ``'returnPath'``: Email address or an array of addresses to return if have - some error. See ``Email::setReturnPath()``. -- ``'messageId'``: Message ID of e-mail. See ``Email::setMessageId()``. -- ``'subject'``: Subject of the message. See ``Email::setSubject()``. + some error. See ``Email::returnPath()``. +- ``'messageId'``: Message ID of e-mail. See ``Email::messageId()``. +- ``'subject'``: Subject of the message. See ``Email::subject()``. - ``'message'``: Content of message. Do not set this field if you are using rendered content. - ``'priority'``: Priority of the email as numeric value (usually from 1 to 5 with 1 being the highest). -- ``'headers'``: Headers to be included. See ``Email::setHeaders()``. +- ``'headers'``: Headers to be included. See ``Email::headers()``. - ``'viewRender'``: If you are using rendered content, set the view classname. - See ``Email::setViewRenderer()``. + See ``Email::viewRender()``. - ``'template'``: If you are using rendered content, set the template name. See - ``Email::setTemplate()``. -- ``'theme'``: Theme used when rendering template. See ``Email::setTheme()``. + ``Email::template()``. +- ``'theme'``: Theme used when rendering template. See ``Email::theme()``. - ``'layout'``: If you are using rendered content, set the layout to render. If you want to render a template without layout, set this field to null. See - ``Email::setLayout()``. + ``Email::layout()``. - ``'viewVars'``: If you are using rendered content, set the array with - variables to be used in the view. See ``Email::setViewVars()``. -- ``'attachments'``: List of files to attach. See ``Email::setAttachments()``. -- ``'emailFormat'``: Format of email (html, text or both). See ``Email::setEmailFormat()``. + variables to be used in the view. See ``Email::viewVars()``. +- ``'attachments'``: List of files to attach. See ``Email::attachments()``. +- ``'emailFormat'``: Format of email (html, text or both). See ``Email::emailFormat()``. - ``'transport'``: Transport configuration name. See - :php:meth:`~Cake\\Mailer\\Email::setConfigTransport()`. + :php:meth:`~Cake\\Mailer\\Email::configTransport()`. - ``'log'``: Log level to log the email headers and message. ``true`` will use LOG_DEBUG. See also :ref:`logging-levels`. -- ``'helpers'``: Array of helpers used in the email template. ``Email::setHelpers()``. +- ``'helpers'``: Array of helpers used in the email template. ``Email::helpers()``. All these configurations are optional, except ``'from'``. @@ -213,7 +223,7 @@ All these configurations are optional, except ``'from'``. The values of above keys using Email or array, like from, to, cc, etc will be passed as first parameter of corresponding methods. The equivalent for: - ``Email::setFrom('my@example.com', 'My Site')`` + ``Email::from('my@example.com', 'My Site')`` would be defined as ``'from' => ['my@example.com' => 'My Site']`` in your config Setting Headers @@ -222,7 +232,10 @@ Setting Headers In ``Email`` you are free to set whatever headers you want. When migrating to use Email, do not forget to put the ``X-`` prefix in your headers. -See ``Email::setHeaders()`` and ``Email::addHeaders()`` +See ``Email::headers()`` and ``Email::addHeaders()`` + +.. deprecated:: 3.4.0 + Use ``setHeaders()`` instead of ``headers()``. Sending Templated Emails ======================== @@ -237,11 +250,11 @@ and elements just like normal views:: $email = new Email(); $email - ->setTemplate('welcome') - ->setLayout('fancy') - ->setEmailFormat('html') - ->setTo('bob@example.com') - ->setFrom('app@domain.com') + ->template('welcome') + ->layout('fancy') + ->emailFormat('html') + ->to('bob@example.com') + ->from('app@domain.com') ->send(); The above would use **src/Template/Email/html/welcome.ctp** for the view @@ -250,11 +263,11 @@ send multipart templated email messages as well:: $email = new Email(); $email - ->setTemplate('welcome') - ->setLayout('fancy') - ->setEmailFormat('both') - ->setTo('bob@example.com') - ->setFrom('app@domain.com') + ->template('welcome') + ->layout('fancy') + ->emailFormat('both') + ->to('bob@example.com') + ->from('app@domain.com') ->send(); This would use the following template files: @@ -267,10 +280,10 @@ This would use the following template files: When sending templated emails you have the option of sending either ``text``, ``html`` or ``both``. -You can set view variables with ``Email::setViewVars()``:: +You can set view variables with ``Email::viewVars()``:: $email = new Email('templated'); - $email->setViewVars(['value' => 12345]); + $email->viewVars(['value' => 12345]); In your email templates you can use these with:: @@ -278,9 +291,9 @@ In your email templates you can use these with:: You can use helpers in emails as well, much like you can in normal template files. By default only the ``HtmlHelper`` is loaded. You can load additional -helpers using the ``setHelpers()`` method:: +helpers using the ``helpers()`` method:: - $email->setHelpers(['Html', 'Custom', 'Text']); + $email->helpers(['Html', 'Custom', 'Text']); When setting helpers be sure to include 'Html' or it will be removed from the helpers loaded in your email template. @@ -289,45 +302,52 @@ If you want to send email using templates in a plugin you can use the familiar :term:`plugin syntax` to do so:: $email = new Email(); - $email->setTemplate('Blog.new_comment'); - $email->setLayout('Blog.auto_message'); + $email->template('Blog.new_comment'); + $email->layout('Blog.auto_message'); The above would use template and layout from the Blog plugin as an example. In some cases, you might need to override the default template provided by plugins. You can do this using themes by telling Email to use appropriate theme using -``Email::setTheme()`` method:: +``Email::theme()`` method:: $email = new Email(); - $email->setTemplate('Blog.new_comment'); - $email->setLayout('Blog.auto_message'); - $email->setTheme('TestTheme'); + $email->template('Blog.new_comment'); + $email->layout('Blog.auto_message'); + $email->theme('TestTheme'); This allows you to override the ``new_comment`` template in your theme without modifying the Blog plugin. The template file needs to be created in the following path: **src/Template/Plugin/TestTheme/Plugin/Blog/Email/text/new_comment.ctp**. +.. deprecated:: 3.4.0 + + * Use ``setTempalte()`` instead of ``template()``. + * Use ``setLayout()`` instead of ``layout()``. + * Use ``setTheme()`` instead of ``theme()``. + + Sending Attachments =================== -.. php:method:: setAttachments($attachments) +.. php:method:: attachments($attachments) You can attach files to email messages as well. There are a few different formats depending on what kind of files you have, and how you want the filenames to appear in the recipient's mail client: -1. String: ``$email->setAttachments('/full/file/path/file.png')`` will attach this +1. String: ``$email->attachments('/full/file/path/file.png')`` will attach this file with the name file.png. -2. Array: ``$email->setAttachments(['/full/file/path/file.png'])`` will have +2. Array: ``$email->attachments(['/full/file/path/file.png'])`` will have the same behavior as using a string. 3. Array with key: - ``$email->setAttachments(['photo.png' => '/full/some_hash.png'])`` will + ``$email->attachments(['photo.png' => '/full/some_hash.png'])`` will attach some_hash.png with the name photo.png. The recipient will see photo.png, not some_hash.png. 4. Nested arrays:: - $email->setAttachments([ + $email->attachments([ 'photo.png' => [ 'file' => '/full/some_hash.png', 'mimetype' => 'image/png', @@ -350,23 +370,29 @@ you want the filenames to appear in the recipient's mail client: a string using the ``data`` option. This allows you to attach files without needing file paths to them. +.. deprecated:: 3.4.0 + Use ``setAttachments()`` instead of ``attachments()``. + Using Transports ================ Transports are classes designed to send the e-mail over some protocol or method. CakePHP supports the Mail (default), Debug and SMTP transports. -To configure your method, you must use the :php:meth:`Cake\\Mailer\\Email::setTransport()` +To configure your method, you must use the :php:meth:`Cake\\Mailer\\Email::transport()` method or have the transport in your configuration:: $email = new Email(); - // Use a named transport already configured using Email::setConfigTransport() - $email->setTransport('gmail'); + // Use a named transport already configured using Email::configTransport() + $email->transport('gmail'); // Use a constructed object. $transport = new DebugTransport(); - $email->setTransport($transport); + $email->transport($transport); + +.. deprecated:: 3.4.0 + Use ``setTransport()`` instead of ``transport()``. Creating Custom Transports -------------------------- @@ -390,7 +416,7 @@ transport). To start off your file should look like:: } You must implement the method ``send(Email $email)`` with your custom logic. -Optionally, you can implement the ``setConfig($config)`` method. ``setConfig()`` is +Optionally, you can implement the ``config($config)`` method. ``config()`` is called before send() and allows you to accept user configurations. By default, this method puts the configuration in protected attribute ``$_config``. @@ -405,7 +431,7 @@ Example:: Relaxing Address Validation Rules --------------------------------- -.. php:method:: setEmailPattern($pattern) +.. php:method:: emailPattern($pattern) If you are having validation issues when sending to non-compliant addresses, you can relax the pattern used to validate email addresses. This is sometimes @@ -415,7 +441,10 @@ necessary when dealing with some Japanese ISP's:: // Relax the email pattern, so you can send // to non-conformant addresses. - $email->setEmailPattern($newPattern); + $email->emailPattern($newPattern); + +.. deprecated:: 3.4.0 + Use ``setEmailPattern()`` instead of ``emailPattern()``. Sending Messages Quickly @@ -458,12 +487,15 @@ When sending emails within a CLI script (Shells, Tasks, ...) you should manually set the domain name for Email to use. It will serve as the host name for the message id (since there is no host name in a CLI environment):: - $email->setDomain('www.example.org'); + $email->domain('www.example.org'); // Results in message ids like ```` (valid) // Instead of ``` (invalid) A valid message id can help to prevent emails ending up in spam folders. +.. deprecated:: 3.4.0 + Use ``setDomain()`` instead of ``domain()``. + Creating Reusable Emails ======================== @@ -489,17 +521,17 @@ following:: public function welcome($user) { $this - ->setTo($user->email) - ->setSubject(sprintf('Welcome %s', $user->name)) - ->setTemplate('welcome_mail') // By default template with same name as method name is used. - ->setLayout('custom'); + ->to($user->email) + ->subject(sprintf('Welcome %s', $user->name)) + ->template('welcome_mail') // By default template with same name as method name is used. + ->layout('custom'); } public function resetPassword($user) { $this - ->setTo($user->email) - ->setSubject('Reset password') + ->to($user->email) + ->subject('Reset password') ->set(['token' => $user->token]); } }