Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 30 ยท Quality and Production

Packaging, Deployment and Updates

Ship a Shopware plugin: composer.json metadata, zip builds, shopware-cli, deployment steps, update migrations and version compatibility, with a runnable constraint checker.

Writing a plugin is half the job. The other half is getting it onto a server, keeping it working after an update and letting other people install it. Shopware projects are deployed in two common ways: as a Composer-managed project where plugins are dependencies, and as a plugin zip uploaded to the Administration or published in the Shopware Store. Both start with a correct composer.json.

This lesson covers the plugin's metadata, building a zip, a deployment sequence that works for most projects, how update migrations run, and how to declare which Shopware versions you support. The real commands are read-only, because Shopware cannot run on this site. The runnable stand-ins check version constraints and validate a plugin's metadata, the two mistakes that most often break releases. If you have not met plugin versioning yet, read Plugin Structure and Lifecycle first.

The plugin's composer.json

Shopware identifies a plugin by its composer.json. Four things are essential: a package type, a class, the version and a Shopware requirement (read-only):

JSON
{
    "name": "swag/badge",
    "description": "Product badges for the storefront",
    "type": "shopware-platform-plugin",
    "version": "1.2.0",
    "license": "MIT",
    "authors": [{ "name": "Swag Example" }],
    "require": {
        "shopware/core": "~6.6.0"
    },
    "autoload": {
        "psr-4": { "Swag\\Badge\\": "src/" }
    },
    "extra": {
        "shopware-plugin-class": "Swag\\Badge\\SwagBadge",
        "label": {
            "en-GB": "Product badges",
            "de-DE": "Produkt-Badges"
        },
        "description": {
            "en-GB": "Shows badges on product pages",
            "de-DE": "Zeigt Badges auf Produktseiten"
        }
    }
}

The type tells Composer and Shopware this is a plugin. The shopware-plugin-class points to the base class from Your First Plugin. The version is what Shopware compares against the installed version to decide whether an update is pending. Labels and descriptions are shown in the plugin manager. The Store may require more fields, such as a changelog file per release, so check its current rules when you publish.

Declaring compatibility

The require entry for shopware/core is a promise: "this plugin works with these Shopware versions". Composer refuses to install the plugin on a shop outside that range, which protects merchants from breakage. Common forms:

Constraint Meaning
~6.6.0 6.6.0 or newer, but below 6.7.0
^6.6 6.6 or newer, below 7.0
>=6.5 <6.7 An explicit range
~6.5.0 || ~6.6.0 Either of two minor lines

A wide range such as ^6.5 is convenient, but it is a claim you must back with tests, because Shopware minor versions can change internal classes. Many plugin authors support the current and previous minor line and declare exactly that. Use your CI matrix from Testing Plugins to prove it. Before a major Shopware version, read the upgrade notes, since classes and extension points are allowed to change between majors.

Also check the php requirement. Your plugin may use syntax newer than a supported Shopware version's minimum PHP, which would fail on older shops.

Building a zip

A plugin zip contains the plugin folder (named after the plugin class, for example SwagBadge) with the source, built admin and storefront assets, composer.json and a changelog. It must not contain development files such as tests, .git, node_modules or the plugin's own vendor folder unless it has runtime dependencies that the shop does not provide.

The shopware-cli tool automates this (read-only):

Terminal
shopware-cli extension validate SwagBadge
shopware-cli extension zip SwagBadge --release

validate checks metadata and common mistakes such as missing files. zip builds a clean archive, builds the JavaScript assets and removes files that do not belong. Because options differ between versions of the tool, run shopware-cli extension --help. A minimal manual alternative is git archive with an export-ignore list, but then you must build and commit the assets yourself.

Asset builds matter. The admin and storefront bundles must exist in the zip, because a merchant who uploads it will not run npm. If a zip installs but the admin pages or styles are missing, the built files are the first thing to check.

Deploying to a server

For Composer-based projects, plugins live in custom/plugins or come in through Composer, and the project is deployed as a whole. A reliable sequence on the target server looks like this (read-only):

