diff --git a/.github/workflows/codecov.yml b/.github/workflows/codecov.yml index 32a1a00..c0fbc53 100644 --- a/.github/workflows/codecov.yml +++ b/.github/workflows/codecov.yml @@ -18,6 +18,7 @@ jobs: - "8.2" - "8.3" - "8.4" + - "8.5" steps: - name: Checkout diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index dc4b6fa..9976515 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -18,6 +18,7 @@ jobs: - "8.2" - "8.3" - "8.4" + - "8.5" steps: - name: Checkout diff --git a/.laminas-ci.json b/.laminas-ci.json index a824eae..29216fa 100644 --- a/.laminas-ci.json +++ b/.laminas-ci.json @@ -1,3 +1,3 @@ -{ - "backwardCompatibilityCheck": true -} +{ + "backwardCompatibilityCheck": true +} diff --git a/README.md b/README.md index 33e7754..c0c6c8d 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Documentation is available at: https://docs.dotkernel.org/dot-mail/. ## Badges ![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-mail) -![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-mail/5.3.0) +![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-mail/5.4.0) [![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/issues) [![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/network) @@ -51,7 +51,8 @@ return [ ### Mail - ESMTP -If you want your application to send mails on e.g. registration, contact, then edit the file `config/autoload/mail.local.php`. Set the `transport`, `message_options` and `smtp_options` keys like below. +If you want your application to send mails on e.g., registration, contact, then edit the file `config/autoload/mail.local.php`. +Set the `transport`, `message_options` and `smtp_options` keys like below. Under `message_options` key: @@ -94,17 +95,19 @@ return [ In `config/autoload/local.php` add under `contact` => `message_receivers` => `to` key *string* values with the emails that should receive contact messages -> Note: **Please add at least 1 email address in order for contact message to reach someone** +> **Please add at least one email address in order for a contact message to reach someone** Also feel free to add as many cc as you want under `contact` => `message_receivers` => `cc` key ### Sending an e-mail -Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. +Below is an example of how to use the email in the most basic way. You can add your own code to it, e.g., to get the user data from a User object or from a config file, to use a template for the body. -Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. +Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. +Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. -The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. See the `Testing if an e-mail message is valid` section below. +The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. +See the `Testing if an e-mail message is valid` section below. ```php public function sendBasicMail() @@ -117,7 +120,8 @@ public function sendBasicMail() } ``` -It's optional, but recommended to call the above function in a `try-catch` block to display helpful error messages. The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. +It's optional but recommended to call the above function in a `try-catch` block to display helpful error messages. +The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. ```php try { @@ -132,7 +136,7 @@ try { ### Testing if an e-mail message is valid -After sending an e-mail you can check if the message was valid or not. +After sending an e-mail, you can check if the message was valid or not. The `$this->mailService->send()->isValid()` method call will return a boolean value. If the returned result is `true`, the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using `$this->mailService->send()->getMessage()`. @@ -152,7 +156,8 @@ if (! $result->isValid()) { ### Logging outgoing emails -Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. +Optionally, you can keep a log of each successfully sent email. +This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: @@ -160,7 +165,7 @@ Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {"subject":"Test subject","to":["Test Account "],"cc":[],"bcc":[]}. ``` -In order to enable it, make sure that your `config/autoload/mail.local.php` has the below `log` configuration under the `dot_mail` key: +To enable it, make sure that your `config/autoload/mail.local.php` has the below `log` configuration under the `dot_mail` key: ```php . We will work with you to -verify the vulnerability and patch it. +If you have encountered a potential security vulnerability in this project, please report it to us at . +We will work with you to verify the vulnerability and patch it. When reporting issues, please provide the following information: @@ -22,19 +19,12 @@ When reporting issues, please provide the following information: - A description indicating how to reproduce the issue - A summary of the security vulnerability and impact -We request that you contact us via the email address above and give the -project contributors a chance to resolve the vulnerability and issue a new -release prior to any public exposure; this helps protect the project's -users, and provides them with a chance to upgrade and/or update in order to -protect their applications. - +We request that you contact us via the email address above and give the project contributors a chance to resolve the vulnerability and issue a new release prior to any public exposure; +this helps protect the project's users and provides them with a chance to upgrade and/or update to protect their applications. ## Policy If we verify a reported security vulnerability, our policy is: -- We will patch the current release branch, as well as the immediate prior minor - release branch. - -- After patching the release branches, we will immediately issue new security - fix releases for each patched release branch. +- We will patch the current release branch, as well as the immediate prior minor release branch. +- After patching the release branches, we will immediately issue new security fix releases for each patched release branch. diff --git a/composer.json b/composer.json index b82c06b..033d71b 100644 --- a/composer.json +++ b/composer.json @@ -27,7 +27,7 @@ } }, "require": { - "php": "~8.2.0 || ~8.3.0 || ~8.4.0", + "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0", "ext-fileinfo": "*", "ext-json": "*", "dotkernel/dot-event": "^4.0", @@ -59,7 +59,7 @@ ], "cs-check": "phpcs", "cs-fix": "phpcbf", - "test": "phpunit --colors=always", - "static-analysis": "phpstan analyse --memory-limit 1G" + "static-analysis": "phpstan analyse --memory-limit 1G", + "test": "phpunit --colors=always" } } diff --git a/docs/book/v4/configuration.md b/docs/book/v4/configuration.md index 53e5b0c..8a6f757 100644 --- a/docs/book/v4/configuration.md +++ b/docs/book/v4/configuration.md @@ -50,11 +50,9 @@ Using `Laminas\Mail\Transport\File` as the transport will require uncommenting t ## Logging configuration Uncommenting the `dot-mail.log` key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. -In order to enable it, make sure that your `mail.local.php` has the below `log` configuration under the `dot_mail` key: +To enable it, make sure that your `mail.local.php` has the below `log` configuration under the `dot_mail` key: ```php - [ ... diff --git a/docs/book/v4/overview.md b/docs/book/v4/overview.md index 0fc3a17..32bc8aa 100644 --- a/docs/book/v4/overview.md +++ b/docs/book/v4/overview.md @@ -2,6 +2,19 @@ > dot-mail is a wrapper on top of [laminas-mail](https://github.com/laminas/laminas-mail) +## Badges + +![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-mail) +![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-mail/4.3.0) + +[![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/issues) +[![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/network) +[![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/stargazers) +[![GitHub license](https://img.shields.io/github/license/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/blob/4.0/LICENSE.md) + +[![Build Static](https://github.com/dotkernel/dot-mail/actions/workflows/continuous-integration.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/dot-mail/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/dot-mail/branch/4.0/graph/badge.svg?token=G51NEHYKD3)](https://codecov.io/gh/dotkernel/dot-mail) + ## Extra features -- the option to log the results of the mailing process it provides the developer with more information and greater control. +The option to log the results of the mailing process it provides the developer with more information and greater control. diff --git a/docs/book/v4/transports.md b/docs/book/v4/transports.md index 406f0e9..cf73d5b 100644 --- a/docs/book/v4/transports.md +++ b/docs/book/v4/transports.md @@ -9,20 +9,23 @@ > Feel free to use any custom transport you desire, provided it implements the mentioned `TransportInterface`. -`Sendmail` is a wrapper over PHP's `mail()` function, and as such has a different behaviour on Windows than on *nix systems. Using sendmail on Windows **will not work in combination with** `addBcc()`. +`Sendmail` is a wrapper over PHP's `mail()` function, and as such has a different behavior on Windows than on *nix systems. Using sendmail on Windows **will not work in combination with** `addBcc()`. - Note: emails sent using the sendmail transport will be more often delivered to SPAM. -`Smtp` connects to the configured SMTP host in order to handle sending emails. Saving a copy of an outgoing mail into a folder is possible for this transport only, and is done by uncommenting `save_sent_message_folder` in the config file `mail.local.php` under `dot_mail.default`. +`Smtp` connects to the configured SMTP host to handle sending emails. +Saving a copy of outgoing mail into a folder is possible for this transport only, and is done by uncommenting `save_sent_message_folder` in the config file `mail.local.php` under `dot_mail.default`. -- Common folder names are `INBOX`, `INBOX.Archive`, `INBOX.Drafts`, `INBOX.Sent`, `INBOX.Spam`, `INBOX.Trash`. If you have `MailService` available in your class, you can call `$this->mailService->getFolderGlobalNames()` to list the folder global names for the email you are using. +- Common folder names are `INBOX`, `INBOX.Archive`, `INBOX.Drafts`, `INBOX.Sent`, `INBOX.Spam`, `INBOX.Trash`. + If you have `MailService` available in your class, you can call `$this->mailService->getFolderGlobalNames()` to list the folder global names for the email you are using. - Multiple folders can be added to the `save_sent_message_folder` key to save a copy of the outgoing email in each folder. -`File` writes each message individually in a file named after the configured format, placed in the configured directory. From here the files may be used for sending via another transport mechanism, or simply as logs. +`File` writes each message individually in a file named after the configured format, placed in the configured directory. +From here the files may be used for sending via another transport mechanism, or simply as logs. `InMemory` saves the message in memory, allowing access to the last "sent" message via the `getLastMessage()` function. -- As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well +- As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well. ```php $this->mailService->setBody('First email body'); diff --git a/docs/book/v4/usage.md b/docs/book/v4/usage.md index e4834ab..66a158b 100644 --- a/docs/book/v4/usage.md +++ b/docs/book/v4/usage.md @@ -2,11 +2,14 @@ ## Sending an e-mail -Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. +Below is an example of how to use the email in the most basic way. +You can add your own code to it, e.g., to get the user data from a User object or from a config file, to use a template for the body. -Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. +Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. +Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. -The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. See the `Testing if an e-mail message is valid` section below. +The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. +See the `Testing if an e-mail message is valid` section below. ```php public function sendBasicMail() @@ -19,7 +22,8 @@ public function sendBasicMail() } ``` -It's optional, but recommended to call the above function in a `try-catch` block to display helpful error messages. The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. +It's optional but recommended to call the above function in a `try-catch` block to display helpful error messages. +The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. ```php try { @@ -34,7 +38,7 @@ try { ## Testing if an e-mail message is valid -After sending an e-mail you can check if the message was valid or not. +After sending an e-mail, you can check if the message was valid or not. The `$this->mailService->send()->isValid()` method call will return a boolean value. If the returned result is `true`, the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using `$this->mailService->send()->getMessage()`. diff --git a/docs/book/v5/configuration.md b/docs/book/v5/configuration.md index 11c318a..78d2ba3 100644 --- a/docs/book/v5/configuration.md +++ b/docs/book/v5/configuration.md @@ -31,7 +31,7 @@ Sending email with the `esmtp` transport requires valid data for the values unde ## Logging configuration Uncommenting the `dot-mail.log` key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. -In order to enable it, make sure that your `mail.local.php` has the below `log` configuration under the `dot_mail` key: +To enable it, make sure that your `mail.local.php` has the below `log` configuration under the `dot_mail` key: ```php Feel free to use any custom transport you desire, provided it implements the mentioned `TransportInterface`. -PHP's `mail()` function is a wrapper over `sendmail`, and as such has a different behaviour on Windows than on *nix systems. Using sendmail on Windows **will not work in combination with** `addBcc()`. +PHP's `mail()` function is a wrapper over `sendmail`, and as such has a different behavior on Windows than on *nix systems. +Using sendmail on Windows **will not work in combination with** `addBcc()`. -> Note: emails sent using the sendmail transport will be more often delivered to SPAM. +> Emails sent using the sendmail transport will be more often delivered to SPAM. -`esmtp` connects to the configured SMTP host in order to handle sending emails. +`esmtp` connects to the configured SMTP host to handle sending emails. diff --git a/docs/book/v5/upgrade-v4-to-v5.md b/docs/book/v5/upgrade-v4-to-v5.md index b0aa677..51a13a1 100644 --- a/docs/book/v5/upgrade-v4-to-v5.md +++ b/docs/book/v5/upgrade-v4-to-v5.md @@ -17,19 +17,18 @@ You can follow all the changes in this list of PRs: > Function definition changes will not be covered in this article. -When upgrading dotkernel/dot-mail from v4 to v5, the main focus is on the configuration file `mail.global.php`. -It was revised to implement symfony/mailer, to remove features that are no longer available and to make dotkernel/dot-mail easier to configure. +When upgrading DotMail from v4 to v5, the main focus is on the configuration file `mail.global.php`. +It was revised to implement symfony/mailer, to remove features that are no longer available and to make DotMail easier to configure. ```php -?php - declare(strict_types=1); return [ /** - * Dotkernel mail module configuration - * Note that many of these options can be set programmatically too, when sending mail messages actually that is - * what you'll usually do, these configs provide just defaults and options that remain the same for all mails + * Dotkernel mail module configuration. + * Note that many of these options can be set programmatically too; + * when sending mail messages, actually that is what you'll usually do, + * these configs provide just defaults and options that remain the same for all mails */ 'dot_mail' => [ //the key is the mail service name, this is the default one, which does not extend any configuration diff --git a/docs/book/v5/usage.md b/docs/book/v5/usage.md index 2343721..b80b91f 100644 --- a/docs/book/v5/usage.md +++ b/docs/book/v5/usage.md @@ -2,11 +2,14 @@ ## Sending an e-mail -Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. +Below is an example of how to use the email in the most basic way. +You can add your own code to it, e.g., to get the user data from a User object or from a config file, to use a template for the body. -Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. +Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. +Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`. -The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. See the `Testing if an e-mail message is valid` section below. +The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. +See the `Testing if an e-mail message is valid` section below. ```php public function sendBasicMail() @@ -19,7 +22,8 @@ public function sendBasicMail() } ``` -It's optional, but recommended to call the above function in a `try-catch` block to display helpful error messages. The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. +It's optional but recommended to call the above function in a `try-catch` block to display helpful error messages. +The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`. ```php try { @@ -34,7 +38,7 @@ try { ## Testing if an e-mail message is valid -After sending an e-mail you can check if the message was valid or not. +After sending an e-mail, you can check if the message was valid or not. The `$this->mailService->send()->isValid()` method call will return a boolean value. If the returned result is `true`, the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using `$this->mailService->send()->getMessage()`. @@ -54,7 +58,8 @@ if (! $result->isValid()) { ## Logging outgoing emails -Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. +Optionally, you can keep a log of each successfully sent email. +This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: @@ -62,7 +67,8 @@ Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {"subject":"Test subject","to":["Test Account "],"cc":[],"bcc":[]}. ``` -Each email is saved via the `dotkernel/dot-log` component in the shown `JSON` format, in the single file configured under the `dot-mail.log.sent` key. To disable it, set the value of `dot-mail.log.sent` to `null`. +Each email is saved via the `dotkernel/dot-log` component in the shown `JSON` format, in the single file configured under the `dot-mail.log.sent` key. +To disable it, set the value of `dot-mail.log.sent` to `null`. ## Transport usage