Shopware Apps

Shopware Apps are an alternative extension mechanism for Shopware 6. Unlike plugins, which are PHP code running inside the shop, apps follow a remote-extension model: the shop communicates with an external app server through webhooks and the Admin API, while the app itself ships only a manifest, templates, and sandboxed App Scripts. Apps were designed primarily for Shopware's Cloud offering, where installing custom PHP code is not possible, but they work in self-hosted installations as well.

All of our projects are self-hosted, so we build custom functionality as plugins, and we rarely deal with apps. Recently, though, a third-party app that one of our clients had been using for a while suddenly caused a bug that was difficult to debug.

One shop identity, three environments

When an app is installed, Shopware registers the shop with the app server. During this handshake the shop sends its shop ID and URL, and the app server stores the configuration for that shop under this ID. The shop ID is saved in the database.

As a good practice, we regularly update staging and local environments with anonymized production data to keep them in sync. As a result, the app was installed on local, staging, and production, and all three instances presented themselves to the app server with the same shop ID. The app vendor runs a central service that all installations connect to, and it stores the app settings for each shop on its side. It had no way to tell our environments apart. When we switched the app to test mode on staging, the change was stored for that shared shop ID, and production started running in test mode too. Since the setting looked correct on production, and nothing had been changed there, finding the root cause took us a while.

Shopware warns about this in its app registration documentation: when a database is replicated, two installations on different URLs end up associated with the same shop ID, which can lead to mixed-up or lost data on the app server. Shopware tries to detect such a situation by comparing the current APP_URL with the one used when the shop ID was generated, and asks how to resolve it (the app:shop-id:change command). In practice, this check is easy to miss or to resolve incorrectly.

Staging mode is only a partial fix

Shopware's answer to this problem is staging mode, available since Shopware 6.6.1.0. It is enabled with a single console command after importing the production database into a staging or local environment. Among other things, it deletes all apps with external connections and resets the shop ID, so the copy can no longer act on behalf of production. As a bonus, staging mode also disables email delivery, can rewrite sales channel domains, and shows a banner in the Storefront and the Administration, so it is always clear which environment you are working with. The behavior can be configured in config/packages/staging.yaml.

However, staging mode doesn't always solve the issue. Apps can store data in other tables, for example App Scripts in the script table. In one case, when an app was deactivated, the data it left behind caused some pages to crash. So staging mode reduces the risk, but it doesn't remove the need to understand what each installed app does.

Debugging a black box

Our first challenge was realizing we were dealing with an app at all. The Administration does not distinguish between apps and plugins: both are listed together under Extensions > My extensions, with no indication of the extension type. We only realized it was an app when we found a manifest.xml in its package.

The incident also showed a more general downside of apps. With a plugin, the code runs inside the shop: we can read it, step through it with a debugger, and reproduce issues locally. With an app like this one, the actual logic lives on a third-party app server. We can inspect the manifest, the App Scripts, and the requests the shop sends out, but not what happens on the other side, or which state the app server keeps for a given shop. When something goes wrong, the vendor's support might be the only way to find out what the app is actually doing.

Our verdict

We place Shopware Apps in Hold, and this assessment applies to self-hosted installations. Apps may be a reasonable solution for Shopware Cloud, where plugins are not an option. But as a mechanism available in every Shopware installation, they don't feel fully thought through: a single shop identity shared across copied environments, the same look as plugins in the Administration, and logic that can't be inspected all make problems hard to prevent and debug.