From 63777002f766227d4954ded5da99039bb6cb0578 Mon Sep 17 00:00:00 2001 From: stereomon Date: Wed, 11 Oct 2023 13:07:32 +0200 Subject: [PATCH 1/5] PBC-3017 Added AppKernel documentation. --- _data/sidebars/acp_user_sidebar.yml | 3 + docs/acp/user/app-kernel.md | 126 ++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 docs/acp/user/app-kernel.md diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index e19eeff55e5..35e35ee28bd 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -14,6 +14,9 @@ entries: url: /docs/acp/user/app-composition-platform-installation.html - title: Developing an app url: /docs/acp/user/developing-an-app.html + nested: + - title: AppKernel + url: /docs/acp/user/app-kernel.html - title: App manifest url: /docs/acp/user/app-manifest.html - title: App configuration diff --git a/docs/acp/user/app-kernel.md b/docs/acp/user/app-kernel.md new file mode 100644 index 00000000000..ab22c4009eb --- /dev/null +++ b/docs/acp/user/app-kernel.md @@ -0,0 +1,126 @@ +--- +title: AppKernel +description: Documentation of how to use the AppKernel when developing an App with Spryker's Mini Framework +template: howto-guide-template +--- + +# Creating an App with the help of the AppKernel + +The AppKernel is a module that provides the default functionality required by most of our Apps. This includes: + +- Configure an App (receive a request from the App Store Catalog to configure this App for a Tenant) +- Disconnect an App (an App gets disconnected from a Tenant through the App Store Catalog) + +This guide provides a step-by-step description of how to use the AppKernel together with Spryker's Mini Framework to develop an App. + +## AppKernel +Basically, every App needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC the AppKernel provides this functionality out of the box. + +This includes: + +- The route provider plugin \Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin which provides Glue endpoints + - `/private/configure` - Used to receive the configuration request. + - `/private/disconnect` - Used to disconnect the App from a Tenant (configuration gets deleted). +- The controller \Spryker\Glue\App\Controller\AppConfigController::postConfigureAction() which will receive the configuration request. +- The controller \Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction() which will receive the disconnection request. + +Additionally, you can extend the AppKernel with your own business logic by using plugins in the provided extension points as outlined in the integration guide. + +## Install the required modules using Composer + +```bash +composer require spryker/app-kernel +``` + + +## Configure routes + +Add the `AppRouteProviderPlugin` to `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()`. + +## Extending Glue + +In many cases, it is required to add your own validation on top of the default validation that is provided by the AppKernel. We offer extension points for both actions Configure and Disconnect. You can use the same plugin in both places when needed. + +### Configure + +Add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins()` on the project level when needed. + +This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postConfigureAction()` before any other action is happening. + +### Disconnect + +Add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins()` on the project level when needed. + +This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postDisconnectAction()` before any other action is happening. + +## Extending Zed + +### Configure + +In some cases, you need to do additional things with the passed configuration e.g. sending a request to a third-party application, or manipulating the data before it gets saved into the database. + +You can add two plugins: + +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeSavePluginInterface` - This one will be executed before the configuration is saved in the database. +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterSavePluginInterface` - This one will be executed after the configuration was saved in the database. + +These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Writer\ConfigWriter::doSaveAppConfig()` method in a transaction. When you need to do some business logic for your App then you can use those plugins to do so and add them to the corresponding method in the \Pyz\Zed\AppKernel\AppKernelDependencyProvider on the project level when needed. + +The following methods can be used to attach your plugins: + +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeSavePlugin()` - Use this for plugins that must be executed before the data gets saved to the database. +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterSavePlugin()` - Use this for plugins that must be executed after the data was saved to the database. + +### Disconnect + +In some cases, you need to do additional things before the Tenant gets disconnected from an App (configuration will be deleted). + +You can add two plugins: + +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeDeletePluginInterface` - This one will be executed before the configuration is deleted from the database. +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterDeletePluginInterface` - This one will be executed after the configuration was deleted from the database. + +These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Deleter\ConfigDeleter::deleteConfig()` method. To prevent the further execution you have to throw an exception inside of your plugin to stop the deletion process. Please, provide a clear exception message to make it easy for anyone to fix the underlying issue. + +The following methods can be used to attach your plugins: + +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeDeletePlugin()` - Use this for plugins that must be executed before the data gets deleted from the database. +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterDeletePlugin()` - Use this for plugins that must be executed after the data was deleted from the database. + +## Saving the configuration + +Each App configuration differs from the other. We made it simple to store any configuration in the database by allowing to pass an array of the configuration to the AppConfigTransfer object. Inside of the AppKernel this array is converted into JSON and stored as such in the database. + +``` +setConfig($myAppConfigTransfer->toArray()); + +$appKernelFacade = new AppKernelFacade(); +$appKernelFacade->saveConfig($appConfigTransfer); +``` + +## Getting the Configuration + +Inside of your App you want to leverage your own Transfer object to work with the configuration. Since the configuration is store as JSON in the database we do the mapping magic inside of the AppKernel. You only need to call the AppKernelFacadeInterface::getConfig() with an AppConfigCriteriaTransfer and the Transfer object you want to populate with the stored configuration. The `AppKernelFacadeInterface::getConfig()` returns your passed TransferInterface populated with the config that was stored as JSON. + +``` +setTenantIdentifier('some-tenant-identifier'); + +$appKernelFacade = new AppKernelFacade(); +$myAppConfigTransfer = $appKernelFacade->getConfig($appConfigCriteriaTransfer, $myAppConfigTransfer); + +$myAppConfigTransfer->getFoo(); +``` + + +## Summary + +When you have done all the mentioned steps you can continue with developing the busines logic of your App. The code that integrates your App into ACP is ready to be used. From ef12093fa707c23a99493677aee4a092d4e599b0 Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Wed, 18 Oct 2023 17:11:41 +0200 Subject: [PATCH 2/5] Making the first changes --- docs/acp/user/app-kernel.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/acp/user/app-kernel.md b/docs/acp/user/app-kernel.md index ab22c4009eb..fb2c3a03945 100644 --- a/docs/acp/user/app-kernel.md +++ b/docs/acp/user/app-kernel.md @@ -1,30 +1,28 @@ --- -title: AppKernel -description: Documentation of how to use the AppKernel when developing an App with Spryker's Mini Framework +title: Create an app with AppKernel +description: Learn how to use the AppKernel when developing an App with Spryker's Mini Framework template: howto-guide-template --- -# Creating an App with the help of the AppKernel +The [AppKernel](https://github.com/spryker/app-kernel) is a module that provides the default functionality required by most of the apps. The functionality includes: -The AppKernel is a module that provides the default functionality required by most of our Apps. This includes: +- Configuration of an app: Receiving a request from the App Store Catalog to configure this app for a Tenant. +- Disconnecting an app: The App gets disconnected from a Tenant through the App Store Catalog. -- Configure an App (receive a request from the App Store Catalog to configure this App for a Tenant) -- Disconnect an App (an App gets disconnected from a Tenant through the App Store Catalog) - -This guide provides a step-by-step description of how to use the AppKernel together with Spryker's Mini Framework to develop an App. +This document provides describes how to use AppKernel together with Spryker's Mini Framework to develop an app. ## AppKernel -Basically, every App needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC the AppKernel provides this functionality out of the box. +Basically, every app needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC, AppKernel provides this functionality by default. -This includes: +This functionality includes the following components: -- The route provider plugin \Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin which provides Glue endpoints - - `/private/configure` - Used to receive the configuration request. - - `/private/disconnect` - Used to disconnect the App from a Tenant (configuration gets deleted). -- The controller \Spryker\Glue\App\Controller\AppConfigController::postConfigureAction() which will receive the configuration request. -- The controller \Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction() which will receive the disconnection request. +- The `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` route provider plugin which provides the following Glue endpoints: + - `/private/configure` - to receive the configuration request. + - `/private/disconnect` - to disconnect the app from a Tenant (configuration gets deleted). +- The `\Spryker\Glue\App\Controller\AppConfigController::postConfigureAction()` controller that receives the configuration request. +- The `\Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction()` controller that receives the disconnection request. -Additionally, you can extend the AppKernel with your own business logic by using plugins in the provided extension points as outlined in the integration guide. +Additionally, you can extend the AppKernel with your own business logic by using plugins in the provided extension points as outlined in the following sections. ## Install the required modules using Composer From c003de43ef0dedddb7f1c6bc131a5266ebdd8fb8 Mon Sep 17 00:00:00 2001 From: lenadoc Date: Thu, 19 Oct 2023 11:04:20 +0200 Subject: [PATCH 3/5] fixes according to the comments --- docs/acp/user/app-kernel.md | 44 +++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/acp/user/app-kernel.md b/docs/acp/user/app-kernel.md index fb2c3a03945..77a98304673 100644 --- a/docs/acp/user/app-kernel.md +++ b/docs/acp/user/app-kernel.md @@ -4,17 +4,15 @@ description: Learn how to use the AppKernel when developing an App with Spryker' template: howto-guide-template --- -The [AppKernel](https://github.com/spryker/app-kernel) is a module that provides the default functionality required by most of the apps. The functionality includes: +The [AppKernel](https://github.com/spryker/app-kernel) is a module that provides the default functionality required by most of the apps. The functionality includes the following actions: -- Configuration of an app: Receiving a request from the App Store Catalog to configure this app for a Tenant. -- Disconnecting an app: The App gets disconnected from a Tenant through the App Store Catalog. +- Configure an app: Receiving a request from the App Store Catalog to configure this app for a Tenant. +- Disconnect an app: The App gets disconnected from a Tenant through the App Store Catalog. -This document provides describes how to use AppKernel together with Spryker's Mini Framework to develop an app. +This document describes how to use AppKernel together with Spryker's Mini Framework to develop an app. -## AppKernel -Basically, every app needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC, AppKernel provides this functionality by default. - -This functionality includes the following components: +## Default functionality of AppKernel +Basically, every app needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC, AppKernel provides this functionality by default, including the following components: - The `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` route provider plugin which provides the following Glue endpoints: - `/private/configure` - to receive the configuration request. @@ -22,49 +20,53 @@ This functionality includes the following components: - The `\Spryker\Glue\App\Controller\AppConfigController::postConfigureAction()` controller that receives the configuration request. - The `\Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction()` controller that receives the disconnection request. -Additionally, you can extend the AppKernel with your own business logic by using plugins in the provided extension points as outlined in the following sections. +Additionally, you can extend the AppKernel with your own business logic by using plugins in the extension points as outlined in the following sections. + +## Install AppKernel -## Install the required modules using Composer +To install AppKernel, install the required modules using Composer. +Run the following command: ```bash composer require spryker/app-kernel ``` - ## Configure routes -Add the `AppRouteProviderPlugin` to `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()`. +After you have installed the AppKernel module, configure the routes by adding `AppRouteProviderPlugin` to `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()`. -## Extending Glue +## Extend Glue -In many cases, it is required to add your own validation on top of the default validation that is provided by the AppKernel. We offer extension points for both actions Configure and Disconnect. You can use the same plugin in both places when needed. +In many cases, it is necessary to add your own validation on top of the default validation that AppKernel provides. We offer extension points for both Configure and Disconnect actions. You can use the same plugin in both places when needed. ### Configure -Add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins()` on the project level when needed. +To extend the Configure action with your custom validation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins()` on the project level. -This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postConfigureAction()` before any other action is happening. +This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postConfigureAction()` before any other action happens. ### Disconnect -Add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins()` on the project level when needed. +To extend the Disconnect action with your custom navigation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins()` on the project level. This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postDisconnectAction()` before any other action is happening. ## Extending Zed +In certain scenarios, you may need to incorporate additional configuration to enhance the default behavior of the Configure and Disconnect actions. In such cases, you have the option to extend these actions within the Zed layer. + ### Configure -In some cases, you need to do additional things with the passed configuration e.g. sending a request to a third-party application, or manipulating the data before it gets saved into the database. +In some cases, you may need to perform additional tasks with the passed configuration, such as sending a request to a third-party application or manipulating the data before it is saved to the database. -You can add two plugins: +To facilitate this, you can you can implement two plugins: - `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeSavePluginInterface` - This one will be executed before the configuration is saved in the database. - `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterSavePluginInterface` - This one will be executed after the configuration was saved in the database. These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Writer\ConfigWriter::doSaveAppConfig()` method in a transaction. When you need to do some business logic for your App then you can use those plugins to do so and add them to the corresponding method in the \Pyz\Zed\AppKernel\AppKernelDependencyProvider on the project level when needed. -The following methods can be used to attach your plugins: +To add plugins to the dependency provider, you can use the following methods: - `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeSavePlugin()` - Use this for plugins that must be executed before the data gets saved to the database. - `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterSavePlugin()` - Use this for plugins that must be executed after the data was saved to the database. @@ -80,7 +82,7 @@ You can add two plugins: These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Deleter\ConfigDeleter::deleteConfig()` method. To prevent the further execution you have to throw an exception inside of your plugin to stop the deletion process. Please, provide a clear exception message to make it easy for anyone to fix the underlying issue. -The following methods can be used to attach your plugins: +To add plugins to the dependency provider, you can use the following methods: - `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeDeletePlugin()` - Use this for plugins that must be executed before the data gets deleted from the database. - `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterDeletePlugin()` - Use this for plugins that must be executed after the data was deleted from the database. From d3b53f33312db759be6b5ede77a7783aa53abed6 Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Thu, 19 Oct 2023 12:06:02 +0200 Subject: [PATCH 4/5] Finalizing the file --- _data/sidebars/acp_user_sidebar.yml | 4 +- docs/acp/user/app-kernel.md | 126 ----------------- docs/acp/user/create-an-app with-appkernel.md | 127 ++++++++++++++++++ 3 files changed, 129 insertions(+), 128 deletions(-) delete mode 100644 docs/acp/user/app-kernel.md create mode 100644 docs/acp/user/create-an-app with-appkernel.md diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index 35e35ee28bd..ed993ace8b8 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -15,8 +15,8 @@ entries: - title: Developing an app url: /docs/acp/user/developing-an-app.html nested: - - title: AppKernel - url: /docs/acp/user/app-kernel.html + - title: Create and app with AppKernel + url: /docs/acp/user/create-an-app with-appkernel.html - title: App manifest url: /docs/acp/user/app-manifest.html - title: App configuration diff --git a/docs/acp/user/app-kernel.md b/docs/acp/user/app-kernel.md deleted file mode 100644 index 77a98304673..00000000000 --- a/docs/acp/user/app-kernel.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Create an app with AppKernel -description: Learn how to use the AppKernel when developing an App with Spryker's Mini Framework -template: howto-guide-template ---- - -The [AppKernel](https://github.com/spryker/app-kernel) is a module that provides the default functionality required by most of the apps. The functionality includes the following actions: - -- Configure an app: Receiving a request from the App Store Catalog to configure this app for a Tenant. -- Disconnect an app: The App gets disconnected from a Tenant through the App Store Catalog. - -This document describes how to use AppKernel together with Spryker's Mini Framework to develop an app. - -## Default functionality of AppKernel -Basically, every app needs to be configured for each Tenant individually. To prevent this logic from being implemented with each PBC, AppKernel provides this functionality by default, including the following components: - -- The `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` route provider plugin which provides the following Glue endpoints: - - `/private/configure` - to receive the configuration request. - - `/private/disconnect` - to disconnect the app from a Tenant (configuration gets deleted). -- The `\Spryker\Glue\App\Controller\AppConfigController::postConfigureAction()` controller that receives the configuration request. -- The `\Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction()` controller that receives the disconnection request. - -Additionally, you can extend the AppKernel with your own business logic by using plugins in the extension points as outlined in the following sections. - -## Install AppKernel - -To install AppKernel, install the required modules using Composer. -Run the following command: - -```bash -composer require spryker/app-kernel -``` - -## Configure routes - -After you have installed the AppKernel module, configure the routes by adding `AppRouteProviderPlugin` to `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()`. - -## Extend Glue - -In many cases, it is necessary to add your own validation on top of the default validation that AppKernel provides. We offer extension points for both Configure and Disconnect actions. You can use the same plugin in both places when needed. - -### Configure - -To extend the Configure action with your custom validation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins()` on the project level. - -This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postConfigureAction()` before any other action happens. - -### Disconnect - -To extend the Disconnect action with your custom navigation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins()` on the project level. - -This plugin will be executed inside the `\Spryker\Glue\AppKernel\Controller\AppConfigController::postDisconnectAction()` before any other action is happening. - -## Extending Zed - -In certain scenarios, you may need to incorporate additional configuration to enhance the default behavior of the Configure and Disconnect actions. In such cases, you have the option to extend these actions within the Zed layer. - -### Configure - -In some cases, you may need to perform additional tasks with the passed configuration, such as sending a request to a third-party application or manipulating the data before it is saved to the database. - -To facilitate this, you can you can implement two plugins: - -- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeSavePluginInterface` - This one will be executed before the configuration is saved in the database. -- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterSavePluginInterface` - This one will be executed after the configuration was saved in the database. - -These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Writer\ConfigWriter::doSaveAppConfig()` method in a transaction. When you need to do some business logic for your App then you can use those plugins to do so and add them to the corresponding method in the \Pyz\Zed\AppKernel\AppKernelDependencyProvider on the project level when needed. - -To add plugins to the dependency provider, you can use the following methods: - -- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeSavePlugin()` - Use this for plugins that must be executed before the data gets saved to the database. -- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterSavePlugin()` - Use this for plugins that must be executed after the data was saved to the database. - -### Disconnect - -In some cases, you need to do additional things before the Tenant gets disconnected from an App (configuration will be deleted). - -You can add two plugins: - -- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeDeletePluginInterface` - This one will be executed before the configuration is deleted from the database. -- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterDeletePluginInterface` - This one will be executed after the configuration was deleted from the database. - -These plugins will be executed inside of the `\Spryker\Zed\AppKernel\Business\Deleter\ConfigDeleter::deleteConfig()` method. To prevent the further execution you have to throw an exception inside of your plugin to stop the deletion process. Please, provide a clear exception message to make it easy for anyone to fix the underlying issue. - -To add plugins to the dependency provider, you can use the following methods: - -- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeDeletePlugin()` - Use this for plugins that must be executed before the data gets deleted from the database. -- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterDeletePlugin()` - Use this for plugins that must be executed after the data was deleted from the database. - -## Saving the configuration - -Each App configuration differs from the other. We made it simple to store any configuration in the database by allowing to pass an array of the configuration to the AppConfigTransfer object. Inside of the AppKernel this array is converted into JSON and stored as such in the database. - -``` -setConfig($myAppConfigTransfer->toArray()); - -$appKernelFacade = new AppKernelFacade(); -$appKernelFacade->saveConfig($appConfigTransfer); -``` - -## Getting the Configuration - -Inside of your App you want to leverage your own Transfer object to work with the configuration. Since the configuration is store as JSON in the database we do the mapping magic inside of the AppKernel. You only need to call the AppKernelFacadeInterface::getConfig() with an AppConfigCriteriaTransfer and the Transfer object you want to populate with the stored configuration. The `AppKernelFacadeInterface::getConfig()` returns your passed TransferInterface populated with the config that was stored as JSON. - -``` -setTenantIdentifier('some-tenant-identifier'); - -$appKernelFacade = new AppKernelFacade(); -$myAppConfigTransfer = $appKernelFacade->getConfig($appConfigCriteriaTransfer, $myAppConfigTransfer); - -$myAppConfigTransfer->getFoo(); -``` - - -## Summary - -When you have done all the mentioned steps you can continue with developing the busines logic of your App. The code that integrates your App into ACP is ready to be used. diff --git a/docs/acp/user/create-an-app with-appkernel.md b/docs/acp/user/create-an-app with-appkernel.md new file mode 100644 index 00000000000..9fa98cd34e4 --- /dev/null +++ b/docs/acp/user/create-an-app with-appkernel.md @@ -0,0 +1,127 @@ +--- +title: Create an app with AppKernel +description: Learn how to use the AppKernel when developing an App with Spryker's Mini Framework +template: howto-guide-template +--- + +The [AppKernel](https://github.com/spryker/app-kernel) is a module that provides the default functionality required by most of the apps. The functionality includes the following actions: + +- Configure an app: Receiving a request from the App Store Catalog to configure the app for a Tenant. +- Disconnect an app: The App gets disconnected from a Tenant through the App Store Catalog. + +This document describes how to use AppKernel together with Spryker's Mini Framework to develop an app. + +## Default functionality of AppKernel + +Every app needs to be individually configured for each Tenant. To avoid implementing this logic in each PBC, AppKernel provides it by default, including the following components: + +- The `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` route provider plugin provides the following Glue endpoints: + - `/private/configure` - to receive the configuration request. + - `/private/disconnect` - to disconnect the app from a Tenant (configuration gets deleted). +- The `\Spryker\Glue\App\Controller\AppConfigController::postConfigureAction()` controller receives the configuration request. +- The `\Spryker\Glue\App\Controller\AppDisconnectController::postDisconnectAction()` controller receives the disconnection request. + +Additionally, you can extend the AppKernel with your own business logic by using plugins in the extension points, as outlined in the following sections. + +## Install AppKernel + +To install AppKernel, install the required modules using Composer. + +Run the following command: + +```bash +composer require spryker/app-kernel +``` + +## Configure routes + +After you have installed the AppKernel module, configure the routes by adding `AppRouteProviderPlugin` to `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()`. + +## Extend Glue + +It is often necessary to add your own validation on top of the default validation that AppKernel provides. We offer extension points for both Configure and Disconnect actions. You can use the same plugin in both places when needed. + +### Configure + +To extend the Configure action with your custom validation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins()` on the project level. + +This plugin is executed in `\Spryker\Glue\AppKernel\Controller\AppConfigController::postConfigureAction()` before any other action happens. + +### Disconnect + +To extend the Disconnect action with your custom navigation, add a class that implements `\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface` and add it to `\Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins()` on the project level. + +This plugin is executed in `\Spryker\Glue\AppKernel\Controller\AppConfigController::postDisconnectAction()` before any other action happens. + +## Extending Zed + +In certain scenarios, you may need to incorporate additional configuration to enhance the default behavior of the Configure and Disconnect actions. In such cases, you can extend these actions within the Zed layer. + +### Configure + +Sometimes, you may need to perform additional tasks with the passed configuration, such as sending a request to a third-party application or manipulating the data before it is saved to the database. + +To facilitate this, you can you can implement two plugins: + +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeSavePluginInterface`: to be executed before the configuration is saved in the database. +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterSavePluginInterface`: to be executed after the configuration was saved in the database. + +These plugins are executed in the `\Spryker\Zed\AppKernel\Business\Writer\ConfigWriter::doSaveAppConfig()` method in a transaction. When you need to implement some business logic for your app, you can use these plugins for this and add them to the corresponding method in `\Pyz\Zed\AppKernel\AppKernelDependencyProvider` on the project level if necessary. + +To add plugins to the dependency provider, you can use the following methods: + +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeSavePlugin()`: for plugins that must be executed before the data gets saved to the database. +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterSavePlugin()`: for plugins that must be executed after the data was saved to the database. + +### Disconnect + +Sometimes, you may need to perform additional tasks before the Tenant gets disconnected from an app and the configuration is deleted. + +To facilitate this, you can you can implement two plugins: + +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeDeletePluginInterface`: to be executed before the configuration is deleted from the database. +- `\Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterDeletePluginInterface`: to be executed after the configuration was deleted from the database. + +These plugins are executed in the `\Spryker\Zed\AppKernel\Business\Deleter\ConfigDeleter::deleteConfig()` method. To prevent their further execution, you must throw an exception inside your plugin to stop the deletion process. We recommend providing a clear exception message to make it easy for anyone to fix the underlying issue. + +To add plugins to the dependency provider, you can use the following methods: + +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeDeletePlugin()`: for plugins that must be executed before the data gets deleted from the database. +- `\Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterDeletePlugin()`: for plugins that must be executed after the data was deleted from the database. + +## Saving the configuration + +Each app configuration differs from the other. We made it simple to store any configuration in the database by allowing to pass an array of the configuration to the `AppConfigTransfer` object. Inside the AppKernel, this array is converted into JSON and stored as such in the database: + +``` +setConfig($myAppConfigTransfer->toArray()); + +$appKernelFacade = new AppKernelFacade(); +$appKernelFacade->saveConfig($appConfigTransfer); +``` + +## Getting the Configuration + +From within your app, you can use your own Transfer object to work with the configuration. Since the configuration is stored as a JSON file in the database, the mapping is done inside AppKernel. You only need to call the `AppKernelFacadeInterface::getConfig()` with `AppConfigCriteriaTransfer` and the Transfer object you want to populate with the stored configuration. The `AppKernelFacadeInterface::getConfig()` returns your passed `TransferInterface` object, now populated with the configuration that was stored as JSON: + +``` +setTenantIdentifier('some-tenant-identifier'); + +$appKernelFacade = new AppKernelFacade(); +$myAppConfigTransfer = $appKernelFacade->getConfig($appConfigCriteriaTransfer, $myAppConfigTransfer); + +$myAppConfigTransfer->getFoo(); +``` + +## Next steps + +Once you have completed all the steps from this document, you can proceed with the development of your app's business logic. The code that integrates your app into ACP is ready to use. From 47990ff0c5afb4a5229abf67cfbea801478177aa Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Thu, 19 Oct 2023 13:34:11 +0200 Subject: [PATCH 5/5] fixing the navigation --- _data/sidebars/acp_user_sidebar.yml | 4 ++-- .../{ => developing-an-app}/create-an-app with-appkernel.md | 0 docs/acp/user/{ => developing-an-app}/developing-an-app.md | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) rename docs/acp/user/{ => developing-an-app}/create-an-app with-appkernel.md (100%) rename docs/acp/user/{ => developing-an-app}/developing-an-app.md (99%) diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index ed993ace8b8..5af6f495d91 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -13,10 +13,10 @@ entries: - title: Install ACP catalog url: /docs/acp/user/app-composition-platform-installation.html - title: Developing an app - url: /docs/acp/user/developing-an-app.html + url: /docs/acp/user/developing-an-app/developing-an-app.html nested: - title: Create and app with AppKernel - url: /docs/acp/user/create-an-app with-appkernel.html + url: /docs/acp/user/developing-an-app/create-an-app with-appkernel.html - title: App manifest url: /docs/acp/user/app-manifest.html - title: App configuration diff --git a/docs/acp/user/create-an-app with-appkernel.md b/docs/acp/user/developing-an-app/create-an-app with-appkernel.md similarity index 100% rename from docs/acp/user/create-an-app with-appkernel.md rename to docs/acp/user/developing-an-app/create-an-app with-appkernel.md diff --git a/docs/acp/user/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md similarity index 99% rename from docs/acp/user/developing-an-app.md rename to docs/acp/user/developing-an-app/developing-an-app.md index a5c6e6eb517..57a9bbb5e0e 100644 --- a/docs/acp/user/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -2,6 +2,8 @@ title: Developing an app Descriptions: Learn how to develop an app template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html --- To develop an app, follow the instructions in this document.