Quality Guidelines for Plugins in the Shopware Community Store

Version

5.5.0 or newer

Table of contents

Plugins - Quality Guidelines for Community Store plugins

Changelog

12/05/20: Add Plugin Checklist for your Quality assurance.
22/04/20: SW6: Menu entries in the main menu of the administration are not allowed anymore because og Look & Feel. 
07/04/20: Cache clearing update
25/02/20: Codereview: Added new Blocker rule "Codereview for Shopware 6 Plugins: Plugin-Icon (40x40/png) for Plugin-Manager will be checked."
06/02/20: Codereview: Added new Blocker rule "Unauthorized file formats or folders will be blocked soon."
21/01/20: Added informations about the SW6 configuration we use: "First sighting of your SW6 Shopware store plugin"
10/01/20: Register your cookie in the new Cookie Consent Manager (SW6)
18/12/19: Important notice: Please check your code review. As of Q1/2020 we will automatically reject all plugins which contain errors with type "Blocker".
12/12/19: Register your cookie in the new Cookie Consent Manager
12/12/19: Changes to "First sighting of your Shopware store plugin".
07/11/19: Plugins are not allowed to extend the Plugin Manager.
05/11/19: Launch of our automatic code reviews with PhpStan and SonarQube on GitHub.
31/10/19: New support for testing, validating and releasing a Community Store plugin.
23/10/19: Clear only necessary caches when installing/uninstalling a plugin.

Checklist for plugin-testing

Please note that this checklist may be edited at any time. Be sure you are using the most recent testing checklist from Shopware, and not from any other provider. We also ask that you pay attention to every single point in the Quality Guide for store plugins – these will be reviewed by us in order to release your plugin.

Every plugin:

  1. If using external fonts (e.g. from Google Fonts) or external services, the plugin store description must contain this information, and please be aware that you might have to edit your "data protection information". This info could be otherwise placed as a tooltip near to the font settings of the plugin configuration.
  2. Plugin store description: Mandatory number of characters set in short and long description. No blank spaces as filler are allowed (EN/DE).
  3. Plugin store description: Does the description makes sense, and does it include step-by-step instructions on how to use and test your plugin?
  4. Plugin store description: Did you include enough screenshots showing the plugin in action in the storefront AND administration (please add a screenshot of the plugin in the Plugin Manager settings).
  5. We want to improve the quality in the Shopware Community Store and offer as many different plugins as possible. We check for a functional comparison with other plugins already available in the Shopware Community Store: If there is a plugin with exact the same function, the plugin may be rejected.
  6. We pay attention to the automatic code review and look for security issues.
  7. Cookie check in the browser console: If the plugin sets cookies in any way in the checkout, these cookies must be registered to the cookie configuration box in the frontend.
  8. Every external link in the adminstration or storefront must be marked as rel="noopener" AND target="_blank".
  9. We check for styling errors on every viewport.
  10. We check the complete functionality of the plugin.

Theme plugins:

  1. There must be a preview image available in the Theme Manager.
  2. Links must include a title-tag and images must have an alt-tag.
  3. Use Google's Structured Data Testing Tool to check the homepage, categories, and various product detail pages (incl. products with no review, 1 review, 9 reviews with various ratings, out of stock products, or any other kind of product configuration). We check for any new bugs.
  4. We do a Lighthouse Audit to check the performance and quality of your frontend plugin. There should not be any drastic change in performance or accessibility values when activating the plugin.

Shopping Worlds/Storytelling elements:

  1. Links must include a title-tag and images must have an alt-tag.
  2. We test the frontend and the checkout with the Debug Console – we also pay attention to new JavaScript errors.
  3. Use Google's Structured Data Testing Tool to check the homepage, categories, and various product detail pages (incl. products with no review, 1 review, 9 reviews with various ratings, out of stock products, or any other kind of product configuration). We check for any new bugs.
  4. We do a Lighthouse Audit to check the performance and quality of your frontend plugin. There should not be any drastic change in performance or accessibility values when activating the plugin.

