diff --git a/concepts/api/index.md b/concepts/api/index.md index 3ba222ae63..f8c23e8512 100644 --- a/concepts/api/index.md +++ b/concepts/api/index.md @@ -21,3 +21,7 @@ Both APIs use HTTP and exchange JSON payloads. The Administration API requires O * Header-based contextual behavior These patterns form the foundation of integration development. + +## Start building + +Use the [API](../../guides/development/integrations-api/index.md) guide for practical API setup, authentication, request examples, and links to the generated API reference. diff --git a/concepts/extensions/index.md b/concepts/extensions/index.md index daabf94fa9..64536a511e 100644 --- a/concepts/extensions/index.md +++ b/concepts/extensions/index.md @@ -22,9 +22,12 @@ Starting with Shopware 6.4.0.0, we introduced a new way to extend Shopware using Plugins are executed within the Shopware Core process and can react to events, execute custom code or extend services. They have direct access to the database and guidelines are in place to ensure update-compatibility, such as a service facade or database migrations. ::: warning -**Plugins and Shopware cloud** - Due to their direct access to the Shopware process and the database, plugins are not supported by Shopware cloud. +Due to their direct access to the Shopware process and the database, **plugins are not supported by Shopware cloud**. ::: -## Start coding +## Start building -Refer to our Guides section for an [overview of how apps and plugins differ](../../guides/plugins/index). +Use the [Extensions](../../guides/development/extensions/index.md) guide to choose between apps and plugins, or go directly to the implementation path you need: + +- [App Base Guide](../../guides/plugins/apps/app-base-guide.md) +- [Plugin Base Guide](../../guides/plugins/plugins/plugin-base-guide.md) diff --git a/guides/development/integrations-api/index.md b/guides/development/integrations-api/index.md index e33ab5a8d2..6a016ff30b 100644 --- a/guides/development/integrations-api/index.md +++ b/guides/development/integrations-api/index.md @@ -11,7 +11,7 @@ This guide helps you make your first successful API request. Your Shopware insta Shopware provides two HTTP APIs: -- **Admin API** for backend operations such as products, orders, customers, plugins, and (via the Sync API) bulk processing +- **Admin API** for backend operations such as products, orders, customers, plugins, and — via the Sync API — bulk operations (for example, mass imports) - **Store API** for storefront-facing interactions such as headless frontends, mobile apps, carts, checkout, and sales channel access For the complete endpoint reference and schemas, use the official Stoplight documentation: diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md index 594b7373a2..b2b73f4684 100644 --- a/guides/development/tooling/index.md +++ b/guides/development/tooling/index.md @@ -7,7 +7,38 @@ nav: # Tooling -Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance: +Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance. + +## Choosing the right CLI + +Shopware projects use two main command-line entry points: + +| Tool | Use it for | +|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bin/console` | Commands provided by the Shopware application itself, such as plugin lifecycle commands, database migrations, cache clearing, scheduled tasks, and system inspection. | +| [`shopware-cli`](https://github.com/shopware/shopware-cli/) | Project and extension tooling around Shopware, such as creating projects, running the development environment, building assets, validating and packaging extensions, Store interaction, and CI workflows. | +| `shopware-cli project console ` | Running a Shopware `bin/console` command through Shopware CLI when you want the CLI to resolve the project context for you. | +| `swx ` | Short alias for `shopware-cli project console `, useful for daily development commands. | +| `shopware-cli project dev` | Starting the interactive local development environment and TUI for managing the Docker-based stack, logs, watchers, and common development tasks. | + +As a rule of thumb: use `bin/console` for application-level Shopware commands, use `shopware-cli` for project, extension, build, CI, and development-environment workflows, and use `swx` when you want a quick wrapper around `bin/console`. + +## Raw commands, helper commands, or deployment tooling? + +Use the lowest-level command that fits the task, but prefer helper or deployment tooling when the same steps need to be repeated reliably. + +| Situation | Prefer | Why | +|-----------------------------------------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| Running a one-off Shopware application command locally | `bin/console` | Direct access to commands provided by the Shopware application. | +| Running common Shopware commands during daily development | `shopware-cli project console ` or `swx ` | Wraps `bin/console` through Shopware CLI and resolves the project context for you. | +| Starting or managing the local development stack | `shopware-cli project dev` | Provides the interactive development environment for the Docker-based stack, logs, watchers, and common development tasks. | +| Building a project in CI | `shopware-cli project ci` | Produces a reproducible build artifact with dependencies and assets prepared before deployment. | +| Installing, updating, or maintaining a deployed instance | Deployment Helper | Automates deploy-time tasks such as install/update detection, migrations, extension management, maintenance mode, cache handling, and one-time commands. | +| Debugging an exceptional production issue manually | Raw commands, carefully | Useful for investigation, but repeated deployment or maintenance steps should move into Deployment Helper configuration. | + +As a rule of thumb: use raw `bin/console` commands for direct local or diagnostic work, Shopware CLI helpers for daily development convenience, and Deployment Helper for repeatable deployment and maintenance workflows. + +## Available tooling - [Development Environment](../dev-environment.md): The Docker-based development environment with an interactive terminal dashboard that manages your entire stack, streams logs, and controls watchers. diff --git a/guides/hosting/configurations/shopware/index.md b/guides/hosting/configurations/shopware/index.md index 86d21d83d2..d67ac8cb88 100644 --- a/guides/hosting/configurations/shopware/index.md +++ b/guides/hosting/configurations/shopware/index.md @@ -5,8 +5,26 @@ nav: --- -# Shopware configurations +# Shopware Configurations ## Overview The following section guides you on the security, performance or structural configurations specific to Shopware 6. + +## How Shopware configuration works + +Shopware configuration can come from different places, depending on whether the value is operational, environment-specific, or meant to be changed by shop administrators. + +| Mechanism | Use it for | Where it lives | +|--------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| Database-backed system configuration | Shop settings that can be changed in the Administration, through Admin API, or by app/plugin code | Stored in the database and read through Shopware's system configuration | +| Static system configuration | Settings that must be fixed, versioned, or controlled per environment | `config/packages/*.yaml` under `shopware.system_config` | +| Symfony / bundle configuration | Technical runtime configuration for Shopware, Symfony, or bundles | `config/packages/*.yaml`, including environment-specific folders such as `config/packages/prod/` | +| Environment variables | Secrets, infrastructure values, and deployment-specific values | `.env`, `.env.local`, server/container environment, or deployment platform | +| CLI commands | Reading, writing, or inspecting configuration during development, deployment, or maintenance | `bin/console` / `shopware-cli project console` | + +As a rule of thumb: use Administration or database-backed system configuration for shop settings that merchants may change, static system configuration for values that should be fixed or version-controlled, and environment variables or Symfony configuration for deployment and infrastructure settings. + +Static system configuration is an overlay on top of database-loaded system configuration. If the same key is configured in both places, the value from `config/packages` wins and the setting can no longer be changed in the Administration. + +For details, see [Static System Configuration](./static-system-config.md). diff --git a/guides/hosting/installation-updates/extension-management.md b/guides/hosting/installation-updates/extension-management.md index e1a1344034..f8915b9527 100644 --- a/guides/hosting/installation-updates/extension-management.md +++ b/guides/hosting/installation-updates/extension-management.md @@ -54,6 +54,10 @@ bin/console plugin:install --activate You can also find the Composer package name when you click "Install via Composer" in the Shopware Account. +:::warning +Removing a Composer package or uninstalling a plugin does not cancel a paid subscription. License state is managed in the Shopware Account, and cancellation must be done there. +::: + ## Migrating already installed extensions to Composer If you already have extensions installed in your project, you can migrate them to Composer. First, you should install the extension with Composer: diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 970649c209..7db6b8c8fe 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -27,23 +27,20 @@ Development tools such as: are managed via the Shopware CLI. These are installed into the user's environment and shared across projects and extensions, rather than being added as project-level `require-dev` dependencies. -[Demo data](https://github.com/shopware/SwagPlatformDemoData) is optional and can be installed during the in-browser first-run wizard. +[Demo data](https://github.com/shopware/SwagPlatformDemoData) is optional. For developer setups, prefer terminal-based setup and development workflows instead of the in-browser First Run Wizard. Your local project is ready for debugging, profiling, and extension development out of the box. In day-to-day development, you'll mostly interact with: -- **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.) -- **custom/**: where you build your own plugins and themes -- **bin/console**: the application CLI that ships with Shopware (Symfony console). - It is used for tasks such as running migrations, installing plugins, clearing caches, or managing configuration in your project. +- **`shopware-cli project dev`**: starts and manages the Docker-based development environment, including containers, logs, watchers, credentials, and service URLs. +- **`shopware-cli project console `**: runs Shopware application commands from your host without opening an interactive container shell. +- **`swx `**: shortcut for `shopware-cli project console `, for example `swx cache:clear`. +- **`custom/`**: where you build your own plugins and themes. -:::info -`bin/console` differs from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) used for extension builds and CI workflows. -The Docker setup already includes the standalone Shopware CLI inside the container. -::: +`bin/console` is the application CLI that ships with Shopware (Symfony console). Use it for Shopware application commands such as migrations, plugin installation, cache clearing, or configuration changes. In Docker-based setups, run those commands through `shopware-cli project console` or `swx` so they execute in the correct container context. -Most other files in the project either configure the environment or support these core layers. +The standalone [Shopware CLI](https://github.com/shopware/shopware-cli) is different from `bin/console`: it manages project workflows such as the development environment, helper commands, extension builds, and CI workflows. ## Project template @@ -107,7 +104,7 @@ This table outlines the key directories and files in your Shopware project and t | **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | | **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions - your "src" for Shopware plugins. | | **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | -| **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | +| **Makefile** | Legacy build helper | May exist in older setups with shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | | **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | | **src/** | Source code | Shopware's core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | | **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | diff --git a/guides/plugins/apps/administration/meteor-admin-sdk.md b/guides/plugins/apps/administration/meteor-admin-sdk.md index 8166375033..4301099566 100644 --- a/guides/plugins/apps/administration/meteor-admin-sdk.md +++ b/guides/plugins/apps/administration/meteor-admin-sdk.md @@ -10,12 +10,12 @@ The [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/adm To write advanced apps, its recommended that you use the [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/admin-sdk). It contains helper functions to communicate with the Administration, execute actions, subscribe to data or extend the user interface. It has many more features and is more flexible. -- 🏗 **Works with Shopware 6 Apps and Plugins:** You can use the SDK for your plugins or apps. API usage is identical. -- ðŸŽĒ **Shallow learning curve:** You don't need to have extensive knowledge about the internals of the Shopware 6 Administration. Our SDK hides the complicated stuff behind a beautiful API. -- 🧰 **Many extension capabilities:** Includes throwing notifications, accessing context information, extending the current UI and more. The feature set of the SDK will gradually be extended, providing more possibilities and flexibility for your ideas and solutions. -- ðŸŠĻ **A stable API with great backwards compatibility:** Don't fear Shopware updates anymore. Breaking changes in this SDK are an exception. If you use the SDK, your apps and plugins will stay stable for a longer time, without any need for code maintenance. -- 🧭 **Type safety:** The whole SDK is written in TypeScript which provides great autocompletion support and more safety for your apps and plugins. -- 💙 **Developer experience:** Have a great development experience right from the start. And it will become better and better in the future. -- ðŸŠķ **Lightweight:** The whole library is completely tree-shakable and dependency-free. Every functionality can be imported granularly to keep your bundle as small and fast as possible. +- **Works with Shopware 6 Apps and Plugins:** You can use the SDK for your plugins or apps. API usage is identical. +- **Shallow learning curve:** You don't need to have extensive knowledge about the internals of the Shopware 6 Administration. Our SDK hides the complicated stuff behind a beautiful API. +- **Many extension capabilities:** Includes throwing notifications, accessing context information, extending the current UI and more. The feature set of the SDK will gradually be extended, providing more possibilities and flexibility for your ideas and solutions. +- **A stable API with great backwards compatibility:** Don't fear Shopware updates anymore. Breaking changes in this SDK are an exception. If you use the SDK, your apps and plugins will stay stable for a longer time, without any need for code maintenance. +- **Type safety:** The whole SDK is written in TypeScript which provides great autocompletion support and more safety for your apps and plugins. +- **Developer experience:** Have a great development experience right from the start. And it will become better and better in the future. +- **Lightweight:** The whole library is completely tree-shakable and dependency-free. Every functionality can be imported granularly to keep your bundle as small and fast as possible. -Go to [Installation](https://developer.shopware.com/resources/admin-extension-sdk/getting-started/installation.html) to get started. Or check out the [quick start guide](https://developer.shopware.com/resources/admin-extension-sdk/#quick-start). +[Get started here](https://developer.shopware.com/resources/admin-extension-sdk/getting-started/). diff --git a/guides/plugins/plugins/administration/index.md b/guides/plugins/plugins/administration/index.md index 1f5d4c600f..a708d2ce05 100644 --- a/guides/plugins/plugins/administration/index.md +++ b/guides/plugins/plugins/administration/index.md @@ -21,6 +21,8 @@ Typical use cases include: This section follows a practical development workflow. Start with registering a module and route, then build the components, connect data, and refine permissions and UI behavior. +For stable cross-version extension points, use the [Meteor Admin SDK](../../apps/administration/meteor-admin-sdk.md). The SDK can be used by both apps and plugins. + ## Developer workflow When extending the Administration inside a plugin, follow this sequence: diff --git a/guides/plugins/plugins/creating-plugins.md b/guides/plugins/plugins/creating-plugins.md index f020813d04..0996580fec 100644 --- a/guides/plugins/plugins/creating-plugins.md +++ b/guides/plugins/plugins/creating-plugins.md @@ -126,7 +126,7 @@ Here's an example `composer.json` you can refer to: } ], "require": { - "shopware/core": "~6.6.0" + "shopware/core": "~6.7.0" }, "extra": { "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample", @@ -157,6 +157,19 @@ If you change the `autoload.psr-4` path (for example, not using `src/`), adjust Set up [CI](../../development/testing/ci.md) early. Run static analysis, tests, and `shopware-cli extension build` in CI so your plugin ZIP is reproducible and safe to promote across environments. ::: +### Depending on other plugins + +If your plugin requires another plugin to be installed, declare it in the `require` section of your `composer.json` using the other plugin's Composer name and version (here, an example plugin named `swag/other-plugin`): + +```json +"require": { + "shopware/core": "~6.7.0", + "swag/other-plugin": "^1.0" +} +``` + +Shopware will then enforce that the required plugin is installed and activated first. For version constraints, dev setups, and store considerations, see [Add Plugin Dependencies](./dependencies/add-plugin-dependencies.md). + ## Add Shopware Packagist (optional) Shopware's Packagist instance enables management of Shopware Store plugins directly in the `composer.json`. To add the repository to your project, run: @@ -165,7 +178,7 @@ Shopware's Packagist instance enables management of Shopware Store plugins direc composer config repositories.shopware composer https://packages.shopware.com ``` -Authentication via API token is required. Refer to ["Using Composer for plugin installation in Shopware"](https://www.shopware.com/en/news/using-composer-for-plugin-installation-in-shopware/) for detailed information. +Authentication via API token is required. Refer to [Extension Management](../../hosting/installation-updates/extension-management.md) for how to obtain the token and set up `auth.json`. ## Manual creation (optional) diff --git a/guides/plugins/plugins/database/database-migrations.md b/guides/plugins/plugins/database/database-migrations.md index e0989d6a44..7da92d7cc9 100644 --- a/guides/plugins/plugins/database/database-migrations.md +++ b/guides/plugins/plugins/database/database-migrations.md @@ -38,19 +38,6 @@ As you can see, there is one file in the `/src/Migration` directory | 1546422281 | A Timestamp used to make migrations incremental | | ExampleDescription | A descriptive name for your migration | -### Customizing the migration path / namespace - -You are also able to change the migration directory. This is done by choosing another namespace for your migrations, which can be changed by overwriting your plugin's `getMigrationNamespace()` method in the plugin base class: - -```php -public function getMigrationNamespace(): string -{ - return 'Swag\BasicExample\MyMigrationNamespace'; -} -``` - -Since the path is read from the namespace, your Migration directory would have to be named `MyMigrationNamespace` now. - ## Generate migration skeleton To generate the boilerplate code for your migration, you have to open your Shopware root directory in your terminal and execute the command `database:create-migration`. Below you can see the command used in this example to create the migration seen above in the file structure. @@ -210,3 +197,16 @@ Therefore, a typical update method might look more like this: ``` If you don't use the Shopware migration system, an empty collection (`NullObject`) will be in the context. + +### Customizing the migration path / namespace + +Most plugins should keep the default `src/Migration` directory — the tooling and examples in this guide assume it. If you have a specific reason to relocate your migrations, you can choose another namespace for them by overwriting your plugin's `getMigrationNamespace()` method in the plugin base class: + +```php +public function getMigrationNamespace(): string +{ + return 'Swag\BasicExample\MyMigrationNamespace'; +} +``` + +Since the path is read from the namespace, your Migration directory would have to be named `MyMigrationNamespace` now. diff --git a/guides/plugins/plugins/dependencies/using-composer-dependencies.md b/guides/plugins/plugins/dependencies/using-composer-dependencies.md index 32e5237ee3..5f0b28486d 100644 --- a/guides/plugins/plugins/dependencies/using-composer-dependencies.md +++ b/guides/plugins/plugins/dependencies/using-composer-dependencies.md @@ -7,23 +7,32 @@ nav: # Adding Composer Dependencies +Use this guide when your extension needs another PHP package — for example, a library for exports, PDF generation, or an external API client. Like any PHP project, Shopware plugins declare such packages in their `composer.json` via the `require` section. + ## Overview -In this guide you'll learn how to add Composer dependencies to your project. +How the dependency gets installed depends on how your plugin is set up: + +* **Static plugins or Composer-managed plugins (recommended):** The project's root Composer installation resolves and installs your plugin's dependencies automatically. No extra steps are needed — this is one of the main reasons the [static plugin approach](../plugin-base-guide.md) is recommended. +* **Zip-installed plugins (e.g., distributed via the Shopware Store):** The dependencies are not resolved by the project. You must either let Shopware run Composer during installation by overriding `executeComposerCommands()`, or bundle the packages with your plugin. Both options are described below. ## Prerequisites -All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of Node and NPM is required. +All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. -## Adding a Composer plugin to the `composer.json` file +## Adding a Composer package to the `composer.json` file -In this guide we will install [`exporter`](https://github.com/sebastianbergmann/exporter), which provides the functionality to export PHP variables for visualization. +As an example, in this guide we will install [`exporter`](https://github.com/sebastianbergmann/exporter), a package that provides the functionality to export PHP variables for visualization. -Now we can simply install the `exporter` package by adding `"sebastian/exporter": "*"` to the list in `require` section of the `composer.json` of our plugin. +Before installing, temporarily remove the `shopware/core` entry from the `require` section of your plugin's `composer.json`. Otherwise, Composer would download Shopware itself into your plugin's `vendor` directory. -Now we can simply install `exporter` by running `composer require sebastian/exporter` in your plugin directory. +Now run the following command in your plugin directory: + +```bash +composer require sebastian/exporter +``` -After that we have to add our dependency to shopware back in. +This adds the package to the `require` section of your plugin's `composer.json` and installs it. Afterwards, add the `shopware/core` requirement back in. ::: warning The `vendor` directory, where the Composer saves the dependencies, has to be included in the plugin bundle. The plugin bundle size is not allowed to exceed 5 MB. diff --git a/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md b/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md index 70ad5a1a41..80da096817 100644 --- a/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md +++ b/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md @@ -13,11 +13,9 @@ Plugins often need to save data into a custom database table. Shopware 6's data ## Prerequisites -This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create a database table, you need to understand plugin migrations [Plugin migrations](../../database/database-migrations.md). Also, you'll have to understand how the [Dependency injection](../../services/dependency-injection.md) works as well. +This guide builds upon the [Plugin base guide](../../../plugins/plugin-base-guide.md), but any plugin will work here. Just note that all examples reference that plugin. -::: info -Refer to this video on **[Creating a custom entity](https://www.youtube.com/watch?v=mTHTyof4gPk)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: +Before creating a custom DAL entity you'll need to create a database table, which requires an understanding of [plugin migrations](../../database/database-migrations.md). Familiarity with [Dependency injection](../../services/dependency-injection.md) is also required, because the entity definition is registered as a service. ## Creating the database table @@ -25,7 +23,7 @@ We'll start with creating a new database table. Make sure to always add your ind In this guide we'll name our table `swag_example`, you'll find this name a few more times in here, so make sure to remember that one. -As already mentioned in the prerequisites, creating a database table is done via plugin migrations [Plugin migrations](../../database/database-migrations.md), head over to this guide to understand how this example works. +As already mentioned in the prerequisites, creating a database table is done via [plugin migrations](../../database/database-migrations.md) - use the guide to understand how this example works. ```php // /src/Migration/Migration1611664789Example.php diff --git a/guides/plugins/plugins/framework/data-handling/index.md b/guides/plugins/plugins/framework/data-handling/index.md index 774fa14dee..47ac5a5e06 100644 --- a/guides/plugins/plugins/framework/data-handling/index.md +++ b/guides/plugins/plugins/framework/data-handling/index.md @@ -9,12 +9,12 @@ nav: The data handling, or the Data Abstraction Layer \(DAL\), can be an overwhelming topic. Yet, if you know the right start, it will be fairly easy to deal with. -Hence, here are some good starting topics: +Start with the step that matches what you want to do: - +- Create or change database tables for a plugin - [Database migrations](../../database/database-migrations.md) +- Add a custom DAL entity for a plugin table - [Adding Custom Complex Data](add-custom-complex-data.md) +- Read data through repositories and criteria - [Reading Data](reading-data.md) +- Write data through repositories - [Writing Data](writing-data.md) +- React to DAL write or entity events - [Using Database Events](using-database-events.md) - - - - -Also, [listening to events](using-database-events) of the DAL will come in handy for sure. +For custom plugin data, create the database table first with a migration, then add the DAL entity definition that maps to that table. diff --git a/guides/plugins/plugins/index.md b/guides/plugins/plugins/index.md index 556b61bef5..e0c6f640a6 100644 --- a/guides/plugins/plugins/index.md +++ b/guides/plugins/plugins/index.md @@ -70,6 +70,8 @@ Shopware supports multiple plugin models, which differ in their folder structure ### Static plugins (recommended) +For new developers building custom project logic, static plugins are the recommended starting point. Use managed plugins mainly for marketplace or Administration-managed extensions, and use bundles when you deliberately do not need the Shopware plugin lifecycle or Administration management. + Project-specific static plugins live in `/custom/static-plugins`, which contains all project-specific plugins that are typically committed to the Git repository. The Shopware Administration does not detect static plugins. They must be required via Composer before they can be installed and activated: ```bash diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md index 2122a3609b..657606864a 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md @@ -23,7 +23,7 @@ A running plugin. Review the [Plugin Base Guide](../plugin-base-guide.md) for in This video is part of the free Shopware Academy online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). ::: -Create `src/Resources/config/config.xml` inside your plugin. The content of the `config.xml` will be dynamically rendered in the Administration. +Create `src/Resources/config/config.xml` inside your plugin. The content of the `config.xml` will be dynamically rendered in the Administration. Start with a simple text field first; the available field types and advanced options are listed below. An example structure: diff --git a/guides/plugins/plugins/plugin-fundamentals/index.md b/guides/plugins/plugins/plugin-fundamentals/index.md index 94513cce8a..a01ec59b6e 100644 --- a/guides/plugins/plugins/plugin-fundamentals/index.md +++ b/guides/plugins/plugins/plugin-fundamentals/index.md @@ -7,10 +7,24 @@ nav: # Plugin Fundamentals -This section covers the core building blocks of a Shopware plugin: +Plugin fundamentals are the building blocks for adding behavior to a Shopware plugin. Use this page to jump directly to the task you want to solve. -* **Plugin lifecycle** — install, activate, deactivate, and uninstall hooks -* **Plugin configuration** — defining and using configuration options -* **CLI commands** — registering custom Symfony console commands -* **Scheduled tasks** — running recurring background jobs -* **Logging** — adding diagnostics to your plugin +## What do you want to do? + +- Run code when a plugin is installed, updated, activated, deactivated, or uninstalled: [Plugin lifecycle](plugin-lifecycle.md) +- Add configurable settings that appear in the Administration: [Plugin configuration](add-plugin-configuration.md) +- Add a custom Symfony console command: [CLI commands](add-custom-commands.md) +- Run recurring background work: [Scheduled tasks](add-scheduled-task.md) +- Add diagnostics and write plugin logs: [Logging](logging.md) +- Register services or inject dependencies: [Services and dependency injection](../services/index.md) +- React to Shopware events: [Listening to events](../framework/event/listening-to-events.md) +- Change or extend existing services: [Decorating services](../services/adjusting-service.md#decorating-the-service) +- Add a Storefront URL or render a Storefront response: [Add Custom Controller](../storefront/controllers/add-custom-controller.md) +- Add database changes: [Database migrations](../database/database-migrations.md) +- Add Composer or npm dependencies: [Plugin dependencies](../dependencies/index.md) + +As a rule of thumb: use an event subscriber when your plugin reacts to something Shopware already does, use a controller when you need a new HTTP entry point, use a command for manual or scripted CLI work, and use a scheduled task for recurring background work. + +## Recommended path + +If you are new to plugin development, start with the [Plugin Base Guide](../plugin-base-guide.md). It explains the typical plugin development flow from creation and installation through lifecycle, configuration, services, events, database changes, testing, and diagnostics. diff --git a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md index 016cc424ac..e46b5da98d 100644 --- a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md @@ -7,13 +7,13 @@ nav: # Use Plugin Configuration -The [Add a Plugin Configuration Guide](add-plugin-configuration.md) shows how to define configuration options in your plugins. This guide helps you to use them in your plugin. +The [Add a Plugin Configuration Guide](add-plugin-configuration.md) shows how to define configuration options in your plugins. This guide helps you to use them in your plugin, showing you how to read plugin configuration values in PHP, Administration JavaScript, and Storefront code. ## Prerequisites -- Review the [Plugin Base Guide](../plugin-base-guide.md) -- [Plugin configuration](add-plugin-configuration.md) — complete this first -- Familiarity with the [Listening to events](../framework/event/listening-to-events.md) guide, as in this example the configuration is read inside of a subscriber +- First, review the [Plugin Base Guide](../plugin-base-guide.md) +- Then define a plugin configuration field in [Add plugin configuration](add-plugin-configuration.md) +- Get familiar with the [Listening to events](../framework/event/listening-to-events.md) guide, as in this example the configuration is read inside of a subscriber The example plugin includes a subscriber that listens to the `product.loaded` event and is called every time a product is loaded. diff --git a/guides/plugins/plugins/services/adjusting-service.md b/guides/plugins/plugins/services/adjusting-service.md index 93c4c30b70..13b7dfda1c 100644 --- a/guides/plugins/plugins/services/adjusting-service.md +++ b/guides/plugins/plugins/services/adjusting-service.md @@ -7,6 +7,10 @@ nav: # Adjusting a Service +Service decoration is one of the main ways to extend Shopware behavior from a plugin, alongside reacting to events. Prefer events when you need to react to something Shopware does. Prefer service decoration when you need to change how an existing service behaves. + +Shopware services that are designed for decoration often expose an abstract class as their contract instead of a PHP interface. The abstract class provides the `getDecorated()` chain and allows new non-abstract methods to be added without immediately breaking existing decorators. + This guide explains how to adjust a service using decoration. For more details, see the [Symfony documentation](https://symfony.com/doc/current/service_container/service_decoration.html). ## Prerequisites diff --git a/guides/plugins/plugins/services/index.md b/guides/plugins/plugins/services/index.md index 42f1c2f2c2..95dcf36ce2 100644 --- a/guides/plugins/plugins/services/index.md +++ b/guides/plugins/plugins/services/index.md @@ -6,8 +6,8 @@ nav: # Services -This section explains how to register, customize and extend services within your plugin: +This section covers the service layer of plugin development. Services are where reusable plugin logic lives, dependency injection wires services together, and service decoration lets plugins change existing Shopware behavior. -* [Dependency Injection](./dependency-injection.md) -* [Add Custom Service](./add-custom-service.md) -* [Adjusting a Service](./adjusting-service.md) +* Register reusable plugin logic as a service: [Add Custom Service](./add-custom-service.md) +* Inject Shopware or plugin services into another service: [Dependency Injection](./dependency-injection.md) +* Change behavior of an existing Shopware service: [Adjusting a Service](./adjusting-service.md) diff --git a/guides/plugins/themes/index.md b/guides/plugins/themes/index.md index 938330367d..392a59ba4a 100644 --- a/guides/plugins/themes/index.md +++ b/guides/plugins/themes/index.md @@ -11,7 +11,7 @@ Storefront Themes let you customize the visual appearance of the Shopware [Store Unlike regular plugins, themes do not contain backend logic. Their purpose is purely storefront presentation, and they are managed per sales channel through the Theme Manager. -Shopware comes with a default theme built on top of Bootstrap 5. Everything you can do with Bootstrap, you can do with the Shopware Storefront. +Shopware comes with a default theme built on top of Bootstrap 5. Everything you can do with Bootstrap, you can do with the Shopware Storefront. For background on the Storefront frontend stack and Bootstrap foundation, see the [Storefront](../../../concepts/framework/architecture/storefront-concept.md) concept. ```text Extensions diff --git a/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md b/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md index 086e6b9d1d..216ade9892 100644 --- a/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md +++ b/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md @@ -15,6 +15,8 @@ The storefront theme is implemented as a skin on top of Bootstrap: Sometimes it is necessary to adjust SCSS variables if you want to change the look of the Storefront for example default variables like `$border-radius` which is defined by Bootstrap. This guide will show how you can override those SCSS variables. +For background on why the Storefront uses Bootstrap, see the [Storefront](../../../../concepts/framework/architecture/storefront-concept.md) concept. + ## Prerequisites All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](../create-a-theme.md) guide if you have not yet a working theme setup. diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index d8e81fd859..028524a68a 100644 --- a/products/tools/cli/index.md +++ b/products/tools/cli/index.md @@ -15,7 +15,9 @@ nav: - uploading and maintaining extensions in the Shopware Store - running CI/CD pipelines for Shopware-based solutions -Shopware CLI runs on macOS, Linux, and via Docker. For system-level requirements (PHP, DB, memory, etc.) see the [General Requirements](../../../guides/installation/system-requirements.md). Windows users should use WSL 2 or Docker. (See full [installation](installation.md) page for Windows details.) +For GitHub Actions, GitLab CI, and Docker examples, see [CI/CD and development environments](installation.md#cicd-and-development-environments). + +Shopware CLI runs on macOS, Linux, and via Docker. For system-level requirements (PHP, DB, memory, etc.) see the [System Requirements](../../../guides/installation/system-requirements.md). Windows users should use WSL 2 or Docker. (See [Installation Options](installation.md) page for Windows details.) ## Quickstart