Skip to content

Commit 2e18076

Browse files
arhimedearhimede
authored
Merge pull request #85 from dotkernel/issue-84
upgrade from 5.2 to 5.3 steps
2 parents 230b666 + ab3bbc3 commit 2e18076

File tree

3 files changed

+239
-16
lines changed

3 files changed

+239
-16
lines changed

‎docs/book/v5/upgrading/UPGRADE-5.3.md

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# UPGRADE FROM 5.2 TO 5.3
2+
3+
-------------------------
4+
5+
Dotkernel API 5.3 is a minor release. As such, no significant backward compatibility breaks are expected,
6+
with minor backward compatibility breaks being prefixed in this document with `[BC BREAK]`.
7+
This document only covers upgrading from version 5.2.
8+
9+
## Table of Contents
10+
11+
-------------------------
12+
13+
* [Update PHPStan memory limit](#update-phpstan-memory-limit)
14+
* [Update anonymization](#update-anonymization)
15+
* [Update User status and remove isDeleted properties](#update-user-status-and-remove-isdeleted-properties)
16+
* [Update dotkernel/dot-mail to version 5.0](#update-dotkerneldot-mail-to-version-50)
17+
* [Add post install script](#add-post-install-script)
18+
* [Remove post-create-project-cmd](#remove-post-create-project-cmd)
19+
* [Ignore development files on production env](#ignore-development-files-on-production-env)
20+
* [Update security.txt](#update-securitytxt)
21+
* [Update coding standards](#update-coding-standards)
22+
* [Update Qodana configuration](#update-qodana-configuration)
23+
* [Remove laminas/laminas-http](#remove-laminaslaminas-http)
24+
25+
### Update PHPStan memory limit
26+
27+
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:
28+
with the default `memory_limit=128M` on our WSL containers, PHPStan runs out of memory
29+
30+
* Add the `--memory-limit 1G` option to the `static-analysis` script found in `composer.json`
31+
> Note that you can set the memory limit to a value of your choosing, with a recommended minimum of 256M
32+
33+
### Update anonymization
34+
35+
By default, Dotkernel API uses "soft delete" for its `User` entities in order to preserve the database entries.
36+
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.
37+
Version 5.3 is adding an optional suffix from a configuration file, from where it can be used anywhere in the application.
38+
39+
* Add the `userAnonymizeAppend` key to the returned array in `config/autoload/local.php`, as well as to the distributed`config/autoload/local.php.dist`
40+
41+
```php
42+
'userAnonymizeAppend' => '',
43+
```
44+
45+
* Update the `anonymizeUser` function in `src/User/src/Service/UserService.php` to use the new key
46+
47+
Before:
48+
49+
```php
50+
$user->setIdentity($placeholder) //...
51+
```
52+
53+
After:
54+
55+
```php
56+
$user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
57+
```
58+
59+
> Note that any custom functionality using the old format will require updates
60+
61+
### Update User status and remove isDeleted properties
62+
63+
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.
64+
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.
65+
As such, a new `Deleted` case for `UserStatusEnum` is now used to mark a deleted account and remove the redundancy.
66+
67+
* [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)
68+
* Add a new "deleted" case to `UserStatusEnum`, which is to be used instead of the previous `isDeleted` property
69+
* Update the database and its migrations to reflect the new structure
70+
> The use of "isDeleted" was redundant in the default application, and as such was removed
71+
>
72+
> All default methods are updated, but any custom functionality using "isDeleted" will require refactoring
73+
74+
### Update `dotkernel/dot-mail` to version 5.0
75+
76+
Dotkernel API uses `dotkernel/dot-mail` to handle the mailing service, which in versions older than 5.0 was based on `laminas/laminas-mail`.
77+
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.
78+
To make the API more future-proof, the upgrade to the new version of `dot-mail` was necessary.
79+
The default usage of the mailer remains unchanged, with the only required updates being to configuration, as described below:
80+
81+
* Bump `dotkernel/dot-mail` to "^5.0" in `composer.json`
82+
* 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)
83+
* 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)
84+
* Remove `Laminas\Mail\ConfigProvider::class` from `config/config.php`
85+
> The list of changes can be seen in the [pull request](https://github.com/dotkernel/api/pull/368/files)
86+
>
87+
> You can read more about the reasons for this change on the [Dotkernel blog](https://www.dotkernel.com/dotkernel/replacing-laminas-mail-with-symfony-mailer-in-dot-mail/).
88+
89+
### Remove `post-create-project-cmd`
90+
91+
Installing the API via `composer create-project` is not recommended, and because of this the `post-create-project-cmd` has been removed.
92+
93+
* Remove the `post-create-project-cmd` key found under `scripts` in `composer.json`
94+
95+
```json
96+
"post-create-project-cmd": [
97+
"@development-enable"
98+
],
99+
```
100+
101+
### Add post install script
102+
103+
To make installing the API less of a hassle, a new post installation script was added.
104+
This script generates all the configuration files required by default, leaving the user to simply complete the relevant data.
105+
106+
> Note that the script will not overwrite existing configuration files, preserving any user data
107+
>
108+
> 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
109+
110+
* Add `bin/composer-post-install-script.php` to automate the post installation copying of distributed configuration files
111+
* Add the following under the `scripts` key in `composer.json`:
112+
113+
```json
114+
"post-update-cmd": [
115+
"php bin/composer-post-install-script.php"
116+
],
117+
```
118+
119+
* Remove the following section from `.github/workflows/codecov.yml` and `.github/workflows/static-analysis.yml`
120+
121+
```yaml
122+
- name: Setup project
123+
run: |
124+
mv config/autoload/local.php.dist config/autoload/local.php
125+
mv config/autoload/mail.global.php.dist config/autoload/mail.global.php
126+
mv config/autoload/local.test.php.dist config/autoload/local.test.php
127+
```
128+
129+
> The command can be manually run via `php bin/composer-post-install-script.php`
130+
131+
### Ignore development files on production env
132+
133+
These tweaks were added to make sure development files remain untouched on production environments.
134+
135+
* Restrict codecov to development mode by changing the following section from `.github/workflows/codecov.yml`:
136+
137+
Before:
138+
139+
```yaml
140+
- name: Install dependencies with composer
141+
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
142+
```
143+
144+
After:
145+
146+
```yaml
147+
- name: Install dependencies with composer
148+
env:
149+
COMPOSER_DEV_MODE: 1
150+
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
151+
```
152+
153+
* Edit `.laminas-ci/pre-run.sh` script by changing `echo "Running $COMMAND"` to `echo "Running pre-run $COMMAND"` and delete the following line:
154+
155+
```shell
156+
cp config/autoload/mail.global.php.dist config/autoload/mail.global.php
157+
```
158+
159+
### Update security.txt
160+
161+
Updated the `security.txt` file to define the preferred language of the security team.
162+
It is recommended that the `Expires` tag is also updated if necessary.
163+
164+
* Add the `Preferred-Languages` key to `public/.well-known/security.txt`
165+
> You may include more than one language as comma separated language tags
166+
167+
### Update coding standards
168+
169+
Dotkernel API uses `laminas/laminas-coding-standard` as its baseline ruleset to ensure adherence to PSR-1 and PSR-12.
170+
As this package had a major release, the minimum version the API uses was also bumped.
171+
172+
* Bump `laminas/laminas-coding-standard` to `^3.0` in `composer.json`
173+
* Add the following to `phpcs.xml` to prevent issues with the fully qualified names from `config/config.php`:
174+
175+
```xml
176+
<rule ref="LaminasCodingStandard">
177+
<!-- Exclude rule -->
178+
<exclude name="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedName" />
179+
</rule>
180+
```
181+
182+
### Update Qodana configuration
183+
184+
The Qodana code quality workflow has changed its default PHP version to 8.4, which is unsupported by Dotkernel API, resulting in errors.
185+
The issue was fixed by restricting Qodana to the supported PHP versions.
186+
187+
* Update `.github/workflows/qodana_code_quality.yml`, specifying the supported PHP versions by adding the `strategy` key:
188+
189+
```yaml
190+
strategy:
191+
matrix:
192+
php-versions: [ '8.2', '8.3' ]
193+
```
194+
195+
* Update the `php-version` key to restrict Qodana to the newly added `php-versions`
196+
197+
Before:
198+
199+
```yaml
200+
with:
201+
php-version: "${{ matrix.php }}"
202+
```
203+
204+
After:
205+
206+
```yaml
207+
with:
208+
php-version: ${{ matrix.php-versions }}
209+
```
210+
211+
### Remove laminas/laminas-http
212+
213+
Prior to version 5.3, `laminas/laminas-http` was only used in 2 test files to assert if correct status codes were returned.
214+
This dependency was removed, as the usage in tests was replaced with the existing `StatusCodeInterface`.
215+
216+
* Remove `laminas/laminas-http` from `composer.json`
217+
* Replace all uses of `Laminas\Http\Response` with `Fig\Http\Message\StatusCodeInterface` in `AuthorizationMiddlewareTest.php` and `ContentNegotiationMiddlewareTest.php`

‎docs/book/v5/upgrading.md renamed to ‎docs/book/v5/upgrading/upgrading.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
1-
# Upgrades
2-
3-
Dotkernel API does not provide an automatic upgrade path.
4-
Instead, the recommended procedure is to manually implement each modification listed in [releases](https://github.com/dotkernel/api/releases).
5-
Additionally, release info can also be accessed as an [RSS](https://github.com/dotkernel/api/releases.atom) feed.
6-
7-
## Upgrade procedure
8-
9-
Once you clone Dotkernel API, you will find a [CHANGELOG.md](https://github.com/dotkernel/api/blob/5.0/CHANGELOG.md) file in the root of the project.
10-
This file contains a list of already implemented features in reverse chronological order.
11-
You can use this file to track the version of your copy of Dotkernel API.
12-
13-
For each new release you need implement the modifications from its pull requests in your project.
14-
It is recommended to copy the release info into your project's CHANGELOG.md file.
15-
This allows you to track your API's version and keep your project up-to-date with future releases.
1+
# Upgrades
2+
3+
Dotkernel API does not provide an automatic upgrade path.
4+
Instead, the recommended procedure is to manually implement each modification listed in [releases](https://github.com/dotkernel/api/releases).
5+
Additionally, release info can also be accessed as an [RSS](https://github.com/dotkernel/api/releases.atom) feed.
6+
7+
## Upgrade procedure
8+
9+
Once you clone Dotkernel API, you will find a [CHANGELOG.md](https://github.com/dotkernel/api/blob/5.0/CHANGELOG.md) file in the root of the project.
10+
This file contains a list of already implemented features in reverse chronological order.
11+
You can use this file to track the version of your copy of Dotkernel API.
12+
13+
For each new release you need implement the modifications from its pull requests in your project.
14+
It is recommended to copy the release info into your project's CHANGELOG.md file.
15+
This allows you to track your API's version and keep your project up-to-date with future releases.
16+
17+
## Version to version upgrading
18+
19+
Starting from [version 5.3](UPGRADE-5.3.md) the upgrading procedure is detailed version to version.

‎mkdocs.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ nav:
2222
- "Doctrine ORM": v5/installation/doctrine-orm.md
2323
- "Test the Installation": v5/installation/test-the-installation.md
2424
- "FAQ": v5/installation/faq.md
25-
- Upgrading: v5/upgrading.md
25+
- Upgrading:
26+
- "Upgrade procedure": v5/upgrading/upgrading.md
27+
- "Upgrading 5.2 to 5.3": v5/upgrading/UPGRADE-5.3.md
2628
- Flow:
2729
- "Middleware Flow": v5/flow/middleware-flow.md
2830
- "Default Library Flow": v5/flow/default-library-flow.md

0 commit comments

Comments
 (0)