Frontend plugins:

  1. Links must include a title-tag and images must have an alt-tag.
  2. If you create custom controller URLs in the sales channel, please note that we check for SEO and a valid canonical-tag: https://docs.shopware.com/en/plugin-standard-for-community-store#plugin-pages-with-their-own-url-must-appear-in-the-sitemap-xml.
  3. Use Google's Structured Data Testing Tool to check the homepage, categories, and various product detail pages (incl. products with no review, 1 review, 9 reviews with various ratings, out of stock products, or any other kind of product configuration). We check for any new bugs.
  4. We check for new errors throughout the entire storefront using the Browser Debug Console. We also pay attention to new JavaScript errors.
  5. We do a Lighthouse Audit to check the performance and quality of your frontend plugin. There should not be any drastic change in performance or accessibility values when activating the plugin.

Backend plugins

  1. We check the complete functionality of the plugin and test wherever the administration is impacted by the plugin.

API/Payment plugins

  1. We check for an API test button. Apart from that, you can validate the required credentials while saving them in the plugin settings. In this case, a status message must be displayed in the backend and Shopware log.
  2. The functionality of a plugin will be tested together with the plugin developer in a live session!

Quality Guidelines

Helpful tools for plugin developers

Checklist for plugin testing

plugin.xml - Plugin metadata

SW5: All plugins must contain the following metadata:


<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../engine/Shopware/Components/Plugin/schema/plugin.xsd">
<label>My Pluginname</label>
<label lang="de">Name of the plugin (German translation)</label>
<version>1.0.0</version>
<copyright>plugin supplier</copyright>
<license>license set in the account. e.g. MIT, proprietary, etc.</license>
<link>optional</link>
<author>Author of the plugin</author>
<compatibility minVersion="5.2.0" />
<changelog version="1.0.0">
   <changes>
        <![CDATA[
        First release Shopware Community Store
        ]]>
   </changes>
   <changes lang="de">
        <![CDATA[
        Erstveröffentlichung Shopware Community Store
        ]]>
   </changes>
</changelog>
<description>
   <![CDATA[
   <b>My Plugin</b>
   <p>CSS,INLINE-Styles,BASE64-IMAGES OR SCRIPTS NOT ALLOWED! Describes Plugin and contains a Link to manual/description in the community-store: <a href="https://store.shopware.com/search?sSearch=TechnicalPluginName">Plugin Manual</a></p>
   ]]>
</description>
<description lang="de">
   <![CDATA[
   <b>Mein Plugin</b>
   <p>CSS,INLINE-Styles,BASE64-IMAGES NICHT ERLAUBT! Beschreibt Plugin und enthält einen Link zur Anleitung/Beschreibung im Community Store: <a href="https://store.shopware.com/search?sSearch=TechnischerPluginName">Plugin Anleitung</a></p>
   ]]>
</description>
</plugin>

Note: The changelog must contain a minimum of 20 characters. Please note that the minVersion must be the same version as you have stored for the plugin in your account.

SW6: no constraints

plugin.xml - Plugin dependencies

SW5: If your plugin requires other plugins to run properly, you have to check that these plugins are installed. For example: If your plugin only works with an activated base plugin, you have to check the installation of the base plugin in the plugin.xml:


    <requiredPlugins>
        <requiredPlugin pluginName="BasePlugin" minVersion="1.0.0" />
    </requiredPlugin>     

SW6: no constraints

Translations in the XML & TPL files

SW5: If your plugin is available in more than one language (e.g. English and German), these can be defined using the option "My plugin is translated into the following languages" (located in the “Description & images” section of your plugin management). The translations / text snippets must be maintained in the respective XML and TPL files.
SW6: If your plugin is available in more than one language (e.g. English and German), these can be defined using the option "My plugin is translated into the following languages" (located in the “Description & images” section of your plugin management). The translations / text snippets must be maintained in the json files.

Valid plugin favicon for the Shopware backend

SW5: You have to upload a valid favicon (16 x 16 px) for the plugin. This favicon will make it easier to identify your plugin in the Plugin Manager module in the backend.
SW6: You have to upload a valid favicon (png / 40 x 40 px) for the plugin. This favicon will make it easier to identify your plugin in the Plugin Manager module in the backend.

Error messages must be entered in the plugin log

SW5: Error/informational messages can only be recorded in the plugin-log of Shopware's log folder ( /var/log/ ). The service "pluginlogger" from the DI container has to be used for this. As of Shopware 5.6, you can also create your own plugin-specific logger. Never write plugin exceptions into the Shopware core.log or outside the Shopware System-Log folder. This ensures that the log file can never be accessed via URL.
Error messages had to be written into the original plugin.log of shopware.
SW6: Error/informational messages can only be recorded in the plugin-log of Shopware's log folder ( /var/log/ ). You have to develop you own logging-service / plugin-specific logger. Never write plugin exceptions into the Shopware-Default-log or outside the Shopware System-Log folder. This ensures that the log file can never be accessed via URL

