Shopware 6 - Tips, tricks and how to's

How to create config for your Shopware 6 plugin

What are the plugin configuration settings

In every application, including Shopware 6 plugins, you work with variables. They are the backbone of your program and you get them in various ways – from POST and GET requests to your controllers, from the URL, from the storefront, the admin forms etc. In those examples, the variables are passed to your code during runtime, based on the user’s action. That is absolutely OK, but there are some variables, that are practically constants in a sense, that your program needs them and their values might sometimes change, but not within one session.

Typical example would be a product import command, that connects to a remote data source. It needs the address and authentication data (username and password) to be able to connect, but you don’t want to fill them all the time, but also don’t want to put them into an URL for security reasons. You just want to have permanently stored variables, that the user of your plugin could edit and change, if necessary. And that is precisely what plugin configuration is for.

Where to find plugin configuration settings

Plugin configuration is available in the Shopware 6 Administration plugin list. Log in to the backend, the go to Settings – System – Plugins. Here you cas see the list of plugins, available in your store. When you click on the three dots, located in the last column of your plugin’s row, a menu will appear:

If the menu contains an item named “Config”, then this plugin is configurable. When you click on it, you will see configuration options for that particular plugin:

Please note, that if your Shopware 6 store contains multiple sales channels, you can set up config values separately for each of them. Just click on the uppermost select box and choose the sales channel, that you want to switch to. The screen then reloads and you will have the option to unlock and edit the values to be saved to that particular sales channel. If the ‘lock’ is left intact, then the sales channel will use the default values.

Also note, that some plugins can have their configuration (or a shortcut to it) in Admin – Settings – Plugins:

How to set up configuration settings

In order to set up the configuration page for your plugin, you need to add an XML file named config.xml to the src/Resources/config subdirectory of your Shopware 6 plugin. In this XML file, you will define the form elements, that you want to display to the user on the plugin configuration page. These elements represent the values, that you want to store to the plugin config.

Basic plugin config setup

Here is a rather long example of the config.xml file from a product import plugin, that I made some time a go:

As you see, the plugin config is organized into cards for better readability. In contrast to Magento 2 module config, in Shopware 6, this division is purely cosmetic and has no influence, on how you read your config variables. You give the name to your card in its sub-element called title. In backend, the title “Import script configuration” looks like this:

The rest is basically just form inputs for the various variables. Each of these inputs has a type, which decides, if a select, multi-select, text area etc. will be displayed. If you omit the type, the system assumes, that you just want to have a basic text input there. You can also specify “int” or “float”, which means, that the system will automatically create input, that will permit the user to put in just appropriate numerical values. Here you can see the complete list of basic types of inputs, used for plugin config in Shopware 6:

TypeDisplayed itemAdditional settings
boolOn/off switch
colorpickerColor selector
dateDate selector
datetimeDate and time selector
floatOne-line input for decimals
intOne-line input for integers
multi-selectMulti-select inputoptions, placeholder
passwordOne-line input for passwordplaceholder
single-selectSingle-select inputoptions, placeholder
textOne-line text inputcopyable, placeholder
textareaMulti-line text inputcopyable, placeholder
timeTime selector
urlOne-line input for URLcopyable, placeholder
Basic input types for Shopware 6 plugin config

As the table shows, the additional settings are possible to use for certain input types only. For selects, you can use, and in fact need to use, the options. Copyable means, that there will be a button, allowing a quick copy of the input contents. And placeholder is a text, that is displayed, when there is no value in the input.

Regardless of the input type, it must always have at least a name. This name is also the name of the variable, that you will read from the config during your plugin’s runtime. The name has to be unique per plugin! The label should also be present. As you can see on the screenshot above, its visual representation depends on the input type a bit, so in a switch, the label “Active” is inline, while in most other cases like “Output type”, it is above the input itself. Useful, but not mandatory is the helpText element, which looks like this:

There are also ‘disabled’ and ‘defaultValue’, which I think are quite self-explanatory. However, for some more complex cases, there are some caveats. Therefore, I have written a separate article on the topic of setting the defaults in plugin config. You might want to check it, especially if you want to use the Shopware 6 components in your plugin’s configuration page.

Using Shopware 6 components in plugin config

You can also use Shopware 6 components in plugin configuration. For the whole selection of them, please see the Shopware 6 official component library, but as an example, I would like to introduce one, that I found to be the most useful: the Entity multi-ID select. This component is a multi-select, that you probably already know from the backend. It allows you to specify any entity, available in your Shopware 6 installation, including your own entities. The items from this entity are then available for selecting and their IDs are saved to the administration as an array. The structure of the components is a bit different from the standard inputs, but as you see in the following example, not that much:

This config.xml translates to this Administration screen:

How to get plugin config variables

Inside Shopware 6, the plugin configuration variables are stored in the table, named system_config. In the column, named configuration_key, is the name of the variable, in format PluginName.config.VariableName. In the column, named configuration_value, is the actual value of the variable. This column is in JSON format and therefore it is very flexible and able to store multiple formats of data, including arrays. You could of course go here directly, if you want to read a variable from your plugin’s config. However, the standard and much more convenient way is to use the SystemConfigService class. So how do you use it? Quite simply, really. Just inject it to your class and then obtain the desired values by calling the get method like this:

Please note, that I have stored the whole path of the config variable to a constant. I consider this a good practice, as it reduces the chance of typos and helps consistency between classes, not mentioning the fact, that you just have to edit it on one place in the code, if the config value changes or gets replaced by another. In larger projects, I tend to have a special class just for config constants to keep things tidy and in one place.

If you want to get all available values for one particular plugin or you need to get the values from another plugin to use them in this one, you can use the getDomain method:

How to change plugin config values in runtime

Sometimes you might want to actually reverse the process and change the config value from runtime. It is as simple as getting it. Just use the set method:

There is also one option, that is not used often, but it is good to know it. If you have a Shopware 6 store with multiple sales channels, you are able to get and set the settings separately for each of them. Just use the sales channel ID as an additional parameter to get or set method and you will read or write the config value for that particular sales channel.