Merge pull request #55 from Jurj-Bogdan/4.0

Added v4 documentation, updated workflows

Author: alexmerlin

.github/workflows/continuous-integration.yml

@@ -0,0 +1,11 @@
+name: "Continuous Integration"
+
+on:
+  pull_request:
+  push:
+    branches:
+    tags:
+
+jobs:
+  ci:
+    uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x

.github/workflows/cs-tests.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/docs-build.yml

@@ -2,7 +2,6 @@
 
 DotKernel mail component based on [laminas-mail](https://github.com/laminas/laminas-mail)
 
-
 ![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.1.1)
 
@@ -11,15 +10,15 @@ DotKernel mail component based on [laminas-mail](https://github.com/laminas/lami
 [![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/static-analysis.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/dot-mail/actions/workflows/static-analysis.yml)
+[![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)
 
 [![SymfonyInsight](https://insight.symfony.com/projects/1995ea7c-3b34-4eee-ac48-3571860d0307/big.svg)](https://insight.symfony.com/projects/1995ea7c-3b34-4eee-ac48-3571860d0307)
 
+## Configuration
 
-### Configuration
+### Mail - Sendmail
 
-#### Mail - Sendmail
 If your server has Sendmail installed, update the `config/autoload/mail.local.php.dist` file by setting the `transport` key like below
 
 ```php
@@ -35,13 +34,16 @@ return [
 ]
 ```
 
-#### Mail - SMTP
+### Mail - SMTP
+
 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:
+
 - `from` - email address from whom users will receive emails
 
 Under `smtp_options` key:
+
 - `host` - the mail server's hostname or IP address
 - `port` - the mail server's port
 - `connection_config` - fill in the `username`, `password` and `ssl` keys with the login details of the email used in `from` above
@@ -113,6 +115,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.
 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.
@@ -121,24 +124,24 @@ In case your e-mail was invalid, you can check for any errors using `$this->mail
 Using the below logic will let you determine if a message was valid or not and log it.
 You can implement your own custom error logging logic.
 
-````
+```php
 $result = $this->mailService->send();
 if (! $result->isValid()) {
     //log the error
     error_log($result->getMessage());
 }
-````
-**Note : Invalid e-mail messages will not be sent.**
+```
 
+**Note : Invalid e-mail messages will not be sent.**
 
 ### 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.
 
 Logs are stored in the following format: `[YYYY-MM-DD HH:MM:SS]: {"subject":"Test subject","to":["Test Account <test@dotkernel.com>"],"cc":[],"bcc":[]}`.
 
-By default, this feature is disabled.
-
 In order to enable it, make sure that your `config/autoload/mail.local.php` has the below `log` configuration under the `dot_mail` key:
+
 ```php
 <?php
 
@@ -151,11 +154,15 @@ return [
     ]
 ];
 ```
-To disable it again, set the value of `sent` to `null`.
+
+To disable it, set the value of `sent` to `null`.
 
 ### Saving a copy of an outgoing mail into a folder
-#### Valid only for SMTP Transport
+
+### Valid only for SMTP Transport
+
 First, make sure the `save_sent_message_folder` key is present in config file `mail.local.php` under `dot_mail.default`. Below you can see its placement and default value.
+
 ```php
 <?php
 
@@ -168,6 +175,7 @@ return [
     ],
 ];
 ```
+
 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.

.github/workflows/static-analysis.yml

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Supported Versions
+
+
+| Version | Supported          | PHP Version                                                                                              |
+|---------|--------------------|----------------------------------------------------------------------------------------------------------|
+| 4.x     | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-mail/4.1.1) |
+| <= 3.x  | :x:                |                                                                                                          |
+
+
+## Reporting Potential Security Issues
+
+If you have encountered a potential security vulnerability in this project,
+please report it to us at <security@dotkernel.com>. We will work with you to
+verify the vulnerability and patch it.
+
+When reporting issues, please provide the following information:
+
+- Component(s) affected
+- 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.
+
+
+## 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.

.github/workflows/unit-tests.yml

@@ -29,15 +29,15 @@
         "php": "~8.1.0 || ~8.2.0 || ~8.3.0",
         "ext-fileinfo": "*",
         "ext-json": "*",
-        "laminas/laminas-servicemanager": "^3.22.1",
-        "laminas/laminas-mail": "^2.25.1",
-        "dotkernel/dot-event": "^3.4.2"
+        "laminas/laminas-servicemanager": "^3.22",
+        "laminas/laminas-mail": "^2.25",
+        "dotkernel/dot-event": "^3.4"
     },
     "require-dev": {
-        "laminas/laminas-coding-standard": "^2.5.0",
+        "laminas/laminas-coding-standard": "^2.5",
         "mikey179/vfsstream": "^v1.6.11",
-        "phpunit/phpunit": "^10.4.2",
-        "vimeo/psalm": "^5.16.0"
+        "phpunit/phpunit": "^10.5",
+        "vimeo/psalm": "^5.23"
     },
     "autoload": {
         "psr-4": {

README.md

@@ -3,7 +3,7 @@
 return [
 
     /**
-     * Dotkernel mail module configuration
+     * 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 config provide just default and options that remain the same for all mails
      */
@@ -28,14 +28,10 @@ return [
              **/
 
             'transport' => \Laminas\Mail\Transport\Sendmail::class,
-            
-            // Uncomment the below line if you want to save a copy of all sent emails to a certain IMAP folder
-            // Valid only if the Transport is SMTP 
-            // 'save_sent_message_folder' => ['INBOX.Sent'],
 
             // Uncomment the below line if you want to save a copy of all sent emails to a certain IMAP folder
             // Valid only if the Transport is SMTP
-            // 'save_sent_message_folder' => ['INBOX.Sent'],
+            //'save_sent_message_folder' => ['INBOX.Sent'],
 
             //message configuration
             'message_options' => [

SECURITY.md

@@ -0,0 +1 @@
+../../README.md