Changes to the database and data records must not be removed with "Reinstall"

SW5: If a user clicks on "Reinstall", be sure that any stored data remains intact.
SW6: no constraints

With "Install/Uninstall" the user must decide whether the data/tables are to be deleted or not

SW5: When clicking on the "Install / Uninstall" option in the Plugin Manager, the user must be presented with the options "completely delete" or "keep the plugin data, text snippets and table adjustments".
SW6: no constraints

Standard prefix for your own database tables

SW5: The prefix for your unique database table is s_plugin_. If you use your own tables, the structure should be as follows: s_plugin_my_plugin_name
SW6: no constraints

Email templates

SW5: Plugin email templates must be stored in the folder "User emails". All email templates must be deleted after the plugin is uninstalled.
SW6: no constraints

Using attributes

SW5: Attributes created by the plugin may not be deleted via the free text administration in the backend.
SW6: no constraints

Test button for access data

If your plugin contains access data for other interfaces, a test button must be provided. In this way, the shop operator immediately receives a notification from the interface API as to whether the access data stored in the plugin is correct or not. The result must be written into the plugin-log.
Apart from that, you can validate the required credentials while saving them in the plugin settings. In this case, a status message must be displayed in the backend and Shopware log.

Untrusted content should not be included

See Untrusted content should not be included in SonarQube Rules.

It is not allowed to extend the Plugin Manager

The Plugin Manager must not be extended or overwritten.

Reloading of files not allowed

Plugins may not load other files during and after the installation in the Plugin Manager.

Plugin pages with their own URL must appear in the sitemap.xml

If the plugin creates its own pages that are set to "index,follow" and the URLs are accessible via the frontend, then these "plugin URLs" must also appear in the sitemap.xml. In addition, these pages must include their own "Meta description" and "Title tag", which can be entered individually via the backend or as a text snippet.

SW5:Code snippets for Shopware plugins.

SW6: in planning.

We expect that every cookie set from the store-URL is registered in our Cookie Consent Manager. We differentiate between "Technically required", "Comfort functions" and "Statistics & Tracking". All cookies have to appear in cookie configuration box in the frontend.

SW5:Registering cookies in the Cookie Consent Manager

SW6:Registering cookies in the Cookie Consent Manager for Shopware 6

Code review - Errors

"The required composer.json file was not found."

Cause: Error in composer.json
One possible cause is that the technical plugin name from the Community Store or account does not match the technical name entered in composer.json or the plugin is incorrectly zipped.
The technical plugin name had to be stored in the last part of the composer.json: composore.json > extra > shopware-plugin-class. So take a look at the bootstrap class. Most of the error were caused by the wrong technical name. For example "Swag\\MyPlugin\\SwagMyPluginSW6" instead of "Swag\\MyPlugin\\SwagMyPlugin".

Here is an example of a valid composer.json.
See "Plugin-Base Class" for more information. 

"No bootstrapping file found. Expecting bootstrapping in..."

The bootstrap cannot be found. Either the folder structure in the ZIP file is incorrect or there is a typo/case sensitive error in the plugin source (e.g. in the technical name).

"Warning: ExtJS was detected in your plugin."

(SW5 related)
The plugin manufacturer needs an SDK license for a commercial plugin which uses ExtJS. For more information, please write an email to plugin-manufacturer@shopware.com.
See Shopware 5 SDK Licence for more information.

"Class Shopware\Storefront\* not found."

Missing requirements in the composer.json (e.g. "require": {"shopware/frontend": "*"},)
See "Shopware Plugin Development: Plugin Meta Information - Explanation of the properties" for more information.

