From 4e0f07b5d80e67982ec09245b26db011f3e94f71 Mon Sep 17 00:00:00 2001 From: strelchenko Date: Wed, 6 Dec 2023 14:25:55 +0200 Subject: [PATCH 1/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path --- .../code-snippets/configuration.md | 68 ++++++ .../code-snippets/manifest.md | 56 +++++ .../code-snippets/translation.md | 44 ++++ .../create-an-app-with-appkernel.md | 130 ---------- .../debug-an-app-with-xdebug.md | 34 +++ .../developing-an-app/developing-an-app.md | 223 ++++++++++++------ .../setting-up-message-broker.md | 75 ++++++ docs/acp/user/intro-to-acp/acp-overview.md | 2 +- 8 files changed, 430 insertions(+), 202 deletions(-) create mode 100644 docs/acp/user/developing-an-app/code-snippets/configuration.md create mode 100644 docs/acp/user/developing-an-app/code-snippets/manifest.md create mode 100644 docs/acp/user/developing-an-app/code-snippets/translation.md delete mode 100644 docs/acp/user/developing-an-app/create-an-app-with-appkernel.md create mode 100644 docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md create mode 100644 docs/acp/user/developing-an-app/setting-up-message-broker.md diff --git a/docs/acp/user/developing-an-app/code-snippets/configuration.md b/docs/acp/user/developing-an-app/code-snippets/configuration.md new file mode 100644 index 00000000000..3edc22d8867 --- /dev/null +++ b/docs/acp/user/developing-an-app/code-snippets/configuration.md @@ -0,0 +1,68 @@ +--- +title: Configuration Json +Descriptions: Configuration Json code snippet +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +--- + +This is a `configuration.json` for the Hello World App. This is an example file where we assume the App needs a `clientId` and a `clientSecret` to be configured. On top of this, we can also enable/disable the App via the App Store Catalog. +This file has to be in config/app/configuration.json of your App. + +```json +{ + "properties": { + "clientId": { + "type": "string", + "title": "clientId_title", + "placeholder": "clientId_placeholder", + "isRequired": true, + "isLockable": true, + "widget": { + "id": "password" + } + }, + "clientSecret": { + "type": "string", + "title": "clientSecret_title", + "placeholder": "clientSecret_placeholder", + "isRequired": true, + "isLockable": true, + "widget": { + "id": "password" + } + }, + "isActive": { + "type": "boolean", + "title": "isActive_title", + "widget": { + "id": "app-status" + }, + "default": false + } + }, + "fieldsets": [ + { + "id": "notifications", + "fields": [ + "isActive" + ], + "layout": "noLayout" + }, + { + "id": "configurations", + "title": "configurations_fieldset_title", + "fields": [ + "clientId", + "clientSecret" + ], + "hint": "configurations_hint" + } + ], + "required": [ + "clientId", + "clientSecret", + "isActive" + ] +} +``` diff --git a/docs/acp/user/developing-an-app/code-snippets/manifest.md b/docs/acp/user/developing-an-app/code-snippets/manifest.md new file mode 100644 index 00000000000..49180cd54a7 --- /dev/null +++ b/docs/acp/user/developing-an-app/code-snippets/manifest.md @@ -0,0 +1,56 @@ +--- +title: Manifest Json +Descriptions: Manifest Json code snippet +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +--- + +This is an example manifest for the English version of the Hello World App. + +This file has to be placed in `config/app/manifest/en_US.json` in your App. + +```json +{ + "name": "Hello World App", + "provider": "Example, Inc.", + "description": "Simple Hello World App for showcasing.", + "descriptionShort": "Hello World App.", + "url": "https://www.example.com", + "isAvailable": true, + "categories": [ + "PLAYGROUND" + ], + "assets": [ + { + "type": "icon", + "url": "/assets/img/hello-world/logo.png" + }, + { + "type": "image", + "url": "/assets/img/hello-world/gallery/image.png" + } + ], + "resources": [ + { + "title": "User Guide", + "url": "https://docs.spryker.com/docs/acp/user/intro-to-acp/acp-overview.html", + "type": "internal-documentation", + "fileType": "spryker-docs" + } + ], + "pages": { + "Overview": [] + }, + "labels": [], + "businessModels": [ + "B2C", + "B2B", + "B2C_MARKETPLACE", + "B2B_MARKETPLACE" + ], + "dependencies": [], + "dialogs": {}, + "developedBy": "Spryker Systems GmbH" +} +``` diff --git a/docs/acp/user/developing-an-app/code-snippets/translation.md b/docs/acp/user/developing-an-app/code-snippets/translation.md new file mode 100644 index 00000000000..86bb3570e86 --- /dev/null +++ b/docs/acp/user/developing-an-app/code-snippets/translation.md @@ -0,0 +1,44 @@ +--- +title: Translation Json +Descriptions: Translation Json code snippet +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +--- + +This is a `translation.json` for the Hello World App. This file is used to translate the form fields which are defined in the `configuration.json`. + +This file has to be in `config/app/translation.json` of your App. + +```json +{ + "configurations_fieldset_title": { + "en_US": "Configurations", + "de_DE": "Konfigurationen" + }, + "configurations_hint": { + "en_US": "Add the Client details.", + "de_DE": "Füge die Client details hinzu." + }, + "clientId_title": { + "en_US": "Client ID", + "de_DE": "Client ID" + }, + "clientId_placeholder": { + "en_US": "Enter Client ID here.", + "de_DE": "Geben Sie hier die Client ID ein." + }, + "clientSecret_title": { + "en_US": "Client Secret", + "de_DE": "Client Secret" + }, + "clientSecret_placeholder": { + "en_US": "Enter Client Secret here.", + "de_DE": "Geben Sie hier den Client Secret ein." + }, + "isActive_title": { + "en_US": "Activate", + "de_DE": "Aktivieren" + } +} +``` diff --git a/docs/acp/user/developing-an-app/create-an-app-with-appkernel.md b/docs/acp/user/developing-an-app/create-an-app-with-appkernel.md deleted file mode 100644 index efd8017a690..00000000000 --- a/docs/acp/user/developing-an-app/create-an-app-with-appkernel.md +++ /dev/null @@ -1,130 +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 -redirect_from: -- /docs/acp/user/developing-an-app/create-an-app with-appkernel.html -- /docs/acp/user/developing-an-app/create-an-app%20with-appkernel.html ---- - -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. diff --git a/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md b/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md new file mode 100644 index 00000000000..104e647d504 --- /dev/null +++ b/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md @@ -0,0 +1,34 @@ +--- +title: Debugging Your App with Xdebug +Descriptions: Learn how to use Xdebug +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +--- + +## Introduction + +Debugging your application becomes a seamless process with the provided DockerSDK, which comes equipped with a configuration to effortlessly run your app with Xdebug. This guide will walk you through the steps to set up and use Xdebug for debugging purposes. + +### Setting Up DockerSDK with XDebug + +To start a testing container with XDebug enabled (disabled in the default container), execute the following command in your terminal: + +```bash +docker/sdk testing -x +``` + + +### Configuring PHPStorm for XDebug + +1. Open PHPStorm and navigate to Preferences → PHP → Servers. +2. Click the "+" sign to add a new configuration with the following details: + - Name: spryker + - Host: spryker.local +3. Enable the Use path mappings option, selecting it based on whether the server is remote or if symlinks are used. For example, map the path from /path/to/root/of/the/app to /data. +4. Click `Apply` and then `OK` to save the configuration. + +Now, PHPStorm is ready to accept XDebug connections, and you can efficiently debug your application using Xdebug. + +Remember that these steps may vary slightly depending on your specific development environment, but this general guide should help you set up Xdebug for debugging in most scenarios. + diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md index baa3ee4dcbd..bb4fd579303 100644 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -1,19 +1,29 @@ --- -title: Developing an app -Descriptions: Learn how to develop an app +title: Developing an App +Descriptions: Learn the step-by-step process of developing an app using Spryker's Mini-Framework template: howto-guide-template redirect_from: - /docs/acp/user/developing-an-app.html --- -To develop an app, follow the instructions in this document. +# Developing an App with Spryker Mini-Framework + +This guide will walk you through the process of developing an app using Spryker's Mini-Framework. Follow the steps below to set up and start your app development. ## Prerequisites -- You have completed the [thought process](#thought-process) for your app. -- You have [installed the Spryker SDK](/docs/sdk/dev/spryker-sdk.html#installation). -- You have an empty GitHub repository. -- You have a local project directory where you want to work, for example, `/www/my-app`. +Before you begin, ensure that you have the following prerequisites in place: + +- Completed the [thought process](#thought-process) for your app. +- An empty GitHub repository. +- A local project directory for your app (e.g., `/www/my-app`). +- [DockerSDK](https://github.com/spryker/docker-sdk) installed globally. + +Make sure you have Spryker Docker SDK, Git, and an empty repository for your app code. + +{% info_block infoBox "Info" %} +Download the completed example from the Mini-Framework [here](https://github.com/spryker-projects/mini-framework). +{% endinfo_block %} ## Thought process First, think about what your app should be capable of: what features it will bring, and what data will be exchanged, not only to you but also to those interested in your app functionality. For example, what messages could be of interest to others, and what API endpoints you should provide. @@ -28,130 +38,201 @@ You need to have a clear understanding of what your app API will provide to othe Before you start with the development, you should design your API schema files. Depending on your requirements, you can have an OpenAPI or an [Async API](#async-api) schema file. In this step, you define the [Sync API](#sync-api) endpoints your app will provide to others, the messages you will emit or consume, and the data you expect to work with. {% info_block infoBox "Info" %} - For more information about Async API schema design, see [Designing your APIs with Async API](https://www.asyncapi.com/blog/designing_your_apis_with_asyncapi_part_1). For more information about OpenAPI schema design, see [Best practices in API design](https://swagger.io/resources/articles/best-practices-in-api-design/). - {% endinfo_block %} You can use the following tools to design your APIs: - [Async API Studio](https://studio.asyncapi.com/) - [Swagger Editor](https://editor.swagger.io/) -You can also use wizards provided by Spryker, which will be used by the [Spryker SDK workflow](/docs/sdk/dev/initialize-and-run-workflows.html). +## Create an app + +Creating an app is straightforward. Execute the following commands: +```bash +mkdir my-app +cd my-app +git clone https://github.com/spryker-projects/mini-framework.git . --depth 1 && rm -rf .git && git init +git add --all +git commit -m "first commit" +``` -## Build an app +After these steps, you will have a new local repository that needs to be linked with your remote one. -You can build a new app with the help of the [Spryker SDK](/docs/sdk/dev/spryker-sdk.html). After you have [installed the Spryker SDK](/docs/sdk/dev/spryker-sdk.html#installation), you can run the following commands to start building the app. +If not done yet, create a new remote repository by opening your [Github account](https://github.com/newConnect). After you created a new repository, GitHub shows you instructions on how to continue. You should follow the list below as you don’t need some of the first steps proposed by GitHub as we’ve already initialized git and we already have a `README.md` from the cloned repository. -1. Ensure that you are in the correct working directory: +{% info_block infoBox "Info" %} +This step can also be done later +{% endinfo_block %} ```bash -cd /www/my-app # The local project directory you created before +git branch -M main +git remote add origin git@github.com:/.git +git push -u origin main ``` -2. Initialize the project: + +Now you have done the groundwork that enables you to develop an App. You created a new repository that contains the boilerplate code for almost any App you’d like to build. + +## Start local development environment + +The Mini-Framework already comes with a predefined Docker configuration. Change the `deploy.dev.yml` and replace `glue-backend.de.spryker.local` with `my-app.de.spryker.local` and then run the following command in the root of your new repository. + +### Boot and Up your environment + +With this command, you will boot your application and start it ```bash -spryker-sdk sdk:init:project --workflow=app +docker/sdk boot deploy.dev.yml +docker/sdk up ``` -3. Run the workflow: + +After creating the development environment for you, you have several ways of using the App. The easiest one is to run the test suite. ```bash -spryker-sdk sdk:workflow:run +docker/sdk testing codecept run ``` -{% info_block infoBox "Info" %} +You will see now that your App boilerplate code is running. -You can skip through the prompts by hitting **Enter**. +## Adding App manifest files -{% endinfo_block %} +Before your App can be listed in the App Store Catalog you need to add the following files. -Starting from [Spryker SDK](/docs/sdk/dev/spryker-sdk.html) version 0.3.0, you can use the following set of commands: +### Manifest -```bash -cd /www/my-app # The local project directory you created before -spryker-sdk sdk:workflow:run # and select the app workflow -``` -The workflow guides you as much as possible through the process of building an app. Whenever something needs manual interaction, the workflow stops with a message on what you need to do. After you completed the manual step, re-run the workflow with the `spryker-sdk sdk:workflow:run` command. This continues the previously paused workflow. +The manifest file is the most important one for the App and contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/developing-an-app/code-snippets/manifest.html) and update it to your needs. Add this file to `config/app/manifest/en_US.json` of your App. -### Workflow details +Manifest files have to have the local name as file name e.g. `en_US.json` and the file has to be placed inside the `config/app/manifest` directory. -The `spryker-sdk sdk:workflow:run` command guides you through the whole process of building an app. This command does the following. +### Configuration -#### 1. Downloads the boilerplate code and adds app definition files +This file contains all necessary form fields for inputs required by the user of your App to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/developing-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your App. -One of the first steps of the workflow is downloading a reduced Spryker project into the working directory. It already contains a lot of code that lets you start implementing your business logic. -This step can take a few minutes to complete. +### Translation -{% info_block infoBox "Info" %} +This file contains all translations for the form fields you’ve previously defined. You can use the Hello World example translation file and update it to your needs. Add this file to `config/app/translation.json` of your App. -At this point, no dependencies are installed. +## Adding the Registry code -{% endinfo_block %} +Every App needs some default endpoints for the App Registry Service. This service is in between of the App Store Catalog and all Apps. Each App will be registered in the App Registry Service and to be able to configure your App needs the following endpoints for communication: + - Configure + - Disconnect -There are a couple of files that an app must have. The workflow guides you through creating them. +To be able to use your Mini Framework as an App you need to add a new Spryker module: +```bash +docker/sdk cli composer require spryker/app-kernel spryker/message-broker-aws spryker/propel-encryption-behavior +``` +This `spryker/app-kernel` module will make the Mini-Framework an App. It provides SyncAPI schema and code for configuration and disconnection as well as an AsyncAPI schema and code for the AppConfigure and AppDisconnect messages. +The `spryker/message-broker-aws` module installs the needed plugins which will be used to send and receive messages. In addition to installing the modules you need to configure them. -##### Manifest files -The manifest files define the details like title, category, and description of the app. The manifest files are also used to display information about the app on the App Catalog Page and the App Detail Page in the Back office. +## Setup the Message Broker -For more details on the manifest files, see [App manifest](/docs/acp/user/app-manifest.html). +The MessageBroker needs to be installed and configured. Follow the description on this page [Setup the MessageBroker](/docs/acp/user/developing-an-app/setting-up-message-broker.html). -{% info_block infoBox "Info" %} +## Config -You need to update the manifest file manually. The SDK only creates a boilerplate file. +Every App needs an app identifier to be identifyable in the App Eco System. Add the following configuration to your `config/Shared/config_default.php` -{% endinfo_block %} +```php +use Spryker\Shared\AppKernel\AppKernelConstants; + +$config[AppKernelConstants::APP_IDENTIFIER] = getenv('APP_IDENTIFIER') ?: 'hello-world'; +``` + +## Plugins + +You need to add some Plugins to your App to enable certain functionality. -##### Configuration file -The configuration file defines the form that is displayed in the Back Office App Catalog after the App was connected and needed some configuration. +### AppRouteProviderPlugin -This file is created with the help of a wizard, but you can also add or update it manually. +Add the `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` to the `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()` method. In case the method doesn’t exist add the complete method. -For more details, see [App Configuration](/docs/acp/user/app-configuration.html). +```php + + */ + protected function getRouteProviderPlugins(): array + { + return [ + new AppRouteProviderPlugin(), + ]; + } +} +``` -For more details, see [App Configuration Translation](/docs/acp/user/app-configuration-translation.html). +This enables the two required endpoints for the App Catalog Communication. -#### 2. Creates app API +## Building the Transfer Objects -The command defines Sync API and Async API. +Transfer objects are used in many place and since we installed some modules we also need to run the console command to generate the transfers. -##### Sync API -The Sync API defines the app's synchronous endpoints, or [Glue](/docs/scos/dev/glue-api-guides/{{site.version}}/old-glue-infrastructure/glue-rest-api.html) endpoints. The workflow creates a boilerplate that you need to update with the required endpoints your app should have. See the [current OpenAPI specification](https://spec.openapis.org/oas/v3.1.0). +```bash +docker/sdk cli console transfer:generate +``` -For more details about the Sync API with information specific to Spryker, see [Sync API](/docs/acp/user/sync-api.html). +## Update the Database -##### Async API +Transfer objects are used in many place and since we installed some modules we also need to run the console command to generate the transfers. -The Async API defines the app's asynchronous endpoints, also known as events and messaging. The workflow creates a boilerplate one that you need to update with the required endpoints your app should have. See the [current Async API specification](https://www.asyncapi.com/docs/reference). +```bash +docker/sdk cli console propel:install +``` -For more details about the Async API with information specific to Spryker, see [Async API](/docs/acp/user/async-api.html). +## Testing the endpoints -![acp-sdk-workflow-2](https://spryker.s3.eu-central-1.amazonaws.com/docs/aop/dev/developing-an-app/ACP-SDK-Workflow-black-2.jpg) +You can now test the configure request with the following snippets. Run the cURL snippets from your host machine. -#### 3. Runs code generators -After the previous steps were executed and you updated the API schema files to your needs, the code generators are executed. The code generators load the schema files and create as much code, including tests, as possible. +### Testing the /private/configure endpoint -{% info_block warningBox "Warning" %} +```bash +curl --location --request POST 'http://my-app.de.spryker.local/private/configure' \ +--header 'Content-Type: application/vnd.api+json' \ +--header 'Accept: application/vnd.api+json' \ +--header 'Accept-Language: en-US, en;q=0.9,*;q=0.5' \ +--header 'X-Tenant-Identifier: dev-US' \ +--data-raw '{ + "data": { + "type": "configuration", + "attributes": { + "configuration": "{\"clientId\":\"clientId\",\"clientSecret\":\"clientSecret\",\"securityUri\":\"securityUri\",\"transactionCallsUri\":\"transactionCallsUri\",\"isActive\": false,\"isInvoicingEnabled\": false}" + } + } +}' +``` -Review the generated code carefully. +You can check now your database if it contains the newly created configuration in the `spy_app_config` table. -{% endinfo_block %} +### Testing the /private/disconnect endpoint + +```bash +curl --location --request POST 'http://my-app.de.spryker.local/private/disconnect' \ +--header 'Content-Type: application/vnd.api+json' \ +--header 'Accept: application/vnd.api+json' \ +--header 'Accept-Language: de-DE, en;q=0.9,*;q=0.5' \ +--header 'X-Tenant-Identifier: dev-US' \ +--data-raw '' +``` -![acp-sdk-workflow-3](https://spryker.s3.eu-central-1.amazonaws.com/docs/aop/dev/developing-an-app/ACP-SDK-Workflow-black-3.jpg) +You can check now your database if previously created configuration in the spy_app_config table is removed. -#### 4. Performs validation +## Summary +Your app is now ready to be used, although it doesn't contain any business logic yet. +Start implementing the business logic by Implementing a Synchronous API and/or Implementing an Asynchronous API. -The workflow executes some validations during the process. The workflow stops when some validations fail and displays a message that helps you to fix the issues. +## Debug your app -![acp-sdk-workflow-4](https://spryker.s3.eu-central-1.amazonaws.com/docs/aop/dev/developing-an-app/ACP-SDK-Workflow-black-4.jpg) +When you want to understand what is happening in the code you can [Debug your App](/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html) with XDebug and by adding `--cookie "XDEBUG_SESSION=PHPSTORM;path=/;" \` to the above cURL request. We provided complete examples for running cURL with XDebug. +Entry points for setting breakpoints are: +- `Spryker\Glue\App\Controller\AppConfigController` +- `\Spryker\Glue\App\Controller\AppDisconnectController` -## What's next -With the executed workflow, you can develop with the code as you’re used to developing Spryker applications. diff --git a/docs/acp/user/developing-an-app/setting-up-message-broker.md b/docs/acp/user/developing-an-app/setting-up-message-broker.md new file mode 100644 index 00000000000..768bc11fcd2 --- /dev/null +++ b/docs/acp/user/developing-an-app/setting-up-message-broker.md @@ -0,0 +1,75 @@ +--- +title: Setting Up the Message Broker +Descriptions: Learn how to develop an app +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +--- + +To enable the message broker functionality, you must install a special branch of the `spryker/message-broker` by running the following command: +```bash +docker/sdk cli composer require "spryker/message-broker:dev-beta/localstack-replacement as 1.8.0" +``` + +## Update the Code + +For testing the application, update or add the `MessageBrokerDependencyProvider` as shown in the code snippet below. + +```php + + */ + public function getMessageSenderPlugins(): array + { + return [ + new LocalSenderReceiverPlugin(), + ]; + } + + /** + * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MessageReceiverPluginInterface> + */ + public function getMessageReceiverPlugins(): array + { + return [ + new LocalSenderReceiverPlugin(), + ]; + } +} +``` + +## Update the configuration + +Open your `config/Shared/config_local.php` file and add the following snippet: + +```php +use Spryker\Shared\MessageBroker\MessageBrokerConstants; + +$config[MessageBrokerConstants::IS_ENABLED] = true; +$config[MessageBrokerConstants::LOCAL_EXCHANGE_FILE_PATH] = APPLICATION_ROOT_DIR . DIRECTORY_SEPARATOR . 'data' . DIRECTORY_SEPARATOR . 'data.json'; +$config[MessageBrokerConstants::MESSAGE_TO_CHANNEL_MAP] = [ + '*' => '*', +]; + +$config[MessageBrokerConstants::CHANNEL_TO_TRANSPORT_MAP] = [ + '*' => 'local', +]; +``` + +## Add the Worker Console + +The final step is to add the `\Spryker\Zed\MessageBroker\Communication\Plugin\Console\MessageBrokerWorkerConsole` console to the `\Pyz\Zed\Console\ConsoleDependencyProvider::getConsoleCommands()` method. With these changes, your Message Broker is now set up and ready to use. diff --git a/docs/acp/user/intro-to-acp/acp-overview.md b/docs/acp/user/intro-to-acp/acp-overview.md index 16f2723893a..748029df082 100644 --- a/docs/acp/user/intro-to-acp/acp-overview.md +++ b/docs/acp/user/intro-to-acp/acp-overview.md @@ -32,7 +32,7 @@ The ACP has the following advantages: ## Installing the ACP catalog -With the latest Spryker product release [202212.0](/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202212.0/release-notes-202212.0.html) the ACP catalog is integrated into the Back Office by default, but not registered with ACP yet. +With the Spryker product release [202212.0](/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202212.0/release-notes-202212.0.html) the ACP catalog is integrated into the Back Office by default, but not registered with ACP yet. You can access the ACP catalog only if you are a SCCOS customer and have additionally been enabled for ACP, which means that your SCCOS is properly set up and registered with the ACP. Check [ACP installation](/docs/acp/user/app-composition-platform-installation.html) for details on how to install and enable the ACP catalog for your version of SCCOS. From 5f0a21eab40679d684134ba32d9f5fe10939cae1 Mon Sep 17 00:00:00 2001 From: strelchenko Date: Mon, 11 Dec 2023 16:46:03 +0200 Subject: [PATCH 2/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path --- .../developing-an-app/code-snippets/configuration.md | 9 +++++++-- .../acp/user/developing-an-app/code-snippets/manifest.md | 4 ++++ .../user/developing-an-app/code-snippets/translation.md | 4 ++++ .../user/developing-an-app/debug-an-app-with-xdebug.md | 1 - docs/acp/user/developing-an-app/developing-an-app.md | 2 +- .../user/developing-an-app/setting-up-message-broker.md | 5 ----- 6 files changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/acp/user/developing-an-app/code-snippets/configuration.md b/docs/acp/user/developing-an-app/code-snippets/configuration.md index 3edc22d8867..1fa10b44ce4 100644 --- a/docs/acp/user/developing-an-app/code-snippets/configuration.md +++ b/docs/acp/user/developing-an-app/code-snippets/configuration.md @@ -6,8 +6,13 @@ redirect_from: - /docs/acp/user/developing-an-app.html --- -This is a `configuration.json` for the Hello World App. This is an example file where we assume the App needs a `clientId` and a `clientSecret` to be configured. On top of this, we can also enable/disable the App via the App Store Catalog. -This file has to be in config/app/configuration.json of your App. +This is a `configuration.json` for the Hello World App. +This is an example file where we assume the App needs a `clientId` and a `clientSecret` to be configured. On top of this, we can also enable/disable the App via the App Store Catalog. +This file has to be in `config/app/configuration.json` of your App. + +{% info_block infoBox "Info" %} +Additional info about the (configuration)[/docs/acp/user/app-configuration.html] +{% endinfo_block %} ```json { diff --git a/docs/acp/user/developing-an-app/code-snippets/manifest.md b/docs/acp/user/developing-an-app/code-snippets/manifest.md index 49180cd54a7..84258794803 100644 --- a/docs/acp/user/developing-an-app/code-snippets/manifest.md +++ b/docs/acp/user/developing-an-app/code-snippets/manifest.md @@ -10,6 +10,10 @@ This is an example manifest for the English version of the Hello World App. This file has to be placed in `config/app/manifest/en_US.json` in your App. +{% info_block infoBox "Info" %} +Additional info about the (configuration)[https://docs.spryker.com/docs/acp/user/app-manifest.html] +{% endinfo_block %} + ```json { "name": "Hello World App", diff --git a/docs/acp/user/developing-an-app/code-snippets/translation.md b/docs/acp/user/developing-an-app/code-snippets/translation.md index 86bb3570e86..370aa990526 100644 --- a/docs/acp/user/developing-an-app/code-snippets/translation.md +++ b/docs/acp/user/developing-an-app/code-snippets/translation.md @@ -10,6 +10,10 @@ This is a `translation.json` for the Hello World App. This file is used to trans This file has to be in `config/app/translation.json` of your App. +{% info_block infoBox "Info" %} +Additional info about the (configuration)[/docs/acp/user/app-configuration-translation.html] +{% endinfo_block %} + ```json { "configurations_fieldset_title": { diff --git a/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md b/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md index 104e647d504..7f5e3adc259 100644 --- a/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md +++ b/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md @@ -18,7 +18,6 @@ To start a testing container with XDebug enabled (disabled in the default contai docker/sdk testing -x ``` - ### Configuring PHPStorm for XDebug 1. Open PHPStorm and navigate to Preferences → PHP → Servers. diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md index bb4fd579303..f7fd31a2cf5 100644 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -231,7 +231,7 @@ Start implementing the business logic by Implementing a Synchronous API and/or I ## Debug your app -When you want to understand what is happening in the code you can [Debug your App](/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html) with XDebug and by adding `--cookie "XDEBUG_SESSION=PHPSTORM;path=/;" \` to the above cURL request. We provided complete examples for running cURL with XDebug. +When you want to understand what is happening in the code you can [Debug your App](/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html) with XDebug and by adding `--cookie "XDEBUG_SESSION=PHPSTORM;path=/;" \` to the above cURL request. Entry points for setting breakpoints are: - `Spryker\Glue\App\Controller\AppConfigController` - `\Spryker\Glue\App\Controller\AppDisconnectController` diff --git a/docs/acp/user/developing-an-app/setting-up-message-broker.md b/docs/acp/user/developing-an-app/setting-up-message-broker.md index 768bc11fcd2..8ef61adcb3b 100644 --- a/docs/acp/user/developing-an-app/setting-up-message-broker.md +++ b/docs/acp/user/developing-an-app/setting-up-message-broker.md @@ -18,11 +18,6 @@ For testing the application, update or add the `MessageBrokerDependencyProvider` ```php Date: Tue, 12 Dec 2023 10:23:59 +0200 Subject: [PATCH 3/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path / sidebar fix --- _data/sidebars/acp_user_sidebar.yml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index 9cdb8f19581..82c6f6de193 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -15,8 +15,16 @@ entries: - title: Developing an app url: /docs/acp/user/developing-an-app/developing-an-app.html nested: - - title: Create and app with AppKernel - url: /docs/acp/user/developing-an-app/create-an-app-with-appkernel.html + - title: Configuration code snippet + url: /docs/acp/user/developing-an-app/code-snippets/configuration.html + - title: Manifest code snippet + url: /docs/acp/user/developing-an-app/code-snippets/manifest.html + - title: Translation code snippet + url: /docs/acp/user/developing-an-app/code-snippets/translation.html + - title: Setting up message brocker + url: /docs/acp/user/developing-an-app/setting-up-message-broker.html + - title: Debug an app with xdebug + url: /docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html - title: App manifest url: /docs/acp/user/app-manifest.html - title: App configuration From 17969646c3ab7cc0dba6e689e67097e016e416dd Mon Sep 17 00:00:00 2001 From: strelchenko Date: Thu, 14 Dec 2023 09:42:51 +0200 Subject: [PATCH 4/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path --- docs/acp/user/developing-an-app/developing-an-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md index f7fd31a2cf5..6b7b9262923 100644 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -35,7 +35,7 @@ You need to have a clear understanding of what your app API will provide to othe ### Schema-first -Before you start with the development, you should design your API schema files. Depending on your requirements, you can have an OpenAPI or an [Async API](#async-api) schema file. In this step, you define the [Sync API](#sync-api) endpoints your app will provide to others, the messages you will emit or consume, and the data you expect to work with. +Before you start with the development, you should design your API schema files. Depending on your requirements, you can have an OpenAPI or an Async API schema file. In this step, you define the Sync API endpoints your app will provide to others, the messages you will emit or consume, and the data you expect to work with. {% info_block infoBox "Info" %} For more information about Async API schema design, see [Designing your APIs with Async API](https://www.asyncapi.com/blog/designing_your_apis_with_asyncapi_part_1). From 381c327422cfbf60c97a600dd71c4e92ea61309d Mon Sep 17 00:00:00 2001 From: strelchenko Date: Thu, 14 Dec 2023 17:47:31 +0200 Subject: [PATCH 5/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path --- docs/acp/user/developing-an-app/developing-an-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md index 6b7b9262923..b3a17d738b4 100644 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -124,7 +124,7 @@ To be able to use your Mini Framework as an App you need to add a new Spryker mo docker/sdk cli composer require spryker/app-kernel spryker/message-broker-aws spryker/propel-encryption-behavior ``` This `spryker/app-kernel` module will make the Mini-Framework an App. It provides SyncAPI schema and code for configuration and disconnection as well as an AsyncAPI schema and code for the AppConfigure and AppDisconnect messages. -The `spryker/message-broker-aws` module installs the needed plugins which will be used to send and receive messages. In addition to installing the modules you need to configure them. +The `spryker/message-broker-aws` module installs the needed plugins which will be used to send and receive messages. In addition to installing the modules you need to configure them. The configuration [example](https://github.com/spryker-projects/mini-framework/blob/examples/acp/hello-world/my-app-final/config/Shared/config_default.php#L28). ## Setup the Message Broker From 216e73592efc0ee9085d28b70e762e131b6ac33c Mon Sep 17 00:00:00 2001 From: strelchenko Date: Thu, 14 Dec 2023 18:14:57 +0200 Subject: [PATCH 6/9] SDK-5414: As a PBC developer I want to have a clear single onboarding path --- docs/acp/user/developing-an-app/developing-an-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md index b3a17d738b4..3181a025a96 100644 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ b/docs/acp/user/developing-an-app/developing-an-app.md @@ -182,7 +182,7 @@ docker/sdk cli console transfer:generate ## Update the Database -Transfer objects are used in many place and since we installed some modules we also need to run the console command to generate the transfers. +Generate the database entities and update the database. ```bash docker/sdk cli console propel:install From 9f81168a5e3e8c570e3e54abf87b12967d787289 Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Thu, 14 Dec 2023 18:06:27 +0100 Subject: [PATCH 7/9] adjusting the files --- _data/sidebars/acp_user_sidebar.yml | 16 +- .../acp/user/app-configuration-translation.md | 2 +- .../code-snippets/configuration.md | 12 +- .../code-snippets/manifest.md | 11 +- .../code-snippets/translation.md | 10 +- .../debug-an-app-with-xdebug.md | 2 +- .../acp/user/develop-an-app/develop-an-app.md | 245 ++++++++++++++++++ .../set-up-the-message-broker.md} | 4 +- .../developing-an-app/developing-an-app.md | 238 ----------------- .../user/intro-to-spryker/docs-updates.md | 2 +- 10 files changed, 271 insertions(+), 271 deletions(-) rename docs/acp/user/{developing-an-app => develop-an-app}/code-snippets/configuration.md (61%) rename docs/acp/user/{developing-an-app => develop-an-app}/code-snippets/manifest.md (69%) rename docs/acp/user/{developing-an-app => develop-an-app}/code-snippets/translation.md (61%) rename docs/acp/user/{developing-an-app => develop-an-app}/debug-an-app-with-xdebug.md (97%) create mode 100644 docs/acp/user/develop-an-app/develop-an-app.md rename docs/acp/user/{developing-an-app/setting-up-message-broker.md => develop-an-app/set-up-the-message-broker.md} (96%) delete mode 100644 docs/acp/user/developing-an-app/developing-an-app.md diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index 82c6f6de193..4df47c61b6c 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -12,19 +12,19 @@ entries: url: /docs/acp/user/intro-to-acp/aop-security-assessment.html - title: Install ACP catalog url: /docs/acp/user/app-composition-platform-installation.html - - title: Developing an app - url: /docs/acp/user/developing-an-app/developing-an-app.html + - title: Develop an app + url: /docs/acp/user/develop-an-app/develop-an-app.html nested: - title: Configuration code snippet - url: /docs/acp/user/developing-an-app/code-snippets/configuration.html + url: /docs/acp/user/develop-an-app/code-snippets/configuration.html - title: Manifest code snippet - url: /docs/acp/user/developing-an-app/code-snippets/manifest.html + url: /docs/acp/user/develop-an-app/code-snippets/manifest.html - title: Translation code snippet - url: /docs/acp/user/developing-an-app/code-snippets/translation.html - - title: Setting up message brocker - url: /docs/acp/user/developing-an-app/setting-up-message-broker.html + url: /docs/acp/user/develop-an-app/code-snippets/translation.html + - title: Set up the message broker + url: /docs/acp/user/develop-an-app/set-up-the-message-broker.html - title: Debug an app with xdebug - url: /docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html + url: /docs/acp/user/develop-an-app/debug-an-app-with-xdebug.html - title: App manifest url: /docs/acp/user/app-manifest.html - title: App configuration diff --git a/docs/acp/user/app-configuration-translation.md b/docs/acp/user/app-configuration-translation.md index 519966c033d..4a2024dcba0 100644 --- a/docs/acp/user/app-configuration-translation.md +++ b/docs/acp/user/app-configuration-translation.md @@ -6,7 +6,7 @@ related: - title: App configuration link: docs/acp/user/app-configuration.html - title: Developing an app - link: docs/acp/user/developing-an-app.html + link: docs/acp/user/develop-an-app.html - title: App manifest link: docs/acp/user/app-manifest.html --- diff --git a/docs/acp/user/developing-an-app/code-snippets/configuration.md b/docs/acp/user/develop-an-app/code-snippets/configuration.md similarity index 61% rename from docs/acp/user/developing-an-app/code-snippets/configuration.md rename to docs/acp/user/develop-an-app/code-snippets/configuration.md index 1fa10b44ce4..89eeff4a4fb 100644 --- a/docs/acp/user/developing-an-app/code-snippets/configuration.md +++ b/docs/acp/user/develop-an-app/code-snippets/configuration.md @@ -3,16 +3,14 @@ title: Configuration Json Descriptions: Configuration Json code snippet template: howto-guide-template redirect_from: -- /docs/acp/user/developing-an-app.html +- /docs/acp/user/develop-an-app.html --- +To display the app you [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html) in the App Store Catalog, the app needs to have the `configuration.json` file. This file contains all necessary form fields for inputs required by users of your app. Add this file to `config/app/configuration.json` in your app. -This is a `configuration.json` for the Hello World App. -This is an example file where we assume the App needs a `clientId` and a `clientSecret` to be configured. On top of this, we can also enable/disable the App via the App Store Catalog. -This file has to be in `config/app/configuration.json` of your App. +For more information about the app configuration, see [App configuration](/docs/acp/user/app-configuration.html). + +Here is the example `configuration.json` file for the Hello World app. In this example, we assume the app needs a `clientId` and a `clientSecret` configured. Additionally, there should be an option to enable and disable the app via the App Store Catalog. -{% info_block infoBox "Info" %} -Additional info about the (configuration)[/docs/acp/user/app-configuration.html] -{% endinfo_block %} ```json { diff --git a/docs/acp/user/developing-an-app/code-snippets/manifest.md b/docs/acp/user/develop-an-app/code-snippets/manifest.md similarity index 69% rename from docs/acp/user/developing-an-app/code-snippets/manifest.md rename to docs/acp/user/develop-an-app/code-snippets/manifest.md index 84258794803..8e6e29cb56e 100644 --- a/docs/acp/user/developing-an-app/code-snippets/manifest.md +++ b/docs/acp/user/develop-an-app/code-snippets/manifest.md @@ -3,16 +3,13 @@ title: Manifest Json Descriptions: Manifest Json code snippet template: howto-guide-template redirect_from: -- /docs/acp/user/developing-an-app.html +- /docs/acp/user/develop-an-app.html --- +To display the app you [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html) in the App Store Catalog,, the app needs to have the manifest file. Add this file has to `config/app/manifest/en_US.json` in your App. -This is an example manifest for the English version of the Hello World App. +For more information about configuration of the manifest file, see [App manifest](https://docs.spryker.com/docs/acp/user/app-manifest.html). -This file has to be placed in `config/app/manifest/en_US.json` in your App. - -{% info_block infoBox "Info" %} -Additional info about the (configuration)[https://docs.spryker.com/docs/acp/user/app-manifest.html] -{% endinfo_block %} +Here is the example manifest for the English version of the Hello World app: ```json { diff --git a/docs/acp/user/developing-an-app/code-snippets/translation.md b/docs/acp/user/develop-an-app/code-snippets/translation.md similarity index 61% rename from docs/acp/user/developing-an-app/code-snippets/translation.md rename to docs/acp/user/develop-an-app/code-snippets/translation.md index 370aa990526..d90e09c33b8 100644 --- a/docs/acp/user/developing-an-app/code-snippets/translation.md +++ b/docs/acp/user/develop-an-app/code-snippets/translation.md @@ -3,16 +3,14 @@ title: Translation Json Descriptions: Translation Json code snippet template: howto-guide-template redirect_from: -- /docs/acp/user/developing-an-app.html +- /docs/acp/user/develop-an-app.html --- -This is a `translation.json` for the Hello World App. This file is used to translate the form fields which are defined in the `configuration.json`. +The `translation.json` file contains translations of the form files which are defined in the `configuration.json` file of your app [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html). Add this file to `config/app/translation.json`in your app. -This file has to be in `config/app/translation.json` of your App. +For more information about the app configuration translation, see [App configuration translation](/docs/acp/user/app-configuration-translation.html). -{% info_block infoBox "Info" %} -Additional info about the (configuration)[/docs/acp/user/app-configuration-translation.html] -{% endinfo_block %} +Here is the example `translation.json` file for the Hello World app. ```json { diff --git a/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md b/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md similarity index 97% rename from docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md rename to docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md index 7f5e3adc259..134d6e5e3fc 100644 --- a/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.md +++ b/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md @@ -3,7 +3,7 @@ title: Debugging Your App with Xdebug Descriptions: Learn how to use Xdebug template: howto-guide-template redirect_from: -- /docs/acp/user/developing-an-app.html +- /docs/acp/user/develop-an-app.html --- ## Introduction diff --git a/docs/acp/user/develop-an-app/develop-an-app.md b/docs/acp/user/develop-an-app/develop-an-app.md new file mode 100644 index 00000000000..2054dad7aed --- /dev/null +++ b/docs/acp/user/develop-an-app/develop-an-app.md @@ -0,0 +1,245 @@ +--- +title: Developing an app with Spryker Mini-Framework +Descriptions: Learn the step-by-step process of developing an app using Spryker's Mini-Framework +template: howto-guide-template +redirect_from: +- /docs/acp/user/developing-an-app.html +- /docs/acp/user/developing-an-app/developing-an-app.html +--- + +This document will walk you through the process of developing an app using Spryker's Mini-Framework. Follow the steps below to set up and start your app development. + +## Prerequisites + +Before you begin, ensure that you have the following prerequisites in place: + +- Completed the [thought process](#thought-process) for your app. +- An empty GitHub repository. +- A local project directory for your app (e.g., `/www/my-app`). +- [DockerSDK](https://github.com/spryker/docker-sdk) installed globally. + +Make sure you have the Spryker Docker SDK, Git, and an empty repository for your app code. + +{% info_block infoBox "Info" %} +[Download the]((https://github.com/spryker-projects/mini-framework)) completed example from the Mini-Framework. +{% endinfo_block %} + +## Thought process +First, think about what your app should be capable of: what features it will bring and what data will be exchanged, not only to you but also to those interested in your app functionality. For example, what messages could be of interest to others, and what API endpoints you should provide. + +### API-first +It's strongly recommended that apps follow the API-first approach. +API-first means that your app is centered on the API. It should be possible to perform every action via the scripting language, and every piece of functionality should be available for other systems to leverage. For more information on the API-first approach, see [this blog post](https://www.algolia.com/blog/product/the-5-principles-of-api-first-development-and-what-does-api-first-even-mean/). +You need to have a clear understanding of what your app API will provide to others and always keep that in mind when designing your app. + +### Schema-first + +Before you start with the development, you should design your API schema files. Depending on your requirements, you can have an OpenAPI or an Async API schema file. In this step, you define the Sync API endpoints your app will provide to others, the messages you will emit or consume, and the data you expect to work with. + +{% info_block infoBox "Info" %} +For more information about Async API schema design, see [Designing your APIs with Async API](https://www.asyncapi.com/blog/designing_your_apis_with_asyncapi_part_1). + +For more information about OpenAPI schema design, see [Best practices in API design](https://swagger.io/resources/articles/best-practices-in-api-design/). +{% endinfo_block %} + +You can use the following tools to design your APIs: +- [Async API Studio](https://studio.asyncapi.com/) +- [Swagger Editor](https://editor.swagger.io/) + +## Create an app + +To create an app, execute the following commands: + +```bash +mkdir my-app +cd my-app +git clone https://github.com/spryker-projects/mini-framework.git . --depth 1 && rm -rf .git && git init +git add --all +git commit -m "first commit" +``` + +After running these commands, you will have a new local repository that needs to be linked with your remote one. + +If not done yet, create a new remote repository by opening your [Github account](https://github.com/newConnect). After you created a new repository, GitHub shows you instructions on how to continue. You should follow the list below as you don’t need some of the first steps proposed by GitHub as we’ve already initialized Git and we already have the `README.md` file from the cloned repository. + +```bash +git branch -M main +git remote add origin git@github.com:/.git +git push -u origin main +``` +{% info_block infoBox "Info" %} + +You can also execute this step later. + +{% endinfo_block %} + +Now, you have done the groundwork that enables you to develop an App. You created a new repository that contains the boilerplate code for almost any App you’d like to build. + +## Start the local development environment + +The Mini-Framework already comes with the predefined Docker configuration. Change the `deploy.dev.yml` by replacing `glue-backend.de.spryker.local` with `my-app.de.spryker.local`. After that, run the command provided in the next section at the root of your new repository. + +### Boot and up your environment + +Execute the following command to boot your application and start it: + +```bash +docker/sdk boot deploy.dev.yml +docker/sdk up +``` + +After creating the development environment, you have several ways of using the app. The easiest one is to run the test suite as follows: + +```bash +docker/sdk testing codecept run +``` + +You will now see that your app boilerplate code is up and running. + +## Add the app manifest files + +Before your app can be listed in the App Store Catalog, you need to add the following files. + +### Manifest + +The manifest file is the most important one for the App. It contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/develop-an-app/code-snippets/manifest.html) and update it to your needs. Add the manifest file to `config/app/manifest/en_US.json` of your app. + +Manifest files must have the local name as the filename, for example, `en_US.json`, and should be placed inside the `config/app/manifest` directory. + +### Configuration + +The configuration file contains all necessary form fields for inputs required by the user of your app, to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/develop-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your App. + +### Translation + +The translation file contains all translations for the form fields you’ve previously defined. You can use the Hello World [example translation file](/docs/acp/user/develop-an-app/code-snippets/translation.html) and update it to your needs. Add this file to `config/app/translation.json` of your App. + +## Add the registry (code) + +Every app requires default endpoints for the App Registry Service. This service acts as an intermediary between the App Store Catalog and all apps. Each app is registered in the App Registry Service and requires the following endpoints for communication: + + - Configure + - Disconnect + +To be able to use your Mini Framework as an app, add a new Spryker module: + +```bash +docker/sdk cli composer require spryker/app-kernel spryker/message-broker-aws spryker/propel-encryption-behavior +``` + +The `spryker/app-kernel` module transforms the Mini-Framework into an app. It provides SyncAPI schema and code for configuration and disconnection, as well as an AsyncAPI schema and code for the AppConfigure and AppDisconnect messages. +The `spryker/message-broker-aws` module installs the necessary plugins for sending and receiving messages. +After installing the modules, you need to configure them. See the [configuration example](https://github.com/spryker-projects/mini-framework/blob/examples/acp/hello-world/my-app-final/config/Shared/config_default.php#L28). + +## Set up the message broker + +Install and configure the message broker as described in [Set up the message broker](/docs/acp/user/develop-an-app/set-up-the-message-broker.html). + +## Config + +To be identifiable in the App Eco System, every app needs an app identifier. To provide the identifier, add the following configuration to `config/Shared/config_default.php`: + +```php +use Spryker\Shared\AppKernel\AppKernelConstants; + +$config[AppKernelConstants::APP_IDENTIFIER] = getenv('APP_IDENTIFIER') ?: 'hello-world'; +``` + +## Plugins + +Add some plugins to your app to enable certain functionality. + +### AppRouteProviderPlugin + +Add `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` to the `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()` method. In case the method doesn’t exist, add the complete method. + +```php + + */ + protected function getRouteProviderPlugins(): array + { + return [ + new AppRouteProviderPlugin(), + ]; + } +} +``` + +This enables the two required endpoints for the App Catalog Communication. + +## Build the transfer objects + +Transfer objects are used in many places. Since you installed some modules, you also need to generate the transfers. To generate the transfers, run the following command: + +```bash +docker/sdk cli console transfer:generate +``` + +## Update the database + +Generate the database entities and update the database: + +```bash +docker/sdk cli console propel:install +``` + +## Test the endpoints + +You can now test the `configure` request with the following snippets. Run the cURL snippets from your host machine. + +### Test the /private/configure endpoint + +```bash +curl --location --request POST 'http://my-app.de.spryker.local/private/configure' \ +--header 'Content-Type: application/vnd.api+json' \ +--header 'Accept: application/vnd.api+json' \ +--header 'Accept-Language: en-US, en;q=0.9,*;q=0.5' \ +--header 'X-Tenant-Identifier: dev-US' \ +--data-raw '{ + "data": { + "type": "configuration", + "attributes": { + "configuration": "{\"clientId\":\"clientId\",\"clientSecret\":\"clientSecret\",\"securityUri\":\"securityUri\",\"transactionCallsUri\":\"transactionCallsUri\",\"isActive\": false,\"isInvoicingEnabled\": false}" + } + } +}' +``` + +Now, check if your database contains the newly created configuration in the `spy_app_config` table. + +### Test the /private/disconnect endpoint + +```bash +curl --location --request POST 'http://my-app.de.spryker.local/private/disconnect' \ +--header 'Content-Type: application/vnd.api+json' \ +--header 'Accept: application/vnd.api+json' \ +--header 'Accept-Language: de-DE, en;q=0.9,*;q=0.5' \ +--header 'X-Tenant-Identifier: dev-US' \ +--data-raw '' +``` + +Now, check if the previously created configuration in the spy_app_config table has been removed from your database. + +## Implement business logic + +Your app is now ready to use, although it doesn't contain any business logic yet. +Start implementing the business logic by implementing a synchronous or asynchronous API. + +## Debug your app + +If you want to understand what is happening in the code, you can [debug your app](/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.html) with XDebug and by adding `--cookie "XDEBUG_SESSION=PHPSTORM;path=/;" \` to the above cURL request. + +Entry points for setting breakpoints are the following: +- `Spryker\Glue\App\Controller\AppConfigController` +- `\Spryker\Glue\App\Controller\AppDisconnectController` + diff --git a/docs/acp/user/developing-an-app/setting-up-message-broker.md b/docs/acp/user/develop-an-app/set-up-the-message-broker.md similarity index 96% rename from docs/acp/user/developing-an-app/setting-up-message-broker.md rename to docs/acp/user/develop-an-app/set-up-the-message-broker.md index 8ef61adcb3b..ecc6f624e8a 100644 --- a/docs/acp/user/developing-an-app/setting-up-message-broker.md +++ b/docs/acp/user/develop-an-app/set-up-the-message-broker.md @@ -1,9 +1,9 @@ --- -title: Setting Up the Message Broker +title: Set up the message broker Descriptions: Learn how to develop an app template: howto-guide-template redirect_from: -- /docs/acp/user/developing-an-app.html +- /docs/acp/user/develop-an-app.html --- To enable the message broker functionality, you must install a special branch of the `spryker/message-broker` by running the following command: diff --git a/docs/acp/user/developing-an-app/developing-an-app.md b/docs/acp/user/developing-an-app/developing-an-app.md deleted file mode 100644 index 3181a025a96..00000000000 --- a/docs/acp/user/developing-an-app/developing-an-app.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Developing an App -Descriptions: Learn the step-by-step process of developing an app using Spryker's Mini-Framework -template: howto-guide-template -redirect_from: -- /docs/acp/user/developing-an-app.html ---- - -# Developing an App with Spryker Mini-Framework - -This guide will walk you through the process of developing an app using Spryker's Mini-Framework. Follow the steps below to set up and start your app development. - -## Prerequisites - -Before you begin, ensure that you have the following prerequisites in place: - -- Completed the [thought process](#thought-process) for your app. -- An empty GitHub repository. -- A local project directory for your app (e.g., `/www/my-app`). -- [DockerSDK](https://github.com/spryker/docker-sdk) installed globally. - -Make sure you have Spryker Docker SDK, Git, and an empty repository for your app code. - -{% info_block infoBox "Info" %} -Download the completed example from the Mini-Framework [here](https://github.com/spryker-projects/mini-framework). -{% endinfo_block %} - -## Thought process -First, think about what your app should be capable of: what features it will bring, and what data will be exchanged, not only to you but also to those interested in your app functionality. For example, what messages could be of interest to others, and what API endpoints you should provide. - -### API-first -It's strongly recommended that apps follow the API-first approach. -API-first means that your app is centered on the API. It should be possible to perform every action via the scripting language, and every piece of functionality should be available for other systems to leverage. For more information on the API-first approach, see [this blog post](https://www.algolia.com/blog/product/the-5-principles-of-api-first-development-and-what-does-api-first-even-mean/). -You need to have a clear understanding of what your app API will provide to others, and always keep that in mind when designing your app. - -### Schema-first - -Before you start with the development, you should design your API schema files. Depending on your requirements, you can have an OpenAPI or an Async API schema file. In this step, you define the Sync API endpoints your app will provide to others, the messages you will emit or consume, and the data you expect to work with. - -{% info_block infoBox "Info" %} -For more information about Async API schema design, see [Designing your APIs with Async API](https://www.asyncapi.com/blog/designing_your_apis_with_asyncapi_part_1). - -For more information about OpenAPI schema design, see [Best practices in API design](https://swagger.io/resources/articles/best-practices-in-api-design/). -{% endinfo_block %} - -You can use the following tools to design your APIs: -- [Async API Studio](https://studio.asyncapi.com/) -- [Swagger Editor](https://editor.swagger.io/) - -## Create an app - -Creating an app is straightforward. Execute the following commands: -```bash -mkdir my-app -cd my-app -git clone https://github.com/spryker-projects/mini-framework.git . --depth 1 && rm -rf .git && git init -git add --all -git commit -m "first commit" -``` - -After these steps, you will have a new local repository that needs to be linked with your remote one. - -If not done yet, create a new remote repository by opening your [Github account](https://github.com/newConnect). After you created a new repository, GitHub shows you instructions on how to continue. You should follow the list below as you don’t need some of the first steps proposed by GitHub as we’ve already initialized git and we already have a `README.md` from the cloned repository. - -{% info_block infoBox "Info" %} -This step can also be done later -{% endinfo_block %} - -```bash -git branch -M main -git remote add origin git@github.com:/.git -git push -u origin main -``` - -Now you have done the groundwork that enables you to develop an App. You created a new repository that contains the boilerplate code for almost any App you’d like to build. - -## Start local development environment - -The Mini-Framework already comes with a predefined Docker configuration. Change the `deploy.dev.yml` and replace `glue-backend.de.spryker.local` with `my-app.de.spryker.local` and then run the following command in the root of your new repository. - -### Boot and Up your environment - -With this command, you will boot your application and start it - -```bash -docker/sdk boot deploy.dev.yml -docker/sdk up -``` - -After creating the development environment for you, you have several ways of using the App. The easiest one is to run the test suite. - -```bash -docker/sdk testing codecept run -``` - -You will see now that your App boilerplate code is running. - -## Adding App manifest files - -Before your App can be listed in the App Store Catalog you need to add the following files. - -### Manifest - -The manifest file is the most important one for the App and contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/developing-an-app/code-snippets/manifest.html) and update it to your needs. Add this file to `config/app/manifest/en_US.json` of your App. - -Manifest files have to have the local name as file name e.g. `en_US.json` and the file has to be placed inside the `config/app/manifest` directory. - -### Configuration - -This file contains all necessary form fields for inputs required by the user of your App to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/developing-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your App. - -### Translation - -This file contains all translations for the form fields you’ve previously defined. You can use the Hello World example translation file and update it to your needs. Add this file to `config/app/translation.json` of your App. - -## Adding the Registry code - -Every App needs some default endpoints for the App Registry Service. This service is in between of the App Store Catalog and all Apps. Each App will be registered in the App Registry Service and to be able to configure your App needs the following endpoints for communication: - - Configure - - Disconnect - -To be able to use your Mini Framework as an App you need to add a new Spryker module: -```bash -docker/sdk cli composer require spryker/app-kernel spryker/message-broker-aws spryker/propel-encryption-behavior -``` -This `spryker/app-kernel` module will make the Mini-Framework an App. It provides SyncAPI schema and code for configuration and disconnection as well as an AsyncAPI schema and code for the AppConfigure and AppDisconnect messages. -The `spryker/message-broker-aws` module installs the needed plugins which will be used to send and receive messages. In addition to installing the modules you need to configure them. The configuration [example](https://github.com/spryker-projects/mini-framework/blob/examples/acp/hello-world/my-app-final/config/Shared/config_default.php#L28). - -## Setup the Message Broker - -The MessageBroker needs to be installed and configured. Follow the description on this page [Setup the MessageBroker](/docs/acp/user/developing-an-app/setting-up-message-broker.html). - -## Config - -Every App needs an app identifier to be identifyable in the App Eco System. Add the following configuration to your `config/Shared/config_default.php` - -```php -use Spryker\Shared\AppKernel\AppKernelConstants; - -$config[AppKernelConstants::APP_IDENTIFIER] = getenv('APP_IDENTIFIER') ?: 'hello-world'; -``` - -## Plugins - -You need to add some Plugins to your App to enable certain functionality. - -### AppRouteProviderPlugin - -Add the `\Spryker\Glue\App\Plugin\RouteProvider\AppRouteProviderPlugin` to the `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins()` method. In case the method doesn’t exist add the complete method. - -```php - - */ - protected function getRouteProviderPlugins(): array - { - return [ - new AppRouteProviderPlugin(), - ]; - } -} -``` - -This enables the two required endpoints for the App Catalog Communication. - -## Building the Transfer Objects - -Transfer objects are used in many place and since we installed some modules we also need to run the console command to generate the transfers. - -```bash -docker/sdk cli console transfer:generate -``` - -## Update the Database - -Generate the database entities and update the database. - -```bash -docker/sdk cli console propel:install -``` - -## Testing the endpoints - -You can now test the configure request with the following snippets. Run the cURL snippets from your host machine. - -### Testing the /private/configure endpoint - -```bash -curl --location --request POST 'http://my-app.de.spryker.local/private/configure' \ ---header 'Content-Type: application/vnd.api+json' \ ---header 'Accept: application/vnd.api+json' \ ---header 'Accept-Language: en-US, en;q=0.9,*;q=0.5' \ ---header 'X-Tenant-Identifier: dev-US' \ ---data-raw '{ - "data": { - "type": "configuration", - "attributes": { - "configuration": "{\"clientId\":\"clientId\",\"clientSecret\":\"clientSecret\",\"securityUri\":\"securityUri\",\"transactionCallsUri\":\"transactionCallsUri\",\"isActive\": false,\"isInvoicingEnabled\": false}" - } - } -}' -``` - -You can check now your database if it contains the newly created configuration in the `spy_app_config` table. - -### Testing the /private/disconnect endpoint - -```bash -curl --location --request POST 'http://my-app.de.spryker.local/private/disconnect' \ ---header 'Content-Type: application/vnd.api+json' \ ---header 'Accept: application/vnd.api+json' \ ---header 'Accept-Language: de-DE, en;q=0.9,*;q=0.5' \ ---header 'X-Tenant-Identifier: dev-US' \ ---data-raw '' -``` - -You can check now your database if previously created configuration in the spy_app_config table is removed. - -## Summary -Your app is now ready to be used, although it doesn't contain any business logic yet. -Start implementing the business logic by Implementing a Synchronous API and/or Implementing an Asynchronous API. - -## Debug your app - -When you want to understand what is happening in the code you can [Debug your App](/docs/acp/user/developing-an-app/debug-an-app-with-xdebug.html) with XDebug and by adding `--cookie "XDEBUG_SESSION=PHPSTORM;path=/;" \` to the above cURL request. -Entry points for setting breakpoints are: -- `Spryker\Glue\App\Controller\AppConfigController` -- `\Spryker\Glue\App\Controller\AppDisconnectController` - diff --git a/docs/scos/user/intro-to-spryker/docs-updates.md b/docs/scos/user/intro-to-spryker/docs-updates.md index aaf447cfd6d..b0bd955c7d2 100644 --- a/docs/scos/user/intro-to-spryker/docs-updates.md +++ b/docs/scos/user/intro-to-spryker/docs-updates.md @@ -30,7 +30,7 @@ In October 2023, we have added and updated the following pages: - [Use API Key authorization](/docs/scos/dev/glue-api-guides/202307.0/use-api-key-authorization.html): Learn how to use the API Key authorization mechanism that lets users authenticate themselves with their API Key generated from the Back Office. - [Decoupled Glue infrastructure: Integrate the API Key authorization](/docs/scos/dev/migration-concepts/migrate-to-decoupled-glue-infrastructure/decoupled-glue-infrastructure-integrate-api-key-authorization.html): Learn how to integrate the API Key authorization to Backend API applications. - [Test the asynchronous API](/docs/scos/dev/guidelines/testing-guidelines/executing-tests/test-the-asynchronous-api.html): Learn how to set up and run AsyncAPI tests. -- [Create an app with AppKernel](/docs/acp/user/developing-an-app/create-an-app-with-appkernel.html): Learn how to use AppKernel with Spryker’s Mini Framework to develop an app. +- [Create an app with AppKernel](/docs/acp/user/develop-an-app/create-an-app-with-appkernel.html): Learn how to use AppKernel with Spryker’s Mini Framework to develop an app. - [Install the Service Points Cart + Checkout feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-service-points-cart-checkout-feature.html). - [Install the Service Points Cart feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-service-points-cart-feature.html). - [Install the Shipment Product Offer + Service Points Availability feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-shipment-product-offer-service-points-availability-feature.html). From f079161af336185f9785bce1282e01a2f590bff1 Mon Sep 17 00:00:00 2001 From: lenadoc Date: Thu, 14 Dec 2023 18:49:17 +0100 Subject: [PATCH 8/9] Adjusting the files --- .../code-snippets/configuration.md | 2 -- .../develop-an-app/code-snippets/manifest.md | 4 +-- .../code-snippets/translation.md | 4 +-- .../debug-an-app-with-xdebug.md | 28 +++++++++---------- .../acp/user/develop-an-app/develop-an-app.md | 15 +++++----- .../set-up-the-message-broker.md | 24 +++++++++------- 6 files changed, 37 insertions(+), 40 deletions(-) diff --git a/docs/acp/user/develop-an-app/code-snippets/configuration.md b/docs/acp/user/develop-an-app/code-snippets/configuration.md index 89eeff4a4fb..ff24a2648dd 100644 --- a/docs/acp/user/develop-an-app/code-snippets/configuration.md +++ b/docs/acp/user/develop-an-app/code-snippets/configuration.md @@ -2,8 +2,6 @@ title: Configuration Json Descriptions: Configuration Json code snippet template: howto-guide-template -redirect_from: -- /docs/acp/user/develop-an-app.html --- To display the app you [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html) in the App Store Catalog, the app needs to have the `configuration.json` file. This file contains all necessary form fields for inputs required by users of your app. Add this file to `config/app/configuration.json` in your app. diff --git a/docs/acp/user/develop-an-app/code-snippets/manifest.md b/docs/acp/user/develop-an-app/code-snippets/manifest.md index 8e6e29cb56e..2bfb602e13d 100644 --- a/docs/acp/user/develop-an-app/code-snippets/manifest.md +++ b/docs/acp/user/develop-an-app/code-snippets/manifest.md @@ -2,10 +2,8 @@ title: Manifest Json Descriptions: Manifest Json code snippet template: howto-guide-template -redirect_from: -- /docs/acp/user/develop-an-app.html --- -To display the app you [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html) in the App Store Catalog,, the app needs to have the manifest file. Add this file has to `config/app/manifest/en_US.json` in your App. +To display the app you [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html) in the App Store Catalog,, the app needs to have the manifest file. Add this file to `config/app/manifest/en_US.json` in your App. For more information about configuration of the manifest file, see [App manifest](https://docs.spryker.com/docs/acp/user/app-manifest.html). diff --git a/docs/acp/user/develop-an-app/code-snippets/translation.md b/docs/acp/user/develop-an-app/code-snippets/translation.md index d90e09c33b8..3949155d591 100644 --- a/docs/acp/user/develop-an-app/code-snippets/translation.md +++ b/docs/acp/user/develop-an-app/code-snippets/translation.md @@ -2,8 +2,6 @@ title: Translation Json Descriptions: Translation Json code snippet template: howto-guide-template -redirect_from: -- /docs/acp/user/develop-an-app.html --- The `translation.json` file contains translations of the form files which are defined in the `configuration.json` file of your app [developed with Spryker Mini-Framework](/docs/acp/user/develop-an-app/develop-an-app.html). Add this file to `config/app/translation.json`in your app. @@ -43,4 +41,4 @@ Here is the example `translation.json` file for the Hello World app. "de_DE": "Aktivieren" } } -``` +``` \ No newline at end of file diff --git a/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md b/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md index 134d6e5e3fc..e3c1351907f 100644 --- a/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md +++ b/docs/acp/user/develop-an-app/debug-an-app-with-xdebug.md @@ -1,33 +1,33 @@ --- -title: Debugging Your App with Xdebug -Descriptions: Learn how to use Xdebug +title: Debug an app with Xdebug +Descriptions: Learn how to use Xdebug for your app template: howto-guide-template -redirect_from: -- /docs/acp/user/develop-an-app.html --- -## Introduction +This document describes how to set up and use Xdebug to debug your app. -Debugging your application becomes a seamless process with the provided DockerSDK, which comes equipped with a configuration to effortlessly run your app with Xdebug. This guide will walk you through the steps to set up and use Xdebug for debugging purposes. +Keep in mind that the steps described here may vary slightly depending on your specific development environment; however, they should still assist you in setting up XDebug for debugging in most scenarios. -### Setting Up DockerSDK with XDebug +## Set up DockerSDK with XDebug -To start a testing container with XDebug enabled (disabled in the default container), execute the following command in your terminal: +To start a testing container with Xdebug enabled (disabled in the default container), execute the following command: ```bash docker/sdk testing -x ``` -### Configuring PHPStorm for XDebug +### Configure PHPStorm for XDebug -1. Open PHPStorm and navigate to Preferences → PHP → Servers. -2. Click the "+" sign to add a new configuration with the following details: +To configure PHPStorm for XDebug, do the following: + +1. In PHPStorm, go to **Preferences → PHP → Servers**. +2. Click the `+` sign to add a new configuration with the following details: - Name: spryker - Host: spryker.local -3. Enable the Use path mappings option, selecting it based on whether the server is remote or if symlinks are used. For example, map the path from /path/to/root/of/the/app to /data. +3. Enable the *Use path mappings* option, selecting it based on whether the server is remote or if symlinks are used. For example, map the path from `/path/to/root/of/the/app` to `/data`. 4. Click `Apply` and then `OK` to save the configuration. -Now, PHPStorm is ready to accept XDebug connections, and you can efficiently debug your application using Xdebug. +PHPStorm is now ready to accept XDebug connections, allowing you to debug your app using XDebug. + -Remember that these steps may vary slightly depending on your specific development environment, but this general guide should help you set up Xdebug for debugging in most scenarios. diff --git a/docs/acp/user/develop-an-app/develop-an-app.md b/docs/acp/user/develop-an-app/develop-an-app.md index 2054dad7aed..eb9414e0b35 100644 --- a/docs/acp/user/develop-an-app/develop-an-app.md +++ b/docs/acp/user/develop-an-app/develop-an-app.md @@ -15,7 +15,7 @@ Before you begin, ensure that you have the following prerequisites in place: - Completed the [thought process](#thought-process) for your app. - An empty GitHub repository. -- A local project directory for your app (e.g., `/www/my-app`). +- A local project directory for your app (for example, `/www/my-app`). - [DockerSDK](https://github.com/spryker/docker-sdk) installed globally. Make sure you have the Spryker Docker SDK, Git, and an empty repository for your app code. @@ -30,7 +30,7 @@ First, think about what your app should be capable of: what features it will bri ### API-first It's strongly recommended that apps follow the API-first approach. API-first means that your app is centered on the API. It should be possible to perform every action via the scripting language, and every piece of functionality should be available for other systems to leverage. For more information on the API-first approach, see [this blog post](https://www.algolia.com/blog/product/the-5-principles-of-api-first-development-and-what-does-api-first-even-mean/). -You need to have a clear understanding of what your app API will provide to others and always keep that in mind when designing your app. +You need to have a clear understanding of what your app API will provide to others, and always keep that in mind when designing your app. ### Schema-first @@ -60,7 +60,7 @@ git commit -m "first commit" After running these commands, you will have a new local repository that needs to be linked with your remote one. -If not done yet, create a new remote repository by opening your [Github account](https://github.com/newConnect). After you created a new repository, GitHub shows you instructions on how to continue. You should follow the list below as you don’t need some of the first steps proposed by GitHub as we’ve already initialized Git and we already have the `README.md` file from the cloned repository. +If not done yet, create a new remote repository by opening your [Github account](https://github.com/newConnect). After you created a new repository, GitHub shows you instructions on how to continue. Follow the list below, as you don’t need some of the first steps proposed by GitHub since you’ve already initialized Git and you already have the `README.md` file from the cloned repository. ```bash git branch -M main @@ -102,17 +102,17 @@ Before your app can be listed in the App Store Catalog, you need to add the foll ### Manifest -The manifest file is the most important one for the App. It contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/develop-an-app/code-snippets/manifest.html) and update it to your needs. Add the manifest file to `config/app/manifest/en_US.json` of your app. +The manifest file is the most important one for the app. It contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/develop-an-app/code-snippets/manifest.html) and update it to your needs. Add the manifest file to `config/app/manifest/en_US.json` of your app. Manifest files must have the local name as the filename, for example, `en_US.json`, and should be placed inside the `config/app/manifest` directory. ### Configuration -The configuration file contains all necessary form fields for inputs required by the user of your app, to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/develop-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your App. +The configuration file contains all necessary form fields for inputs required by the user of your app, to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/develop-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your app. ### Translation -The translation file contains all translations for the form fields you’ve previously defined. You can use the Hello World [example translation file](/docs/acp/user/develop-an-app/code-snippets/translation.html) and update it to your needs. Add this file to `config/app/translation.json` of your App. +The translation file contains all translations for the form fields you’ve previously defined. You can use the Hello World [example translation file](/docs/acp/user/develop-an-app/code-snippets/translation.html) and update it to your needs. Add this file to `config/app/translation.json` of your app. ## Add the registry (code) @@ -241,5 +241,4 @@ If you want to understand what is happening in the code, you can [debug your app Entry points for setting breakpoints are the following: - `Spryker\Glue\App\Controller\AppConfigController` -- `\Spryker\Glue\App\Controller\AppDisconnectController` - +- `\Spryker\Glue\App\Controller\AppDisconnectController` \ No newline at end of file diff --git a/docs/acp/user/develop-an-app/set-up-the-message-broker.md b/docs/acp/user/develop-an-app/set-up-the-message-broker.md index ecc6f624e8a..5ab72ee6d94 100644 --- a/docs/acp/user/develop-an-app/set-up-the-message-broker.md +++ b/docs/acp/user/develop-an-app/set-up-the-message-broker.md @@ -1,19 +1,21 @@ --- title: Set up the message broker -Descriptions: Learn how to develop an app +Descriptions: Learn how to set up the message broker template: howto-guide-template -redirect_from: -- /docs/acp/user/develop-an-app.html --- +This document describes how to set up the message broker for your app. + +## 1. Enable the message broker + +To enable the message broker for your app, install the specific branch of the `spryker/message-broker` by running the following command: -To enable the message broker functionality, you must install a special branch of the `spryker/message-broker` by running the following command: ```bash docker/sdk cli composer require "spryker/message-broker:dev-beta/localstack-replacement as 1.8.0" ``` -## Update the Code +## 2. Update the code -For testing the application, update or add the `MessageBrokerDependencyProvider` as shown in the code snippet below. +To test the app, update or add `MessageBrokerDependencyProvider` as shown in the following example: ```php Date: Fri, 15 Dec 2023 10:37:46 +0100 Subject: [PATCH 9/9] fixing the links --- _data/sidebars/acp_user_sidebar.yml | 12 ++++++------ docs/acp/user/app-configuration-translation.md | 4 ++-- .../{configuration.md => configuration-json-file.md} | 2 +- .../{manifest.md => manifest-json-file.md} | 2 +- .../{translation.md => translation-json-file.md} | 2 +- docs/acp/user/develop-an-app/develop-an-app.md | 6 +++--- docs/scos/user/intro-to-spryker/docs-updates.md | 1 - 7 files changed, 14 insertions(+), 15 deletions(-) rename docs/acp/user/develop-an-app/code-snippets/{configuration.md => configuration-json-file.md} (98%) rename docs/acp/user/develop-an-app/code-snippets/{manifest.md => manifest-json-file.md} (98%) rename docs/acp/user/develop-an-app/code-snippets/{translation.md => translation-json-file.md} (97%) diff --git a/_data/sidebars/acp_user_sidebar.yml b/_data/sidebars/acp_user_sidebar.yml index 4df47c61b6c..1e00761f3e1 100644 --- a/_data/sidebars/acp_user_sidebar.yml +++ b/_data/sidebars/acp_user_sidebar.yml @@ -15,12 +15,12 @@ entries: - title: Develop an app url: /docs/acp/user/develop-an-app/develop-an-app.html nested: - - title: Configuration code snippet - url: /docs/acp/user/develop-an-app/code-snippets/configuration.html - - title: Manifest code snippet - url: /docs/acp/user/develop-an-app/code-snippets/manifest.html - - title: Translation code snippet - url: /docs/acp/user/develop-an-app/code-snippets/translation.html + - title: Configuration JSON file + url: /docs/acp/user/develop-an-app/code-snippets/configuration-json-file.html + - title: Manifest JSON file + url: /docs/acp/user/develop-an-app/code-snippets/manifest-json-file.html + - title: Translation JSON file + url: /docs/acp/user/develop-an-app/code-snippets/translation-json-file.html - title: Set up the message broker url: /docs/acp/user/develop-an-app/set-up-the-message-broker.html - title: Debug an app with xdebug diff --git a/docs/acp/user/app-configuration-translation.md b/docs/acp/user/app-configuration-translation.md index 4a2024dcba0..fca87d06434 100644 --- a/docs/acp/user/app-configuration-translation.md +++ b/docs/acp/user/app-configuration-translation.md @@ -5,8 +5,8 @@ template: howto-guide-template related: - title: App configuration link: docs/acp/user/app-configuration.html - - title: Developing an app - link: docs/acp/user/develop-an-app.html + - title: Develop an app + link: docs/acp/user/develop-an-app/develop-an-app.html - title: App manifest link: docs/acp/user/app-manifest.html --- diff --git a/docs/acp/user/develop-an-app/code-snippets/configuration.md b/docs/acp/user/develop-an-app/code-snippets/configuration-json-file.md similarity index 98% rename from docs/acp/user/develop-an-app/code-snippets/configuration.md rename to docs/acp/user/develop-an-app/code-snippets/configuration-json-file.md index ff24a2648dd..dfb11882eec 100644 --- a/docs/acp/user/develop-an-app/code-snippets/configuration.md +++ b/docs/acp/user/develop-an-app/code-snippets/configuration-json-file.md @@ -1,5 +1,5 @@ --- -title: Configuration Json +title: Configuration JSON file Descriptions: Configuration Json code snippet template: howto-guide-template --- diff --git a/docs/acp/user/develop-an-app/code-snippets/manifest.md b/docs/acp/user/develop-an-app/code-snippets/manifest-json-file.md similarity index 98% rename from docs/acp/user/develop-an-app/code-snippets/manifest.md rename to docs/acp/user/develop-an-app/code-snippets/manifest-json-file.md index 2bfb602e13d..e3a97ef4487 100644 --- a/docs/acp/user/develop-an-app/code-snippets/manifest.md +++ b/docs/acp/user/develop-an-app/code-snippets/manifest-json-file.md @@ -1,5 +1,5 @@ --- -title: Manifest Json +title: Manifest JSON file Descriptions: Manifest Json code snippet template: howto-guide-template --- diff --git a/docs/acp/user/develop-an-app/code-snippets/translation.md b/docs/acp/user/develop-an-app/code-snippets/translation-json-file.md similarity index 97% rename from docs/acp/user/develop-an-app/code-snippets/translation.md rename to docs/acp/user/develop-an-app/code-snippets/translation-json-file.md index 3949155d591..b039020fea3 100644 --- a/docs/acp/user/develop-an-app/code-snippets/translation.md +++ b/docs/acp/user/develop-an-app/code-snippets/translation-json-file.md @@ -1,5 +1,5 @@ --- -title: Translation Json +title: Translation JSON file Descriptions: Translation Json code snippet template: howto-guide-template --- diff --git a/docs/acp/user/develop-an-app/develop-an-app.md b/docs/acp/user/develop-an-app/develop-an-app.md index eb9414e0b35..43906fcd264 100644 --- a/docs/acp/user/develop-an-app/develop-an-app.md +++ b/docs/acp/user/develop-an-app/develop-an-app.md @@ -102,17 +102,17 @@ Before your app can be listed in the App Store Catalog, you need to add the foll ### Manifest -The manifest file is the most important one for the app. It contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/develop-an-app/code-snippets/manifest.html) and update it to your needs. Add the manifest file to `config/app/manifest/en_US.json` of your app. +The manifest file is the most important one for the app. It contains data that will be displayed in the App Store Catalog. You can use the [manifest code snippet](/docs/acp/user/develop-an-app/code-snippets/manifest-json-file.html) and update it to your needs. Add the manifest file to `config/app/manifest/en_US.json` of your app. Manifest files must have the local name as the filename, for example, `en_US.json`, and should be placed inside the `config/app/manifest` directory. ### Configuration -The configuration file contains all necessary form fields for inputs required by the user of your app, to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/develop-an-app/code-snippets/configuration.html) and update it to your needs. Add this file to `config/app/configuration.json` of your app. +The configuration file contains all necessary form fields for inputs required by the user of your app, to be displayed in the App Store Catalog. You can use the [configuration code snippet](/docs/acp/user/develop-an-app/code-snippets/configuration-json-file.html) and update it to your needs. Add this file to `config/app/configuration.json` of your app. ### Translation -The translation file contains all translations for the form fields you’ve previously defined. You can use the Hello World [example translation file](/docs/acp/user/develop-an-app/code-snippets/translation.html) and update it to your needs. Add this file to `config/app/translation.json` of your app. +The translation file contains all translations for the form fields you’ve previously defined. You can use the Hello World [example translation file](/docs/acp/user/develop-an-app/code-snippets/translation-json-file.html) and update it to your needs. Add this file to `config/app/translation.json` of your app. ## Add the registry (code) diff --git a/docs/scos/user/intro-to-spryker/docs-updates.md b/docs/scos/user/intro-to-spryker/docs-updates.md index b0bd955c7d2..a88512b24b1 100644 --- a/docs/scos/user/intro-to-spryker/docs-updates.md +++ b/docs/scos/user/intro-to-spryker/docs-updates.md @@ -30,7 +30,6 @@ In October 2023, we have added and updated the following pages: - [Use API Key authorization](/docs/scos/dev/glue-api-guides/202307.0/use-api-key-authorization.html): Learn how to use the API Key authorization mechanism that lets users authenticate themselves with their API Key generated from the Back Office. - [Decoupled Glue infrastructure: Integrate the API Key authorization](/docs/scos/dev/migration-concepts/migrate-to-decoupled-glue-infrastructure/decoupled-glue-infrastructure-integrate-api-key-authorization.html): Learn how to integrate the API Key authorization to Backend API applications. - [Test the asynchronous API](/docs/scos/dev/guidelines/testing-guidelines/executing-tests/test-the-asynchronous-api.html): Learn how to set up and run AsyncAPI tests. -- [Create an app with AppKernel](/docs/acp/user/develop-an-app/create-an-app-with-appkernel.html): Learn how to use AppKernel with Spryker’s Mini Framework to develop an app. - [Install the Service Points Cart + Checkout feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-service-points-cart-checkout-feature.html). - [Install the Service Points Cart feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-service-points-cart-feature.html). - [Install the Shipment Product Offer + Service Points Availability feature](/docs/pbc/all/service-points/202311.0/unified-commerce/install-and-upgrade/install-the-shipment-product-offer-service-points-availability-feature.html).