8 minutes to read

No more Zips: The improved Shopware installer

No more Zips: The improved Shopware installer

ETA: 6.5 final, this will not be available with 6.5 RC

Rolling out this change is not planned for the RC, but 6.5 RC will already use the new structure. That means the RC will not be available as ZIP nor with the new installer, but only on GitHub. With 6.5 final, the installer will be available.

The improved Shopware installer

One important thing up-front: If you want to start a new project using Shopware 6.5 or later, this article contains nothing you need to know to do so.

At the end you will find actions you might need to take in case you are:

  • A developer of plugin-system based apps

  • Starting a new Shopware 6.5 project

  • Upgrading an existing project using the Installer/Updater

  • Upgrading an existing project using composer

With that said, here is how the downloadable installer changed with Shopware 6.5, and why that is a good and necessary change.

Shopware traditionally is available as a ZIP-archive, downloadable via the Shopware Website. This is mainly targeted towards merchants and agencies which did not yet switch to using version control (git) and dependency control (composer).

shopware 6-5 installer 01 welcome

What will be changed

In case you are using a composer-based installation method, nothing will change. These changes only regard what you get from downloading Shopware via the Shopware website.

After the Release of Shopware 6.5, which is unrealeased as of the writing of this article, it is still possible to "download Shopware". And it is still possible to install or update Shopware with the content of said download.

What changes is the content. Prior to Shopware 6.5 the ZIP-archive contained all files and dependencies required to either install or update Shopware on a server prepared for that task.

With the new method, you download a single PHP file that, when run on a system prepared for Shopware, will download and install or update Shopware for you. This behavior is heavily inspired by how the installer of the open-source Content Management System Contao works. More details are explained at the end of this article, in case you are not familiar with Contao.

Why things change

The main reason behind the new, combined installer and updater is: Better compatibility between plugin-system based apps.

Before Shopware 6.5, every plugin-system based app is required to include all dependencies in the download itself. This leads to multiple copies of the same dependency, sometimes with different version, so app developers need to hide their dependencies and make them appear as custom code (PHP scoping).

In an ideal world, composer would handle all dependencies of a project, regardless of whether they are defined in a plugin-system based app or inside Shopware. Composer can then check for conflicting dependencies on install, and report them to the user. Without composer, conflicting dependencies will produce errors in the shop while it es running.

Another, less important reason is the way we need to build the update-ZIP at Shopware: It consists of the files that changed between versions. Creating these archives is a process that involves a fair share of manual work, which makes it very labour intensive to keep things safe for the user.

How things will change

Again, if you are using a composer-based installation method, nothing will change. These changes only regard what you get from downloading Shopware via the Shopware website. Here is the more technical explanation of what exactly you get as a download and what it does on your system.

As already mentioned, with the release of 6.5 instead of a ZIP-file you download a PHP-file. This file is a phar-Archive containing a symfony-based application, also bundling composer.

After saving this file to your webserver and pointing your browser to it, the application will check if it was uploaded to a public Shopware folder, in which case it will display the update process. In case the application was uploaded somewhere fresh, the installation process is displayed.

Both installer and updater consist of a multi-step wizard, checking and asking for some needed information. When everything is set, the real magic begins: The application runs itself and at some point composer in the background, displaying the results in a live terminal to the user.

So instead of just uploading files to your webserver and hoping for the best, the new installer and updater will execute a controlled composer installation or update, without the need to use the command line or having composer installed.

What you need to do

As a developer of plugin-system based apps

You do not have to use the new method of letting Shopware take care of your dependencies. But please do so, unless you have a good reason not to. It’s very straightforward.

In your plugin-system based app, implement executeComposerCommands() in your plugin base class and let it return true. From that point on, Shopware will handle your dependencies. Example:

code example 1

Regarding your dependencies, please make sure to include the absolut minimum version you need, to maximize compatability. You can also include a minimal and preferred version of a dependency in your composer.json using a version range with or like so:

"some/dependency": "^1.0 || ^1.2"

This example would install the newer version of the dependency unless another plugin-system based app requires the older one. More details on that can be found in the composer documentation.

Starting a new project

In case you plan to start a new project with Shopware 6.5 or later, you don't need to do anything other than following the official installation guide, but we encourage you to use the symfony flex approach whenever possible.

Upgrading an existing project using the Installer/Updater

Upgrading to Shopware 6.5 is as easy as uploading the Installer/Updater to your public folder and navigating your browser to it. Of course after creating at least a backup and ideally testing on a clone of your shop, not your live shop.

Also, did you know you are able to deactivate the update notification in the administration? For this, create or edit the file config/packages/shopware.yaml and add or alter the following entry (keep the indentation):

code example 2

Upgrading an existing project using composer

The production template changes a lot with the release of Shopware 6.5, meaning there is some manual work needed to upgrade existing projects using composer. Migrate from Production Template to symfony flex. This will enable Shopware to manage all dependencies of plugin-system based apps for you.


Never miss out - get all the latest news sent straight to your inbox.

To the newsletter manager