From 5a1b2ebd1e69eaaf7684a8d502a8e1f6137cd1be Mon Sep 17 00:00:00 2001 From: bota Date: Thu, 28 Aug 2025 11:31:11 +0300 Subject: [PATCH 1/6] tutorial how to implement email service Signed-off-by: bota --- docs/book/v1/implement-sending-emails.md | 95 ++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/book/v1/implement-sending-emails.md diff --git a/docs/book/v1/implement-sending-emails.md b/docs/book/v1/implement-sending-emails.md new file mode 100644 index 0000000..cc2f96b --- /dev/null +++ b/docs/book/v1/implement-sending-emails.md @@ -0,0 +1,95 @@ +# IMPLEMENTATION OF EMAIL SENDING SERVICE + +To implement such a service, the [send-email](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. + +## Step 1 Adding Core + +Import the Core from the project from which requests will be sent, in this case the dotkernel admin. This can be done either by directly copying the entire Core folder, or using submodule add if Core is a separate repository. + +> **_NOTE:_** make sure you always keep the Core in the queue and the Core in the project it communicates with in sync. + +## Step 2 Core dependency + +After the Core is added, navigate to the composer.json file and make sure you add all the necessary dependencies for the Core. + +```shell +"dotkernel/dot-cache": "^4.3", +"dotkernel/dot-data-fixtures": "^1.4.0", +"dotkernel/dot-errorhandler": "4.2.1", +"dotkernel/dot-mail": "^5.3.0", +"laminas/laminas-authentication": "2.18.0", +"mezzio/mezzio-authentication-oauth2": "^2.11", +"mezzio/mezzio-twigrenderer": "^2.17.0", +"ramsey/uuid": "^4.5.0", +"ramsey/uuid-doctrine": "^2.1.0", +"roave/psr-container-doctrine": "^5.2.2", +``` + +Also here under the "autoload" → "psr-4" key make sure you add all the modules from the Core folder. + +```shell +"autoload": { + "psr-4": { + "Queue\\": "src/", + "Core\\Admin\\": "src/Core/src/Admin/src", + "Core\\App\\": "src/Core/src/App/src", + "Core\\Security\\": "src/Core/src/Security/src", + "Core\\Setting\\": "src/Core/src/Setting/src", + "Core\\User\\": "src/Core/src/User/src", + } +}, +``` +## Step 3 Install new dependencies + +Install all new dependencies using: + +```shell +composer install +``` + +## Step 4 Configuration + +Navigate to `config/config.php` and add `ConfigProvider::class` file from all packages you installed. + +```shell +Mezzio\Twig\ConfigProvider::class, +Dot\Cache\ConfigProvider::class, +Dot\DataFixtures\ConfigProvider::class, +Dot\Mail\ConfigProvider::class, + +// Core +Core\Admin\ConfigProvider::class, +Core\App\ConfigProvider::class, +Core\Security\ConfigProvider::class, +Core\Setting\ConfigProvider::class, +Core\User\ConfigProvider::class, +``` +## Step 5 Database connection + +Navigate to `config/autoload/local.php` and fill in the database connection details. +> **_NOTE:_** if you only have the local.php.dist file, duplicate it, and delete .dist from the copy's name + +```shell +$databases = [ + 'default' => [ + 'host' => '', + 'dbname' => '', + 'user' => '', + 'password' => '', + 'port' => 3306, + 'driver' => 'pdo_mysql', + 'charset' => 'utf8mb4', + 'collate' => 'utf8mb4_general_ci', + ], +]; +``` + +## Step 6 Email configuration + +Inside your `config/autoload` folder create a new file named `mail.global.php`, copy this [file](https://github.com/dotkernel/queue/blob/send-email/config/autoload/mail.global.php) content and fill in your configuration. + +## Step 7 Data management and emails sending + +Once everything is installed and configured we can move on to handle the data in the queue. Inside your handler for example `MessageHandler` you can inject all the services you need in order to create and send emails. + +In this [file](https://github.com/dotkernel/queue/blob/send-email/src/App/Message/MessageHandler.php) you can follow a simple example of how to create and send an email using data received from the queue inside the handler. From cfbec635c5173bc21a6160f204a7f0961921e666 Mon Sep 17 00:00:00 2001 From: bota Date: Thu, 28 Aug 2025 11:34:03 +0300 Subject: [PATCH 2/6] linting Signed-off-by: bota --- docs/book/v1/implement-sending-emails.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/book/v1/implement-sending-emails.md b/docs/book/v1/implement-sending-emails.md index cc2f96b..3c94cee 100644 --- a/docs/book/v1/implement-sending-emails.md +++ b/docs/book/v1/implement-sending-emails.md @@ -37,8 +37,9 @@ Also here under the "autoload" → "psr-4" key make sure you add all the modules "Core\\Setting\\": "src/Core/src/Setting/src", "Core\\User\\": "src/Core/src/User/src", } -}, +} ``` + ## Step 3 Install new dependencies Install all new dependencies using: @@ -64,6 +65,7 @@ Core\Security\ConfigProvider::class, Core\Setting\ConfigProvider::class, Core\User\ConfigProvider::class, ``` + ## Step 5 Database connection Navigate to `config/autoload/local.php` and fill in the database connection details. From 893eb6a10389fa9b19882019f50d09f49f29af0f Mon Sep 17 00:00:00 2001 From: bota Date: Thu, 28 Aug 2025 15:28:44 +0300 Subject: [PATCH 3/6] improved documentation for send emails Signed-off-by: bota --- .../send-emails.md} | 27 ++++++++++++------- mkdocs.yml | 2 ++ 2 files changed, 19 insertions(+), 10 deletions(-) rename docs/book/v1/{implement-sending-emails.md => How to/send-emails.md} (50%) diff --git a/docs/book/v1/implement-sending-emails.md b/docs/book/v1/How to/send-emails.md similarity index 50% rename from docs/book/v1/implement-sending-emails.md rename to docs/book/v1/How to/send-emails.md index 3c94cee..8fbae8f 100644 --- a/docs/book/v1/implement-sending-emails.md +++ b/docs/book/v1/How to/send-emails.md @@ -1,16 +1,21 @@ -# IMPLEMENTATION OF EMAIL SENDING SERVICE +# SEND EMAILS -To implement such a service, the [send-email](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. +Using a queuing service solves problems such as server overload. For example, if a server receives a large number of requests, it tries to process them synchronously, resulting in long response times or even server crashes. -## Step 1 Adding Core +A concrete example is sending emails. While a series of tasks are running on the server, a task such as sending an email is sent to a queue and run in the background so the server can move on to the next task, while the queue composes the email and sends it. Tasks are queued and processed gradually (FIFO), depending on available resources. -Import the Core from the project from which requests will be sent, in this case the dotkernel admin. This can be done either by directly copying the entire Core folder, or using submodule add if Core is a separate repository. +To implement such a service, the [`send-email`](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. +> **_NOTE:_** The default branch 1.0 hold only the base code of Queue and provides essential features such as: +> * Adding messages to the queue +> * Retrieving and processing messages (FIFO) -> **_NOTE:_** make sure you always keep the Core in the queue and the Core in the project it communicates with in sync. +## Step 1 Importing Core + +Importing the Core is essential for the queue to communicate with the main application logic (for this case [`dotkernel admin`](https://github.com/dotkernel/admin)). Whether you copy the Core folder directly or add it as a submodule, it’s important to keep the Core in sync between the main project and the queue so that all classes, services, and configurations are available for message processing. ## Step 2 Core dependency -After the Core is added, navigate to the composer.json file and make sure you add all the necessary dependencies for the Core. +After adding the Core, you need to make sure all external dependencies are included in composer.json. Without them, Core functionalities (cache, mail, authentication, etc.) won’t work in the queue. ```shell "dotkernel/dot-cache": "^4.3", @@ -25,7 +30,7 @@ After the Core is added, navigate to the composer.json file and make sure you ad "roave/psr-container-doctrine": "^5.2.2", ``` -Also here under the "autoload" → "psr-4" key make sure you add all the modules from the Core folder. +Adding Core modules under `autoload` → `psr-4` enables automatic class loading, so you don’t have to manually require each class. ```shell "autoload": { @@ -48,6 +53,8 @@ Install all new dependencies using: composer install ``` +Running `composer install` ensures that all packages required for Core and the queue are downloaded. This includes third-party libraries and all project-specific dependencies. + ## Step 4 Configuration Navigate to `config/config.php` and add `ConfigProvider::class` file from all packages you installed. @@ -69,7 +76,7 @@ Core\User\ConfigProvider::class, ## Step 5 Database connection Navigate to `config/autoload/local.php` and fill in the database connection details. -> **_NOTE:_** if you only have the local.php.dist file, duplicate it, and delete .dist from the copy's name +> **_NOTE:_** if you only have the local.php.dist file, duplicate it, and delete .dist from the copy's name. ```shell $databases = [ @@ -88,10 +95,10 @@ $databases = [ ## Step 6 Email configuration -Inside your `config/autoload` folder create a new file named `mail.global.php`, copy this [file](https://github.com/dotkernel/queue/blob/send-email/config/autoload/mail.global.php) content and fill in your configuration. +Inside your `config/autoload` folder create a new file named `mail.global.php`, copy this [file](https://github.com/dotkernel/queue/blob/send-email/config/autoload/mail.global.php) content and fill in your configuration. The queue will use these settings to send emails in the background. ## Step 7 Data management and emails sending -Once everything is installed and configured we can move on to handle the data in the queue. Inside your handler for example `MessageHandler` you can inject all the services you need in order to create and send emails. +Once everything is installed and configured we can move on to handle the data in the queue. In the message handler for example `MessageHandler`, each message from the queue is processed, the email is composed, and then sent. By injecting the required services and using templates, the handler can send emails without blocking the main application, respecting FIFO and asynchronous processing. In this [file](https://github.com/dotkernel/queue/blob/send-email/src/App/Message/MessageHandler.php) you can follow a simple example of how to create and send an email using data received from the queue inside the handler. diff --git a/mkdocs.yml b/mkdocs.yml index 26b11c8..a78ede5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,8 @@ nav: - Installation: v1/installation.md - Commands: v1/commands.md - Valkey: v1/valkey.md + - How to: + - Send Emails: v1/send-emails.md site_name: queue site_description: "Dotkernel Queue" repo_url: "https://github.com/dotkernel/queue" From 219de7d8b03ce3774b34ea2cdf91e173e8a37dad Mon Sep 17 00:00:00 2001 From: bota Date: Thu, 28 Aug 2025 15:31:00 +0300 Subject: [PATCH 4/6] linting Signed-off-by: bota --- docs/book/v1/How to/send-emails.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/book/v1/How to/send-emails.md b/docs/book/v1/How to/send-emails.md index 8fbae8f..5165303 100644 --- a/docs/book/v1/How to/send-emails.md +++ b/docs/book/v1/How to/send-emails.md @@ -5,6 +5,7 @@ Using a queuing service solves problems such as server overload. For example, if A concrete example is sending emails. While a series of tasks are running on the server, a task such as sending an email is sent to a queue and run in the background so the server can move on to the next task, while the queue composes the email and sends it. Tasks are queued and processed gradually (FIFO), depending on available resources. To implement such a service, the [`send-email`](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. + > **_NOTE:_** The default branch 1.0 hold only the base code of Queue and provides essential features such as: > * Adding messages to the queue > * Retrieving and processing messages (FIFO) From 68ccabda1dbab0ff21bd55727060eae3dcb8d788 Mon Sep 17 00:00:00 2001 From: bota Date: Thu, 28 Aug 2025 15:33:58 +0300 Subject: [PATCH 5/6] typo Signed-off-by: bota --- docs/book/v1/How to/send-emails.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/book/v1/How to/send-emails.md b/docs/book/v1/How to/send-emails.md index 5165303..35d63dd 100644 --- a/docs/book/v1/How to/send-emails.md +++ b/docs/book/v1/How to/send-emails.md @@ -6,7 +6,8 @@ A concrete example is sending emails. While a series of tasks are running on the To implement such a service, the [`send-email`](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. -> **_NOTE:_** The default branch 1.0 hold only the base code of Queue and provides essential features such as: +> **_NOTE:_** The default branch 1.0 holds only the base code of Queue and provides essential features such as: +> > * Adding messages to the queue > * Retrieving and processing messages (FIFO) From 2ab328da4033dda10ab02beb561667666dd3f998 Mon Sep 17 00:00:00 2001 From: bota Date: Fri, 29 Aug 2025 13:07:39 +0300 Subject: [PATCH 6/6] typo Signed-off-by: bota --- docs/book/v1/{How to => how-to}/send-emails.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/book/v1/{How to => how-to}/send-emails.md (94%) diff --git a/docs/book/v1/How to/send-emails.md b/docs/book/v1/how-to/send-emails.md similarity index 94% rename from docs/book/v1/How to/send-emails.md rename to docs/book/v1/how-to/send-emails.md index 35d63dd..7a92812 100644 --- a/docs/book/v1/How to/send-emails.md +++ b/docs/book/v1/how-to/send-emails.md @@ -2,7 +2,7 @@ Using a queuing service solves problems such as server overload. For example, if a server receives a large number of requests, it tries to process them synchronously, resulting in long response times or even server crashes. -A concrete example is sending emails. While a series of tasks are running on the server, a task such as sending an email is sent to a queue and run in the background so the server can move on to the next task, while the queue composes the email and sends it. Tasks are queued and processed gradually (FIFO), depending on available resources. +A concrete example is sending emails. While a series of tasks are running on the server, a task such as sending an email is passed to a queue and run in the background so the server can move on to the next task, while the queue composes the email and sends it. Tasks are queued and processed gradually (FIFO), depending on available resources. To implement such a service, the [`send-email`](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model.