spryker/app-kernel

AppKernel module

2.3.0 2024-12-12 10:03 UTC

Requires

• php: >=8.2
• guzzlehttp/psr7: ^2.7
• league/openapi-psr7-validator: ^0.22.0
• spryker/app-kernel-extension: ^1.0.0
• spryker/glue-application-extension: ^1.0.0
• spryker/kernel: ^3.30.0
• spryker/log: ^3.0.0
• spryker/message-broker: ^1.11.0
• spryker/propel-encryption-behavior: ^0.1.1
• spryker/secrets-manager: ^1.0.0
• spryker/secrets-manager-extension: ^1.0.0
• spryker/symfony: ^3.0.0
• spryker/transfer: ^3.33.0
• spryker/translator: ^1.13.0
• spryker/util-encoding: ^2.0.0
• spryker/util-text: ^1.0.0

Requires (Dev)

• codeception/codeception: ^5.0
• codeception/module-cli: ^2.0.0
• codeception/module-filesystem: ^3.0.0
• codeception/module-phpbrowser: ^3.0.0
• codeception/module-rest: ^3.0.0
• codeception/module-webdriver: ^3.0.0
• phpstan/phpdoc-parser: 1.25.0
• phpstan/phpstan: 1.10.66
• rector/rector: ^0.19.0
• spryker/code-sniffer: *
• spryker/container: *
• spryker/development: ^3.34.0
• spryker/glue-application: ^1.64.0
• spryker/glue-backend-api-application: ^1.6.0
• spryker/glue-json-api-convention: ^1.3.0
• spryker/http: ^1.11.0
• spryker/message-broker-aws: ^1.7.0
• spryker/propel: *
• spryker/testify: *
• spryker/testify-async-api: ^0.1.4

proprietary

README

Provides SyncAPI and AsyncAPI schema files and the needed code to make the Mini-Framework an App.

Installation

composer require spryker/app-kernel

Configure

App Identifier

config/Shared/config_default.php

use Spryker\Shared\AppKernel\AppKernelConstants;

$config[AppKernelConstants::APP_IDENTIFIER] = getenv('APP_IDENTIFIER') ?: 'hello-world';
$config[AppKernelConstants::OPEN_API_SCHEMA_PATH] = 'path/to/your/openApiSchema.yml';

Validating Requests against the OpenAPI Schema

Low level validation can be done by using the Spryker\Zed\AppKernel\Communication\Plugin\OpenApiSchemaValidatorPlugin plugin. When this plugin is added to the GlueApplicationDependencyProvider all API requests against this App will be validated against the defined OpenAPI schema.

To enable this, you need to have a well-defined OpenAPI schema file, and you need to add the OpenApiSchemaValidatorPlugin plugin to the getRestApplicationPlugins method in your GlueApplicationDependencyProvider.

use Spryker\Zed\AppKernel\Communication\Plugin\OpenApiSchemaValidatorPlugin;

...

    protected function getRestApplicationPlugins(): array
    {
        return [
            new OpenApiSchemaValidatorPlugin(),
        ];
    }

...

Pay intention that this will be a hard validation that gets executed before any other code from your App gets executed. If the validation fails, the request will be rejected with a 400 Bad Request response with a proper message that explains what exactly is wrong in the request.

Make sure you have tests for your API.

Testing the AppKernel

You can test the AppKernel as usual with Codeception. Before that you need to run some commands:

composer setup

With these commands you've set up the AppKernel and can start the tests

vendor/bin/codecept build
vendor/bin/codecept run

Documentation

Configuration

AppIdentifier

Every App needs a unique App Identifier which needs to be configured in the config/Shared/config_default.php file after installation.

use Spryker\Shared\AppKernel\AppConstants;

$config[AppConstants::APP_IDENTIFIER] = getenv('APP_IDENTIFIER') ?: '1ba6db00-d12c-43c9-9783-936e4cded397';

High-Level Architecture

Features

Encryption

This package comes with a built-in Encryption for data that gets persisted. By default, the encryption is disabled but can be easily enabled. After installation and setup, you can configure the encryption of sensitive data.

Enable Plugin

The encryption will be done with the help of a plugin. You can add the required plugin to the \Pyz\Client\SecretsManager\SecretsManagerDependencyProvider::getSecretsManagerProviderPlugin() method on the project level.

Currently, we have an AWS Plugin available for you \Spryker\Client\SecretsManagerAws\Plugin\SecretsManager\SecretsManagerAwsProviderPlugin for any other encryption you need to create your own plugin.

You can install the package that contains the plugin with

composer require spryker/secrets-manager-aws

Extend the Propel schema

Add a spy_app_kernel.schema.xml on the project level to src/Pyz/AppKernel/Zed/Persistence/Propel/schema and update the columns you want to be encrypted.

Example

<?xml version="1.0"?>
<database xmlns="spryker:schema-01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="zed" xsi:schemaLocation="spryker:schema-01 https://static.spryker.com/schema-01.xsd" namespace="Orm\Zed\AppKernel\Persistence" package="src.Orm.Zed.AppKernel.Persistence">

    <table name="spy_app_config" identifierQuoting="true">
        <behavior name="encryption">
            <parameter name="column_name_1" value="config"/>
        </behavior>
    </table>

</database>

Next, execute the migrations by running the docker/sdk console propel:install command, then these columns will be encrypted.

Plugins

This package provides the following plugins

Glue

• \Spryker\Glue\AppKernel\Plugin\RouteProvider\AppKernelRouteProviderPlugin

AppKernelRouteProviderPlugin

This plugin must be added to the \Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins().

Extension

In most cases, the default behavior of the AppKernel will be enough. When you need to add or change behavior we provide extension points you can use to change the AppKernel.

This package provides the following extensions.

Glue

• Configuration validation plugins
• Disconnect validation plugins

Configuration validation plugins

This plugin stack can be used to add your own validators for the configuration of the App. This will most likely be useful when you need to validate the passed configuration from the App Store Catalog e.g. checking against the implemented provider if credentials are valid.

You can add your own plugins to the \Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestConfigureValidatorPlugins() method on the project level.

Disconnect validation plugins

This plugin stack can be used to add your own validators for the disconnect of the App. This can be used e.g. for validating if the App can be disconnected or not.

You can add your own plugins to the \Pyz\Glue\AppKernel\AppKernelDependencyProvider::getRequestDisconnectValidatorPlugins() method on the project level.

Zed

Zed offers the following extension points

• \Spryker\Zed\AppKernelExtension\Dependency\Plugin\AppKernelPlatformPluginInterface
• \Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeSavePluginInterface
• \Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterSavePluginInterface
• \Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationBeforeDeletePluginInterface
• \Spryker\Zed\AppKernelExtension\Dependency\Plugin\ConfigurationAfterDeletePluginInterface

Both save and delete actions can be extended with a plugin that needs to be executed before and after the AppKernel code is executed.

AppKernelPlatformPluginInterface

You can implement this plugin in the Apps PlatformPlugin. It enables the validation of the configuration that gets passed from the AppStoreCatalog.

ConfigurationBeforeSavePluginInterface

You can add your plugins to the \Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeSavePlugins() method on the project level.

ConfigurationAfterSavePluginInterface

You can add your plugins to the \Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterSavePlugins() method on the project level.

ConfigurationBeforeDeletePluginInterface

You can add your plugins to the \Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationBeforeDeletePlugins() method on the project level.

ConfigurationAfterDeletePluginInterface

You can add your plugins to the \Pyz\Zed\AppKernel\AppKernelDependencyProvider::getConfigurationAfterDeletePlugins() method on the project level.