Building a custom plugin in Shopware has always been about more than just adding routes or controllers. At the heart of every reliable extension lies a solid configuration strategy. With Shopware 6.7, the platform leans even harder into modern Symfony conventions, making your plugin’s configuration both more powerful and easier to maintain. This guide walks you through the practical steps to configure your Shopware 6.7+ plugin correctly, covering manifest files, service definitions, environment variables, and administration settings—without getting lost in theoretical detours.

The Foundation: config.json and Plugin Metadata

Every plugin starts with config.json. In 6.7, this file remains the entry point for Shopware’s installer and updater. It declares your plugin’s name, vendor, version, compatibility, and dependencies. But beyond metadata, it signals to the framework how your plugin should behave during installation. Ensure your copy and skin paths are accurate, as 6.7 enforces stricter validation during the bin/console sw:plugin:new and sw:plugin:refresh commands. While this file doesn’t handle runtime configuration, a clean structure here prevents unexpected deployment failures later. Pay special attention to the upgradePath field—Shopware 6.7 validates it more rigorously to avoid silent migration breaks.

Service Configuration with Symfony’s Modern Approach

In earlier versions, developers often mixed XML and YAML for dependency injection. Shopware 6.7 strongly favors services.yaml for all new plugins. Place it in your plugin’s root or src/Config directory. Use tagged services to integrate with Shopware’s event system or command bus. For example:

services:
  my_plugin.service.config_reader:
    class: Vendor\Plugin\Service\ConfigReader
    arguments:
      - '%shopware.plugin.%PLUGIN_NAME%.config%'
    tags: ['kernel.event_subscriber']

Notice the parameter injection. Shopware 6.7 passes plugin-specific parameters through the framework automatically, so avoid hardcoding paths or settings directly in your services. Instead, delegate values to configuration layers that can be overridden later. Remember that 6.7 runs on Symfony 7, which enforces tighter container rules. Services should remain private by default, and you should only tag them when they interact with the framework’s lifecycle. Public services are now strictly discouraged unless absolutely necessary for legacy bridge code.

Environment Variables and Runtime Parameters

One of the biggest shifts in 6.7 is how plugins should handle sensitive or dynamic data. Never store API keys, URLs, or toggle flags directly in PHP files. Use environment variables combined with Symfony’s native %env()% syntax:

parameters:
  shopware.plugin.my_plugin.api_url: '%env(string:MY_PLUGIN_API_URL)%'
  shopware.plugin.my_plugin.enabled: '%env(bool:MY_PLUGIN_ENABLED)%'

Your plugin can then access these via the container or by type-hinting them in your service constructor. This approach aligns with modern DevOps practices and keeps configurations environment-agnostic. Remember to document required .env keys for other developers. If you need fallback values, use the ? operator (e.g., '%env(default:https://example.com?:MY_PLUGIN_API_URL)%'), which is fully supported in Shopware 6.7’s container configuration and prevents fatal errors during fresh deployments.

Administration UI Configuration: config.xml

Most plugins need a user-facing settings page. In Shopware 6.7, config.xml defines the administration interface using a declarative schema. Create it in your plugin’s root directory and structure it with <entity>, <component>, and <setting> tags. Use sw-entity-singleton for configuration storage, which automatically handles versioning and rollback compatibility. Avoid mixing legacy form components unless necessary—Shopware 6.7 provides updated Vue-based components that integrate seamlessly with the platform’s state management system. Each setting should map to a configuration entity class, not a raw database row. This ensures your UI remains compatible with Shopware’s multi-store and permission models.

Configuration Resolution and Multi-Store Context

In Shopware 6.7+, configuration resolution follows a strict priority chain: environment variables → container parameters → administration settings → default fallbacks. When your plugin needs to read configuration, inject the parameter bag or use Shopware\Core\Framework\Adapter\Translation\Translator if localization is required. For multi-store setups, remember that Shopware automatically scopes plugin_config entries by saleschannel_id and storefront_id. If your plugin must apply globally across all channels, store values under the main store’s context or use platform-wide configuration entities explicitly marked with global="true" in your schema definition.

Debugging and Validation

Configuration issues are notoriously hard to spot until runtime. In Shopware 6.7, use bin/console debug:container shopware.plugin to verify that your parameters are correctly registered. Check the plugin_config table directly when UI changes don’t persist; mismatched entity names between config.xml and your PHP model is a common culprit. Always clear the cache (bin/console cache:warmup) after modifying service definitions or parameter files. Invalid YAML indentation or missing service tags will silently fail in production but throw strict errors locally during container compilation.

Common Pitfalls and Best Practices

Developers upgrading from 6.5 or 6.6 often run into configuration mismatches. First, never use absolute paths in your code—rely on $this->getPluginPath() or dependency injection. Second, skip manual plugin_config inserts; let the administration API handle writes. Third, validate your config.xml against Shopware’s official schema before deployment. Finally, remember that 6.7 enforces strict service visibility rules. Public services are discouraged unless absolutely necessary for legacy compatibility. Always document configuration points clearly and test across development, staging, and production environments.

Conclusion

Plugin configuration in Shopware 6.7 is no longer a guessing game. By embracing Symfony’s parameter container, leveraging environment variables, and following the platform’s updated administration schema, you can build extensions that are secure, maintainable, and future-proof. The framework handles the heavy lifting—your job is to structure your configuration cleanly and let Shopware manage the rest. Test your plugin across multiple environments, document every configuration point, and you’ll avoid the most common pitfalls that trip up even experienced developers. With 6.7’s stricter conventions, upfront discipline pays off in stability and performance down the line.