Terminal
composer install --no-dev --optimize-autoloader --no-interaction
bin/console plugin:refresh
bin/console plugin:update:all --no-interaction   # if your version provides it
bin/console system:update:finish --no-interaction
bin/console theme:compile --active-only
bin/console assets:install
bin/console cache:clear

Command names and options vary between versions, and some projects use Shopware's deployment helper instead of a hand-written list, so treat this as an outline and compare with bin/console list on your version. The principles hold in all setups:

  1. Build before you deploy. Install dependencies and compile assets in CI, then ship the result. Servers should not need Node.
  2. Run migrations and update steps on every deploy. This is what system:update:finish and plugin updates do for the database.
  3. Clear caches after code changes, and warm the ones that matter.
  4. Keep configuration out of the build. Environment-specific values come from .env or secrets, not from committed files.
flowchart LR
    G["Git push"] --> CI["CI<br/>install, test, build assets"]
    CI --> A["Artifact<br/>code + built assets"]
    A --> S["Server<br/>deploy release"]
    S --> M["Migrations<br/>plugin:update, system:update:finish"]
    M --> C["Clear and warm caches"]
    C --> L["Release live"]

Build and test once in CI, then promote the same artifact to servers.

How updates run

When a merchant installs a new zip, or you deploy a higher version in composer.json, the plugin is updated. Shopware compares the version in the database with the code, runs the plugin's update() method and any new migrations. The details are in Database Migrations, but the rules for safe updates are worth repeating:

  • Migrations are idempotent where possible, so a repeated run does no harm.
  • Put changes that break the old code (dropping a column) into the destructive phase, which runs only when a merchant or a deploy asks for it. Additive changes can run immediately.
  • Never edit a migration that has shipped. Add a new one.
  • Keep user data on uninstall unless the merchant asked to delete it.

For zero-downtime deployments, new code must work with the old schema and the old code must work with the new schema, for the minutes both are running. In practice that means two-step changes. First add the column and write to both, then later remove the old one. Maintenance mode for the sales channel is the fallback when a change cannot be made compatible.

Release checklist

Before tagging a release:

  • Version bumped in composer.json and the changelog written for it.
  • Tests pass on every supported Shopware and PHP version.
  • New migrations tested on a copy of an old database, not only on a fresh install.
  • Admin and storefront assets built and present in the zip.
  • composer.json constraints match what you tested.
  • Uninstall and reinstall checked once.

Checking constraints with a stand-in

The first stand-in is a small version-constraint checker. Real Composer is much more complete; this one understands ~, ^, >=, <, wildcard 6.6.*, spaces for "and" and || for "or". It shows what these operators actually allow.

PHP A semver constraint checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The table makes the difference visible: ~6.6.0 stops before 6.7, while ^6.6 allows every later 6.x release, which is a bigger promise to keep.

Validating the metadata

The second stand-in checks a plugin's composer.json against a release checklist. The real shopware-cli extension validate does much more, but the idea is the same: catch metadata mistakes before a merchant does.

PHP A release checklist for composer.json

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a constraint like ~6.6.0 for shopware/core mean?

    The tilde with three parts allows patch updates within the same minor line. It stops before the next minor.
  2. 2. Why should the built admin and storefront assets be inside the plugin zip?

    The merchant installs the zip as it is. Without built assets, the plugin's admin pages and styles are missing.
  3. 3. You want to drop a column your old code still reads, during a zero-downtime deploy. What is the safe approach?

    While old and new code run side by side, both must work with the schema. Destructive changes belong in a later step.
  4. 4. Which statement about a migration that has already shipped is true?

    Shops that ran the old version will not run an edited migration again. A new migration is the only reliable way to change the schema further.

Summary

  • A plugin's composer.json carries its type, class, version, labels and the Shopware compatibility range.
  • Declare only the Shopware and PHP versions you test, and use CI to back that claim.
  • Build a clean zip with built assets and no development files, for example with shopware-cli extension zip.
  • Deploy by building once, shipping the artifact, running update and migration steps, then clearing caches.
  • Updates run when the version rises: write idempotent migrations, never edit shipped ones and make destructive changes in a later step.
  • Run a release checklist every time, including an upgrade test from an older version.

Next: Project: Product Badges.