I am not sure, if this article should be in the Shopware 6 basics or Tips, tricks and how to’s, because quite frankly, it is both. I consider the practices, that I will talk about, to be something so basic, that anyone, who develops plugins for Shopware 6 should adhere to them. On the other hand, they are just my tips for you to make your developments more sustainable and future proof. My experience at the moment comes from around 20 Shopware 6 plugins of various sizes and purposes, so I feel confident enough to present it to you as guidelines. I have made some mistakes at the beginning and had to fix them later on, so maybe you can learn from them now and it will save you some headaches later.

Name your plugins properly

I am proposing the following naming convention for Shopware 6 plugins in composer.json:

• Plugins: vendor/plugin-some-name
• Themes: vendor/theme-some-name

The vendor is your name or the name of your company. Then there is either a word ‘plugin’ or ‘theme’, which allows to easily distinguish between them and then finally the name of your plugin.

I consider naming everything in english, including plugins, to be the best practice, even if your plugin does not have english language version. It is also an unwritten standard, that plugin names do not contain any special characters and begin with an upper case letter. Basically use the so called upper camel case (or Pascal case), like this: MyAwesomePlugin. Also please make sure, that the directory, in which your plugin resides, is named the same as the plugin itself.

Shopware saves this value from composer.json file to the table named plugin and column named composer_name. Well named plugins are easier to find and sort. One good use case for this is, if you encounter a strange error and you are not sure, what causes it. To debug it, you want to disable all or some of your plugins to see, if something you did causes the problem. You can find out more about it in the article about batch plugin activation and deactivation.

Make sure, that whatever your plugin does, it does it only if it is activated

The best way to ensure this, is to follow one golden rule:

All your code should be within your plugin’s directory.

This is very important, even if you have created your custom plugin just for one particular store. You need to think about situations, when your plugin is deactivated for some reason. This can be for example for debugging purposes, when you find out, that it does not work well after Shopware update or it simply becomes not necessary anymore. And even if that is improbable, it is still a good practice to keep your plugin’s logic separated. If someone else needs to edit your code, he will expect it to be within your plugin’s directory.

There is more to this. Nothing from outside your plugin should be dependent on it. If it absolutely has to be, then mark it in composer.json file of that dependent plugin, so that Shopware knows about it. Then it does not allow deactivating your plugin, if another plugin, that is dependent on it, is active. Example of composer.json:

Alternatively, add a conditionality in the problematic parts, that expect your plugin to be active, so that it applies only in case your plugin is activated, or create a fallback for the case, that your plugin is not active. Typical example of this are the themes. It is tempting to edit your theme’s template directly to output custom stuff from your plugin, but it is wrong and will lead to errors. Safer way is to just add an empty block to your theme’s template and the override this block from within your plugin.

For example this would be in your theme’s template named some-template.html.twig:

And this would be in a template in your plugin’s directory:

If your plugin is turned off, nothing happens. And that is exactly, what should happen in that case.

Another alternative would be to add a condition on a presence of some variable, that is only available, if your plugin is active. Example, that displays something only if somePluginVariable is present:

Ensure your plugin’s portability

This means, that your plugin should be able to be installed on any instance of Shopware 6 without the need to do any manual adjustments to the store itself, the code, database, files or anything else. You should be able to just copy it into the custom/plugins directory like a non-programmer, install and activate it. If there is some individual configuration needed, then it should be done just using your plugin’s configuration, that is accessible from the Plugin manager in Shopware 6 Administration. Therefore all of the installation procedures must already be implemented in your plugin and proceed automatically, when you install and activate your plugin.

This is important for many reasons. You might want to use your plugin on a different store. Or you have a development server and a production server. In both cases, you don’t want to have to do any additional actions. So here is a small checklist of things, you should have covered:

• When you need a new table in the database, create a migration for it, so that it gets created automatically
• When you need to output translated text in your plugin, create snippet files with texts inside your plugin, so that they are automatically available on any place, where you install your plugin
  • Do not use ifs on language in the code to get the translated texts
  • Do not create the text snippets in Administration

Create documentation for your plugins

I am not talking about the documentation for users right now, although that is important as well. I want to focus on the technical documentation and especially inline code comments.

It never ceases to surprise and amaze me, how many programmers just leave their code undocumented. And to be honest, I hate it and consider it a bad practice. My opinion is, that when you come to someone else’s code, you should be able to see on the first glance, what the author has tried to achieve here. It is a waste of valuable time, if you have to go through twenty or even more rows of unknown code and decipher it. Maybe you are a genius and in 10 seconds, you know exactly, what the code does, but most people are not. On the other hand, creating a comment above each logical block (or at least a method), describing, what is it supposed to do, that costs you as a developer those measly 10 seconds. But by doing this, you save your colleagues (or your future self) valuable minutes or even hours, that they would otherwise have to spend by studying your code line by line, damning you in the process. So please comment your code, even if it seems obvious to you.

Additional information

Thank you for reading my take on the plugin development best practices. Any constructive feedback is welcome – just use the comments below, if you want to contribute.

For more information and technical documentation, regarding the Shopware 6 plugin development, you can always go to the official guides. I have also created a Shopware 6 plugin development tutorial, containing a whole example plugin for you to download, so you might want to check it out as well. 😉