Merge pull request #1827 from jolelievre/kernels-doc

Explain new Symfony kernel split

modules/core-updates/9.0.md

@@ -85,6 +85,38 @@ Some dependencies are still present but were upgraded which comes with their own
 - [Services translator, security.csrf.token_manager, session, session.flash_bag no longer public](https://github.com/PrestaShop/PrestaShop/pull/35069)
 - [Replace AdminSecurity annotation with attributes](https://github.com/PrestaShop/PrestaShop/pull/35212)
 
+### Kernel modifications
+
+Until PrestaShop 8.0, we relied on one Kernel used for the back office. In Symfony 9.0, we expanded the usage of the Symfony framework, especially for two new features:
+- the new Admin API based on API Platform and OAuth authentication
+- an experimental feature that gives access to a Symfony container in the front office (in opposition to the custom-built container available today). This one is not very much used yet, but it's a first stone for the future front office migration
+
+Those two new environments have mechanisms and configuration different from those in the back office. To separate these configurations cleanly, they each have their dedicated kernel class and their own configuration. This allows to cleanly define different routing, security configurations, dedicated services, listeners, ...
+Each kernel has a unique `applicationId` that allows to dynamize its configuration and cache folder (since the services are not the same, each kernel needs its own cache folder). The `appId` parameter has also been added globally to the `bin/console` tool. They all share the common `app/config/config.yml` configuration file, but each one extends it in its own config folder.
+
+| Environment                 | Kernel class     | Config folder          | Cache folder                          | Endpoint               | Application ID |
+|-----------------------------|------------------|------------------------|---------------------------------------|------------------------|----------------|
+| Back office                 | `AdminKernel`    | `app/config/admin`     | `var/cache/{dev,prod,test}/admin`     | `/admin-dev/index.php` | `admin`        |
+| Admin API                   | `AdminAPIKernel` | `app/config/admin-api` | `var/cache/{dev,prod,test}/admin-api` | `/admin-api/index.php` | `admin-api`    |
+| Front office (experimental) | `FrontKernel`    | `app/config/front`     | `var/cache/{dev,prod,test}/front`     | `/index.php`           | `front`        |
+
+{{% notice note %}}
+**Console usage**
+
+Clear the cache of the Admin API for its `prod` environment
+
+`php bin/console cache:clear --env=prod --app-id=admin-api`
+
+Display event listeners for the back office in `dev` environment (default value of `app-id` is `admin` for retro compatibility)
+
+`php bin/console debug:event-dispatcher kernel.request --env=dev`
+{{% /notice %}}
+
+**Related PRs**
+
+- [Experimental front container](https://github.com/PrestaShop/PrestaShop/pull/32719)
+- [Admin API has dedicated kernel, we now have three distinct configurations](https://github.com/PrestaShop/PrestaShop/pull/35515)
+
 ### BO login and authorization migrated to Symfony
 
 The back office login page has been migrated to Symfony. Along with this change, the authorization system in the back office is now also based on Symfony, which implies several things:
@@ -119,7 +151,6 @@ if ($session) {
 The Symfony session has other interesting features (like flash bags for unique usage data). You can read more about its usage in the <a href="https://symfony.com/doc/6.4/session.html" target="_blank">Session documentation</a>.
 {{% /notice %}}
 
-
 **Removed hooks:**
 - `actionAdminLoginControllerBefore`
 - `actionAdminLoginControllerLoginBefore`
@@ -204,13 +235,6 @@ This changes the data passed to the smarty templates:
 
 - [Modified LanguageInterface and LocaleInterface](https://github.com/PrestaShop/PrestaShop/pull/34500)
 
-### Kernel modifications
-
-@todo Explain the three new kernels and their respective folders for configurations
-
-- [Experimental front container](https://github.com/PrestaShop/PrestaShop/pull/32719)
-- [Admin API has dedicated kernel, we now have three distinct configurations](https://github.com/PrestaShop/PrestaShop/pull/35515)
-
 ### Change of behaviour/rules or removed code
 
 - [Customization quantity feature has been removed](https://github.com/PrestaShop/PrestaShop/pull/12422), the customization quantity is now the one from the cart_product row