Be sure you set cookies as secure. Don`t forget to register your to Cookie to the Coookie Consent Manager.

"Call to static method jsonEncode() on an unknown class......"

Shopware always uses json_Encode exclusively - there is no other fallback.

"Make sure that using this pseudorandom number generator is safe here"

"Make sure this cross-domain message is being sent to the intended domain."

"The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run update to update them."

The composer.lock in the plugin archive has to be deleted.

"Class Shopware\Core\System\Snippet\Files\SnippetFileInterface not found and could not be autoloaded."

In the Shopware 6 Early Access version, the mentioned class did not exist, therefore, the code review failed.
The reason for the problem is the following specification in the composer.json:


"require": {
    "shopware/core": "*",
    "shopware/storefront": "*"
},

Composer resolves this to "Whatever is the latest from these repositories" and then installs the Early Access version instead of the current Release Candidate. This happens because an EA is not known by composer as a stability level (like stable or RC) and is therefore ultimately considered "stable".
The solution is to amend the requirement as follows:


"require": {
    "shopware/core": "^6.1",
    "shopware/storefront": "^6.1"
},
"minimum-stability": "RC"

This ensures that at least version Shopware 6.1 is installed, even if it is a Release Candidate. It will be preferred as soon as the final 6.1 is released.

Unauthorized file formats or folders detected in the plugin. Please remove the following files/folders:

Not allowed folders and files:


.gitignore, .DS_Store, Thumbs.db, .git, __MACOSX, .zip, .tar, .tar.gz, .phar

The way we test plugins

It's always a good idea to review the process of how we conduct tests prior to submitting your plugin for review - this ensures the quickest way for your plugins to be published.

First sighting of the plugin

Start Testing:: If successfull we test the plugin once again with the most current Shopware version. The Shopware installation is located in a subfolder and has a language subshop with a virtual URL as well as an independent subsshop with its own URL, which is also located in a subfolder.
The plugin must not produce any error messages - neither in the backend nor in the frontend.

SW5: The plugin is tested with PHP 7.2, Shopware 5.6.2 CE Version (including the activated and current versions of the Cookie Consent Tool for Shopware > 5.2.11), the Shopware security plugin and with the current Shopware version without the security plugin.

SW6: The plugin is tested with PHP 7.4, the latest official Shopware 6 CE Version.
See a href="https://docs.shopware.com/en/plugin-standard-for-community-store#checklist-for-plugin-testing" title="Official Checklist for Shopware Community Store Plugins" > for final Tests.

"Clear only the necessary caches when installing or uninstalling a plugin."

SW5:

Do not empty the template-/http-Cache or recompile the theme when installing the plugin. Also please consider which caches actually need to be cleared for your plugin to work, since regenerating caches may cause a high load on the server. Clear only the necessary caches when the activate-method is called.

SW6: no constraints

Frontend plugins

  • Use Google's Structured Data Testing Tool to check if there are any new bugs. There must be no new warnings/errors. We test categories and product pages (available products, unavailable products, available products plus reviews, and products to be released in future). Testing Tool: Google Structured Data Testing Tool
  • We check the frontend and the checkout with the Debug Console - we also pay attention to new JavaScript errors. If more errors appear in the debug console than before the installation of the plugin, we will reject the plugin.
  • We do an Lighthouse Audit to check the perfomance and quality of your frontend plugin. If there are drastically worse performance and accessability values than before activating the plugin, we will reject the plugin. Google Lighthouse: Run Lighthouse Audit

Plugin Manager

  • The Debug Console controls the reinstallation, uninstallation, installation and deletion of the plugin. No 400 errors or exceptions are allowed to appear.
  • If the plugin requires special PHP options, these must be queried during installation. If the query is negative, a growl message must appear in the backend.

SW5: After deleting the plugin, we chek whether the plugin has removed all database adjustments/entries.

SW6: no constraints

Shopping Worlds / Shopping Experiences

  • Shopping Worlds elements must include an element icon.
  • If the plugin is deleted, Shopping Worlds should continue to work flawlessly in the frontend.

Payment

  • We check if the "pluginlogger" service is used for the debug/error.log and that logs are written in the directory /var/log/. Log files must use this folder in every circumstance. Another solution is to store them into the database.

Plugins accessing external API services

  • A test button for optional API access data must be available. If the API data is incorrect, an entry must appear in the plugin log file in the Shopware folder /var/log/ respectively in the database.
  • Apart from that, you can validate the required credentials while saving them in the plugin settings. In this case, a status message must be displayed in the backend and Shopware log.

Template tests

  • Tests with Google's Structured Data Testing Tool: We test categories and product pages (available products, unavailable products, available products plus reviews, and products to be released in future).. Testing tools: Google Structured Data Testing Tool and Google Lighthouse

Description entered in the Shopware Account

  • The plugin's short description must have at least 150 characters.
  • The plugin description must contain at least 200 characters and should clearly represent the plugin's functions in detail.
  • Include several screenshots from the frontend and backend. They must show the plugin "in action" and show its configuration options and how to use the plugin.
  • Be sure that the plugin is assigned to the appropriate categories.
  • If you provide a demo shop, the link must be valid (the URL cannot contain http:or https:).
  • The description must be a 1:1 translation.
  • Your plugin manufacturer profile must contain accurate English and German descriptions as well as a manufacturer logo.

Automated tests

There are Cypress tests for Shopware 5 on GitHub. The project is driven by the Friends of Shopware group. You can contribute at any time: Cypress Tests for Shopware 5, Developer Documentation Cypress Tests for Shopware 6 and Cypress Tests for Shopware 6 at Github

Automatic code reviews with PhpStan and SonarQube

Our most current code review configurations that we use when uploading pluigns via the Shopware Acccount can be found on GitHub.

Shopware Account

Note: iframes, external scripts or tracking pixels are not allowed in the source code of the descriptions, profiles, and instructions. Custom styles may not overwrite the original Shopware styles. External sources must be included via https.

Plugin master data

SW5: Please enter the valid license you set in your shopware account. You have to identify this license in the plugin.xml as well.

SW6: no constraints - will be automaticly checked thorugh the basic coderview

Description & images

Short description: Min. 150 - max. 185 characters.

  • Tip: Use the short description wisely as the text will be used to tease your plugin in the overview along with the "Customers also bought" and "Customers also viewed" recommendations. The short description is also published as the meta-description. This description should be a minimum of 155 characters long and unique.

Description: Min. 200 characters.

Inline styles will be stripped.The following HTML tags are allowed:


<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
  • Tip: When it comes to increasing your plugin sales, it's important that potential customers feel completely informed about your products and services. To this end, you should provide a description that is meaningful, detailed and easy to understand - when possible, even make it understandable for people with very little technical knowledge. Explain step by step how your plugin works and how to use it to achieve the desired result. Of course, your plugin description should be accompanied by clean HTML source code.
  • Tip: Video content increases awareness, trust, and has proven to convert potential customers better than other content types. Help your customers better understand your plugin or service with explainer videos, product demos, tutorials, etc. You can embed max. 2 YouTube videos in your plugin description.

In addition, you should include descriptive images that represent the plugin's functionality. Show the plugin "in action" in both the frontend and backend.

Note: You are no longer able to advertise your Shopware certificates within the plugin description, in your plugin images, or in your manufacturer profile. The manufacturer/partner certificates are dynamically loaded at the end of each plugin description and published by us.

Availability in the Community Store

A plugin is to be released in both stores (German and International), the content must be accurately translated 1:1 from/to German/English.​​​

Plugin manufacturer profile

A complete manufacturer profile in German and English is mandatory. The English or German text must be translated 1:1. You can find the manufacturer profile in your account under Shopware Account > Plugin Administration > Plugin manufacturer profile.

Note on Shopware Technology Partner contract for interfaces

You have now read the complete list of requirements for developing and releasing plugins in the Shopware Community Store.

If your plugin is a software extension/interface with downstream costs, transaction fees, or service fees for the customer, we need to complete a technology partner agreement in order activate your plugins.

If you have any questions regarding the technology partner agreement, please contact our sales team by writing an email to sales@shopware.com or calling +44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany).

Shopware 5.0 SDK License

The Shopware 5 backend is completely based on Ext JS framework by Sencha (www.sencha.com). If you are developing Shopware 5 plugins which build upon or alter the Shopware/ExtJS layer and wish to offer them with a proprietary license (extensions that are not licensed under the GNU Affero General Public License version 3 or a compatible license), you require a Shopware SDK license.

Thanks to an OEM agreement with Sencha, Shopware is able to offer this license on a per developer basis, allowing the license holder to make use of this framework for their own extensions.

When do I need a SW5 SDK-License?

  1. Plugin will be sold and uses extJS

When do I NOT need a SW5 SDK-License?

  1. Plugin will be sold and uses no extJS
  2. Plugin is for free and uses extJS
  3. Plugin is for free and uses no extJS

If you need a license, please write an email to plugin-manufacturer@shopware.com.

Was this article helpful?