file structure & more details

Jurj-Bogdan · Jurj-Bogdan · commit bd8baa98bde5 · 2025-01-17T16:59:47.000+02:00
Signed-off-by: Jurj-Bogdan &lt;bogdanjurj11@gmail.com&gt;
diff --git a/docs/book/v5/upgrading/UPGRADE-5.3.md b/docs/book/v5/upgrading/UPGRADE-5.3.md
@@ -11,27 +11,34 @@ This document only covers upgrading from version 5.2.
 
 -------------------------
 
-* [Update Phpstan memory limit](#update-phpstan-memory-limit)
+* [Update PHPStan memory limit](#update-phpstan-memory-limit)
 * [Update anonymization](#update-anonymization)
 * [Update User status and remove isDeleted properties](#update-user-status-and-remove-isdeleted-properties)
 * [Update dotkernel/dot-mail to version 5.0](#update-dotkerneldot-mail-to-version-50)
 * [Add post install script](#add-post-install-script)
 * [Remove post-create-project-cmd](#remove-post-create-project-cmd)
+* [Ignore development files on production env](#ignore-development-files-on-production-env)
 * [Update security.txt](#update-securitytxt)
 * [Update coding standards](#update-coding-standards)
-* [Fix codecov.yml](#fix-codecovyml)
 * [Update Qodana configuration](#update-qodana-configuration)
 * [Remove laminas/laminas-http](#remove-laminaslaminas-http)
 
-### Update Phpstan memory limit
+### Update PHPStan memory limit
+
+Following PHPStan's introduction in version 5.2 for the reasons described on the [Dotkernel blog](https://www.dotkernel.com/php-development/static-analysis-replacing-psalm-with-phpstan/) a minor issue has cropped up:
+ with the default `memory_limit=128M` on our WSL containers, PHPStan runs out of memory
 
 * Add the `--memory-limit 1G` option to the `static-analysis` script found in `composer.json`
-  > With the default `memory_limit=128M` on our WSL containers, PHPStan runs out of memory
-  >
   > Note that you can set the memory limit to a value of your choosing, with a recommended minimum of 256M
 
 ### Update anonymization
 
+By default, Dotkernel API uses "soft delete" for it's `User` entities in order to preserve the database entries.
+
+Anonymization is used to make sure any sensitive information is scrubbed from the system, with the `User`'s `identity`, `email`, `firstName` and `lastName` properties being overwritten by a unique placeholder.
+
+Version 5.3 is adding an optional suffix from a configuration file, from where it can be used anywhere in the application.
+
 * Add the `userAnonymizeAppend` key to the returned array in `config/autoload/local.php`, as well as to the distributed`config/autoload/local.php.dist`
 
 ```php
@@ -56,6 +63,12 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 
 ### Update User status and remove isDeleted properties
 
+Up to and including version 5.2, the `User` entity made use of the `UserStatusEnum` to mark the account status (`active` or `inactive`) and marked deleted accounts with the `isDeleted` property.
+
+Starting from version 5.3 the `isDeleted` property has been removed because, by default, there is no use in having both it and the status property.
+
+As such, a new `Deleted` case for `UserStatusEnum` is now used to mark a deleted account and remove the redundancy.
+
 * [BC Break] Remove the `isDeleted` property from the `User` class, alongside all usages, as seen in the [pull request](https://github.com/dotkernel/api/pull/359/files)
 * Add a new "deleted" case to `UserStatusEnum`, which is to be used instead of the previous `isDeleted` property
 * Update the database and it's migrations to reflect the new structure
@@ -65,6 +78,14 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 
 ### Update `dotkernel/dot-mail` to version 5.0
 
+Dotkernel API uses `dotkernel/dot-mail` to handle the mailing service, which in versions older than 5.0 was based on `laminas/laminas-mail`.
+
+Due to the deprecation of `laminas/laminas-mail`, a decision was made to switch `dot-mail` to using `symfony/mailer` starting from version 5.0.
+
+To make the API more future-proof, the upgrade to the new version of `dot-mail` was necessary.
+
+The default usage of the mailer remains unchanged, with the only required updates being to configuration, as described below:
+
 * Bump `dotkernel/dot-mail` to "^5.0" in `composer.json`
 * As the mail configuration file is now directly copied from the vendor via [script](#add-post-install-script), remove the existing `config/autoload/mail.global.php[.dist]` file(s)
 * Update the content for each of these configuration files to reflect the new structure from [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail/blob/5.0/config/mail.global.php.dist)
@@ -75,6 +96,8 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 
 ### Remove `post-create-project-cmd`
 
+Installing the API via `composer create-project` is not recommended, and because of this the `post-create-project-cmd` has been removed.
+
 * Remove the `post-create-project-cmd` key found under `scripts` in `composer.json`
 
 ```json
@@ -85,6 +108,14 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 
 ### Add post install script
 
+To make installing the API less of a hassle, a new post installation script was added.
+
+This script generates all the configuration files required by default, leaving the user to simply complete the relevant data.
+
+> Note that the script will not overwrite existing configuration files, preserving any user data
+>
+> In case the structure of a configuration file needs updating (such as [mail.local.php](#update-dotkerneldot-mail-to-version-50) in this update), simply running the script *will not* make the changes
+
 * Add `bin/composer-post-install-script.php` to automate the post installation copying of distributed configuration files
 * Add the following under the `scripts` key in `composer.json`:
 
@@ -106,13 +137,49 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 
 > The command can be manually run via `php bin/composer-post-install-script.php`
 
+### Ignore development files on production env
+
+These tweaks were added to make sure development files remain untouched on production environments.
+
+* Restrict codecov to development mode by changing the following section from `.github/workflows/codecov.yml`:
+
+Before:
+
+```yaml
+- name: Install dependencies with composer
+  run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
+```
+
+After:
+
+```yaml
+- name: Install dependencies with composer
+  env:
+    COMPOSER_DEV_MODE: 1
+  run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
+```
+
+* Edit `.laminas-ci/pre-run.sh` script by changing `echo "Running $COMMAND"` to `echo "Running pre-run $COMMAND"` and delete the following line:
+
+```shell
+cp config/autoload/mail.global.php.dist config/autoload/mail.global.php
+```
+
 ### Update security.txt
 
+Updated the `security.txt` file to define the preferred language of the security team.
+
+It is recommended that the `Expires` tag is also updated if necessary.
+
 * Add the `Preferred-Languages` key to `public/.well-known/security.txt`
   > You may include more than one language as comma separated language tags
 
 ### Update coding standards
 
+Dotkernel API uses `laminas/laminas-coding-standard` as its baseline ruleset to ensure adherence to PSR-1 and PSR-12.
+
+As this package had a major release, the minimum version the API uses was also bumped.
+
 * Bump `laminas/laminas-coding-standard` to `^3.0` in `composer.json`
 * Add the following to `phpcs.xml` to prevent issues with the fully qualified names from `config/config.php`:
 
@@ -123,11 +190,11 @@ $user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
 </rule>
 ```
 
-### Fix codecov.yml
+### Update Qodana configuration
 
-* Change `COMPOSER_DEV_MODE=1` to the correct syntax `COMPOSER_DEV_MODE: 1`
+The Qodana code quality workflow has changed its default PHP version to 8.4, which is unsupported by Dotkernel API, resulting in errors.
 
-### Update Qodana configuration
+The issue was fixed by restricting Qodana to the supported PHP versions.
 
 * Update `.github/workflows/qodana_code_quality.yml`, specifying the supported PHP versions by adding the `strategy` key:
 
@@ -155,5 +222,9 @@ with:
 
 ### Remove laminas/laminas-http
 
+Prior to version 5.3, `laminas/laminas-http` was only used in 2 test files to assert if correct status codes were returned.
+
+This dependency was removed, as the usage in tests was replaced with the existing `StatusCodeInterface`.
+
 * Remove `laminas/laminas-http` from `composer.json`
 * Replace all uses of `Laminas\Http\Response` with `Fig\Http\Message\StatusCodeInterface` in `AuthorizationMiddlewareTest.php` and `ContentNegotiationMiddlewareTest.php`
diff --git a/docs/book/v5/upgrading/upgrading.md b/docs/book/v5/upgrading/upgrading.md
@@ -14,4 +14,6 @@ For each new release you need implement the modifications from its pull requests
 It is recommended to copy the release info into your project's CHANGELOG.md file.
 This allows you to track your API's version and keep your project up-to-date with future releases.
 
-Starting from [version 5.3](upgrading/UPGRADE-5.3.md) the upgrading procedure is detailed version to version.
+## Version to version upgrading
+
+Starting from [version 5.3](UPGRADE-5.3.md) the upgrading procedure is detailed version to version.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,7 +22,9 @@ nav:
           - "Doctrine ORM": v5/installation/doctrine-orm.md
           - "Test the Installation": v5/installation/test-the-installation.md
           - "FAQ": v5/installation/faq.md
-      - Upgrading: v5/upgrading.md
+      - Upgrading:
+          - "Upgrading": v5/upgrading/upgrading.md
+          - "Upgrading 5.2 to 5.3": v5/upgrading/UPGRADE-5.3.md
       - Flow:
           - "Middleware Flow": v5/flow/middleware-flow.md
           - "Default Library Flow": v5/flow/default-library-flow.md
