diff --git a/Documentation/ApiOverview/Mail/Index.rst b/Documentation/ApiOverview/Mail/Index.rst index 6fce57fc01..9a5f8df9af 100644 --- a/Documentation/ApiOverview/Mail/Index.rst +++ b/Documentation/ApiOverview/Mail/Index.rst @@ -438,82 +438,21 @@ like the following: .. index:: Mail; MailMessage .. _mail-mail-message: -Send email with `MailMessage` ------------------------------ +Send email of type `MailMessage` with an injected `MailerInterface` +------------------------------------------------------------------- -:php:`MailMessage` can be used to generate and send an email without using -Fluid: +.. versionchanged:: 14.0 + The following methods have been removed: -.. code-block:: php - :caption: EXT:site_package/Classes/Utility/MyMailUtility.php - - use Symfony\Component\Mime\Address; - use TYPO3\CMS\Core\Mail\MailMessage; - use TYPO3\CMS\Core\Utility\GeneralUtility; - - // Create the message - $mail = GeneralUtility::makeInstance(MailMessage::class); - - // Prepare and send the message - $mail - // Defining the "From" email address and name as an object - // (email clients will display the name) - ->from(new Address('john.doe@example.org', 'John Doe')) - - // Set the "To" addresses - ->to( - new Address('receiver@example.org', 'Max Mustermann'), - new Address('other@example.org') - ) - - // Give the message a subject - ->subject('Your subject') - - // Give it the text message - ->text('Here is the message itself') + * :php:`TYPO3\CMS\Core\Mail\MailMessage->send()` + * :php:`TYPO3\CMS\Core\Mail\MailMessage->isSent()` - // And optionally an HTML message - ->html('

Here is the message itself

') - - // Optionally add any attachments - ->attachFromPath('/path/to/my-document.pdf') - - // And finally send it - ->send() - ; - - - -Or, if you prefer, do not concatenate the calls: - -.. code-block:: php - :caption: EXT:site_package/Classes/Utility/MyMailUtility.php - - use Symfony\Component\Mime\Address; - use TYPO3\CMS\Core\Utility\GeneralUtility; - use TYPO3\CMS\Core\Mail\MailMessage; - - $mail = GeneralUtility::makeInstance(MailMessage::class); - $mail->from(new Address('john.doe@example.org', 'John Doe')); - $mail->to( - new Address('receiver@example.org', 'Max Mustermann'), - new Address('other@example.org') - ); - $mail->subject('Your subject'); - $mail->text('Here is the message itself'); - $mail->html('

Here is the message itself

'); - $mail->attachFromPath('/path/to/my-document.pdf'); - $mail->send(); - - -.. note:: - Before TYPO3 v10 the :php:`MailMessage` class only had methods like - :php:`->setTo()`, :php:`setFrom()`, :php:`->setSubject()` etc. - Now the class inherits from :php:`\Symfony\Component\Mime\Email` which - provides the methods from the example. To make migration from older TYPO3 - versions easier the previous methods still exist. The use of - :php:`MailMessage` in own extensions is recommended. +:php:`\TYPO3\CMS\Core\Mail\MailMessage` can be used to generate an email +without using Fluid. The email can then be sent via the injected interface +:php:`\TYPO3\CMS\Core\Mail\MailerInterface`. +.. literalinclude:: _codesnippets/_MyMailerController.php + :caption: EXT:site_package/Classes/Controller/MyMailerController.php .. index:: Mail; Attachments .. _mail-attachments: @@ -527,14 +466,13 @@ Attach files that exist in your file system: :caption: EXT:site_package/Classes/Utility/MyMailUtility.php // Attach file to message - $mail->attachFromPath('/path/to/documents/privacy.pdf'); + $email->attachFromPath('/path/to/documents/privacy.pdf'); // Optionally you can tell email clients to display a custom name for the file - $mail->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy'); + $email->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy'); // Alternatively attach contents from a stream - $mail->attach(fopen('/path/to/documents/contract.doc', 'r')); - + $email->attach(fopen('/path/to/documents/contract.doc', 'r')); .. index:: Mail; Inline media @@ -549,13 +487,13 @@ Add some inline media like images in an email: :caption: EXT:site_package/Classes/Utility/MyMailUtility.php // Get the image contents from a PHP resource - $mail->embed(fopen('/path/to/images/logo.png', 'r'), 'logo'); + $email->embed(fopen('/path/to/images/logo.png', 'r'), 'logo'); // Get the image contents from an existing file - $mail->embedFromPath('/path/to/images/signature.png', 'footer-signature'); + $email->embedFromPath('/path/to/images/signature.png', 'footer-signature'); // reference images using the syntax 'cid:' + "image embed name" - $mail->html(' ... ...'); + $email->html(' ... ...'); .. index:: @@ -577,39 +515,8 @@ It is possible to define a default email sender ("From:") in This is how you can use these defaults: -.. code-block:: php - :caption: EXT:site_package/Classes/Utility/MyMailUtility.php - - use TYPO3\CMS\Core\Mail\MailMessage; - use TYPO3\CMS\Core\Utility\GeneralUtility; - use TYPO3\CMS\Core\Utility\MailUtility; - - $from = MailUtility::getSystemFrom(); - $email = new MailMessage(); - - // As getSystemFrom() returns an array we need to use the setFrom method - $email->setFrom($from); - // ... - $email->send(); - -In case of the problem "Mails are not sent" in your extension, try to set a -``ReturnPath:``. Start as before but add: - -.. code-block:: php - :caption: EXT:site_package/Classes/Utility/MyMailUtility.php - - use TYPO3\CMS\Core\Utility\MailUtility; - - // You will get a valid email address from 'defaultMailFromAddress' or if - // not set from PHP settings or from system. - // If result is not a valid email address, the final result will be - // no-reply@example.org. - $returnPath = MailUtility::getSystemFromAddress(); - if ($returnPath != "no-reply@example.org") { - $mail->setReturnPath($returnPath); - } - $mail->send(); - +.. literalinclude:: _codesnippets/_MyMailerControllerDefault.php + :caption: EXT:site_package/Classes/Controller/MyMailerController.php .. index:: Mail; Custom mailer diff --git a/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerController.php b/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerController.php new file mode 100644 index 0000000000..e1850d2024 --- /dev/null +++ b/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerController.php @@ -0,0 +1,45 @@ +from(new Address('john.doe@example.org', 'John Doe')) + + // Set the "To" addresses + ->to( + new Address('receiver@example.org', 'Max Mustermann'), + new Address('other@example.org'), + ) + + // Give the message a subject + ->subject('Your subject') + + // Give it the text message + ->text('Here is the message itself') + + // And optionally an HTML message + ->html('

Here is the message itself

') + + // Optionally add any attachments + ->attachFromPath('/path/to/my-document.pdf'); + // And finally send it + $this->mailer->send($email); + } +} diff --git a/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerControllerDefault.php b/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerControllerDefault.php new file mode 100644 index 0000000000..fb6672dd79 --- /dev/null +++ b/Documentation/ApiOverview/Mail/_codesnippets/_MyMailerControllerDefault.php @@ -0,0 +1,22 @@ +setFrom(MailUtility::getSystemFrom()); + $this->mailer->send($email); + } +}