Composer patches

Shopware 6 ships with a powerful built-in plugin system, which helps you to extend its core functionalities and build themes upon. While in some urgent cases one maybe has to patch core files.

Do not touch core files

The first and very important thing to keep in mind is: Do not touch core files at all and commit these changes in your customers project repository. Once you have done that, upgrading software will become very hard at all. To ensure maintenance possibilities, there are other options when it comes to patching Composer projects.

Production template

The so called production template helps you to build customers projects. With the production template you do have the possibility to only require the specific parts of the platform you really want to have inside your project. The process is straight forward: Clone the repository, adjust it to your needs, require other dependencies with Composer and add your CI/CD configuration. Dependencies can be other plugins/themes or other Composer packages. Custom themes and plugins can also be committed inside the specific custom directory.

Patching Shopware 6

A clean and maintainable solution to patch core functionalities is to require another composer dependency to your project. This is where cweagans/composer-patches comes in place.

"require": {
    "php": "~7.2",
    "composer\/package-versions-deprecated": "1.8.0",
    "shopware\/core": "~v6.3.0",
    "shopware\/administration": "~v6.3.0",
    "shopware\/storefront": "~v6.3.0",
    "shopware\/elasticsearch": "~v6.3.0",
    "shopware\/recovery": "~v6.3.0",
    "cweagans\/composer-patches": "^1.5.0"
}

Once you have required this packages, you do have to implement adjustments inside the composer.jsons extra object. In our scenario we do want to adjust a file from the shopware/storefront repository. This object gives you the opportunity to name and link to the specific patched file (inside your repository).

"extra": {
    "patches": {
        "shopware/storefront": {
            "Composer patches test": "custom/patches/mypatch.patch"
        }
    }
}

The custom directory is a good starting point for that. There are other configuration options available - e.g. implementing the patch as Git repository and requiring the patch instead of adding a static file to your project. More information regarding this topic can be found here.

Creating the patch file

Let's say we want to adjust a Storefront template. The first thing we need to do is to make another change to the composer.json as we want the sources to be preferred.

"config": {
    "optimize-autoloader": true,
    "preferred-install": "source"
},

Once you have adjusted the e.g. base.html.twig, you are able to perform a diff on that repository.

git diff base.html.twig > mypatch.patch

Running composer install afterwards applies the patch to your project. The big advantage of having this patching method applied is, that you do have all patches in one place & you do exactly know which file you've touched.