DEV Community: Stefan Pilz

Shopware Plugin Architecture: How to Build Update-Safe Plugins

Stefan Pilz — Fri, 02 Jan 2026 14:59:05 +0000

Shopware plugins often fail not because of bugs, but because of architecture decisions that don’t survive updates.

Every major Shopware release exposes the same pattern:

plugins that rely on core overrides break
fragile hacks stop working
maintenance costs explode

This article is a practical guide to building update-safe Shopware plugins that survive:

minor updates
major versions
core refactorings

Why “update-safe” matters in Shopware

Shopware evolves fast:

core services are refactored
internal logic moves
admin & storefront architectures change

If your plugin:

overrides core classes
depends on internal behavior
patches logic at the wrong layer

then updates will break it — not maybe, but eventually.

Update-safe plugins:

integrate instead of replace
react instead of override
extend behavior without owning it

1️⃣ Events instead of core overrides

❌ The classic mistake: overriding core classes

class CustomCartService extends CartService
{
    public function add(...) { ... }
}

This looks simple — and it’s fragile.

Why?

core services change signatures
internal logic shifts
parent behavior becomes unpredictable

✅ The correct approach: react via events

class CartSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            CartChangedEvent::class => 'onCartChanged'
        ];
    }

    public function onCartChanged(CartChangedEvent $event): void
    {
        $cart = $event->getCart();
    }
}

Benefits

no dependency on internal implementation
forward-compatible
predictable execution order

Rule of thumb:

If an event exists, never override the core.

2️⃣ Services over static helpers

❌ Anti-pattern: static helper classes

class PriceHelper
{
    public static function calculate(...) { ... }
}

Problems:

no dependency injection
hard to test
tightly coupled logic
difficult to extend

✅ Proper service-based architecture

services:
  MyPlugin\Service\PriceCalculator:
    arguments:
      - '@shopware.cart.calculator'

class PriceCalculator
{
    public function __construct(
        private CartCalculator $calculator
    ) {}

    public function calculate(...) { ... }
}

3️⃣ Subscriber > Decorator (most of the time)

Decorators are powerful — but risky.

Use decorators only when:

return values must be modified
no suitable event exists
logic must be changed synchronously

Subscribers are safer:

they do not replace logic
they survive refactors better
they don’t rely on internal call order

4️⃣ Message Bus for async & heavy logic

❌ Anti-pattern: heavy logic in request lifecycle

Examples:

external API calls
batch processing
AI requests
expensive calculations

✅ Use the Message Bus (Symfony Messenger)

class SyncProductMessage
{
    public function __construct(
        public string $productId
    ) {}
}

class SyncProductHandler
{
    public function __invoke(SyncProductMessage $message): void
    {
        // async processing
    }
}

5️⃣ Typical anti-patterns

accessing private core services
relying on undocumented entity fields
overwriting Twig blocks completely
business logic in controllers

Always extend, never replace.

6️⃣ Plugin boundaries

A stable plugin:

owns its own logic
does not own Shopware core behavior
integrates via public extension points

Ask yourself:

would this survive a major update?
does it rely on undocumented behavior?

7️⃣ Practical rules

events over overrides
services over helpers
subscribers over decorators
message bus over sync logic

Avoid

core inheritance
static utilities
undocumented internals

Final thoughts

Update-safe Shopware plugins are not about clever hacks.

They are about respecting boundaries.

If your plugin reacts instead of replacing, integrates instead of controlling and stays within public APIs, updates become boring.

And boring is good.

About the author

Stefan Pilz
Shopware Freelancer & Plugin Developer
Website: https://stefanpilz.ltd

Setting Up a New Shop in Shopware: Multi-Sales-Channel Decisions Explained

Stefan Pilz — Wed, 24 Sep 2025 19:41:39 +0000

Setting Up a New Shop in Shopware: Multi-Sales-Channel Decisions Explained

When starting a new shop project in Shopware, one of the most overlooked – yet crucial – architectural decisions is how to structure your sales channels.

Should you use different domains for each market, rely on subfolders under a single domain, or set up completely separate sales channels? Each approach has its strengths and weaknesses for SEO, maintenance, and scalability.

In this guide, we’ll explore the three main options, highlight the SEO pitfalls (like duplicate content between .de and .at), and give you a clear framework for making the right decision.

Option 1: Multiple domains on a single channel

Example setup:

myshop.de → Germany
myshop.at → Austria
myshop.com → international customers

Pros

Strong local signals (.de, .at build trust)
Customers immediately recognize a domain that feels “local”

Cons

If content is identical (e.g. Germany and Austria both in German), Google sees it as duplicate content
Needs proper hreflang tags and/or localized differences to avoid SEO issues
Slightly more complex to manage SSL, redirects, and tracking

Option 2: Subfolders on one main domain

Example setup:

myshop.com/de → Germany
myshop.com/at → Austria
myshop.com/en → international customers

Pros

All countries benefit from one strong domain authority
Easier to manage (single SSL, single analytics property)
Lower risk of duplicate content across markets

Cons

Less local perception: Austrian customers may trust myshop.at more than myshop.com/at
Legal or tax differences are harder to reflect in one channel

Option 3: Separate sales channels with individual domains

Example setup:

myshop.de → B2C Germany
myshop.at → B2C Austria
businessshop.de → B2B customers

Pros

Maximum flexibility: different assortments, prices, legal texts, shipping methods
Clear separation between B2B and B2C if needed

Cons

Highest maintenance effort: products, categories, and CMS content must be updated separately
Domains may compete with each other in search results
More technical complexity (plugins, tracking, SSL per domain)

The duplicate content trap (.de vs .at)

A common mistake: running myshop.de and myshop.at, both in German with nearly identical product and category content.

Google treats this as duplicate content, and one domain will almost always lose rankings.

How to fix it:

Add hreflang tags to indicate which content belongs to which market
Introduce small but meaningful differences: local pricing, shipping info, legal texts, or editorial content
Reconsider if separate ccTLDs are really necessary – subfolders might be the safer SEO play

Visual comparison

Here’s a radar chart that compares the three approaches across SEO, effort, and flexibility:

Decision matrix

Option	SEO Impact	Effort	Flexibility	Best for
Multiple domains	+ Local signals, trust - Duplicate content risk	Medium	Medium	Merchants focusing on local branding (.de/.at)
Subfolders	+ Strong domain authority - Less local perception	Low	Medium	SEO-driven, international expansion
Separate channels	+ Full separation - Domains may compete	High	High	B2B/B2C split, different assortments or legal setups

Conclusion

Shopware gives you full flexibility. The right choice depends on three factors:

SEO: Avoid duplicate content and configure hreflang correctly
Business: Are assortments, prices, and legal rules different per market?
Marketing: Do you need the trust of local ccTLDs, or do you prefer consolidating global SEO power on one domain?

👉 Golden rule: As few channels as possible, as many as necessary.

Next step

Planning to launch a new Shopware store?

Before making your decision on multi-channel architecture, make sure your setup aligns with your SEO strategy and business goals.

💬 I’ve supported multiple Shopware rollouts – if you’d like insights or a sanity check on your setup, feel free to reach out!

What Developers Need to Know About the Shopware 6.7 Update

Stefan Pilz — Tue, 06 May 2025 13:23:19 +0000

Shopware 6.7 is a major release packed with significant changes, especially relevant for developers. This article provides a structured overview of the most important new features, technical changes, and migration tips so you can upgrade your Shopware project successfully.

New Features and Improvements in Shopware 6.7

Accessibility Compliance: Shopware 6.7 fully implements the European Accessibility Act (EAA) requirements with comprehensive accessibility updates now enabled by default. For developers, this means your themes and plugins must now comply with stricter accessibility standards, including enforced UI adjustments.
Modernized Frontend Toolchain (Webpack → Vite): The admin frontend build system has been switched from Webpack to Vite, speeding up builds and improving development cycles.
Developers with admin UI plugins will need to migrate from webpack.config.js to vite.config.js.
Vue 3 and Pinia: Shopware 6.7 now runs fully on Vue 3. The legacy Vue 2 "migration build" has been removed.
All admin UIs and extensions must be compatible with Vue 3.
Additionally, the state management system has shifted from Vuex to Pinia.
Improved Caching System: Caching has been optimized to enhance performance and scalability.
Cache invalidations now happen asynchronously (every 5 minutes by scheduled task).
The separate Store API cache layer has been removed.
Updated Tech Stack Requirements: Shopware 6.7 now requires PHP 8.2+ and Node.js 20+. Core libraries like PHPUnit, Doctrine DBAL, and OAuth2 have been updated.
New Migration Toolkit: Shopware provides a developer tool to assist with plugin migration, capable of linting, auto-fixing, and formatting code.

Key Technical and Breaking Changes

Vite Frontend Build: Any plugins using Webpack must migrate to Vite. Shopware provides migration guides for creating vite.config.js.
Removal of Vue 2 Migration Mode: Legacy compatibility with Vue 2 is gone. All admin code must now use Vue 3 APIs and patterns.
Switch from Vuex to Pinia: Store definitions must be rewritten for Pinia. Access patterns shift from this.$store to Pinia store instances.
New Meteor Admin Components: Admin UI now uses Meteor Components aligned with the Shopware Design System. Use the deprecated attribute to temporarily fallback to legacy components.
Removed Legacy Systems: Deprecated templates and PHP methods have been removed, e.g., legacy product detail page templates.
OAuth2 Token API Strictness: The /api/oauth/token endpoint now requires RFC-compliant requests only.
Plugin Uninstall Behavior: Plugins must ensure they clean up their database artifacts when keepUserData = false.

Migration Guide for Developers (Upgrading to 6.7)

System Requirements:
- PHP 8.2+
- Node.js 20+
- Update your environment and test on staging first.
Check Theme Compatibility:
- Shopware’s premium themes won't be updated for 6.7.
- Review custom themes for deprecated structures.
Frontend Changes for Accessibility:
- Update themes to meet new accessibility rules.
- Adjust template structure where needed.
Update Admin Plugins:
- Migrate to vite.config.js
- Use Vue 3 + Composition API
- Replace Vuex with Pinia
- Update UI components to Meteor versions
Test All API Integrations:
- Ensure OAuth requests are RFC-compliant
- Review response changes and endpoints
Use the Plugin Migration Tool:
- Automate detection and correction of deprecated code.
Test Everything Thoroughly:
- Run the upgrade on a staging site
- Validate frontend, admin, plugins, and integrations

🚀 Need help upgrading to Shopware 6.7?

Whether you need migration support, plugin refactoring, or help reviewing your custom themes – I’m happy to assist as a technical partner or consultant.

👉 Message me here on dev.to or visit my website to learn more.

Shopware Apps vs. Plugins – Real-Life Example with Code

Stefan Pilz — Thu, 10 Apr 2025 19:14:56 +0000

Shopware 6 provides two powerful ways to extend and customize your shop: Apps and Plugins. Both offer ways to interact with the platform, but they serve very different purposes. In this post, we’ll explore the differences through a simple (and slightly sneaky) example involving the GMV (Gross Merchandise Volume) of a shop.

What We’re Building

We’ll create a Shopware App that queries the total order value of the shop (GMV) via the Shopware Admin API.

Then, we’ll implement a Plugin that intercepts those order values and manipulates them – effectively feeding fake data back to the app. This is not a practical use case, but it's perfect to show how these two extension types operate.

Shopware Apps: External Logic with API Access

Apps in Shopware 6 are external applications that run on a separate server (not inside Shopware) and communicate with the shop via a secure API integration.

When an app is installed, it registers an integration with specific access scopes (permissions), which the shop admin has to approve. It’s important to note: the app only gets access to the data that the API makes available, and only if the proper permissions were granted.

Here’s an example manifest.xml for our app:

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
<meta>
    <name>FakeGmvReporting</name>
    <label>Fake GMV Reporting</label>
    <label lang="de-DE">Fake GMV Reporting</label>
    <description>Test app for reading orders to calculate GMV.</description>
    <author>Friendly Hacker</author>
    <version>1.0.0</version>
    <license>MIT</license>
</meta>

<setup>
    <registrationUrl>http://fake-gmv-app:3000/register</registrationUrl>
    <secret>supersecret</secret>
</setup>

<webhooks>
    <webhook name="appActivated" url="http://fake-gmv-app:3000/activated" event="app.activated"/>
</webhooks>

<permissions>
    <read>order</read>
    <read>order_line_item</read>
    <read>currency</read>
    <read>system_config</read>
</permissions>
</manifest>

✅ Shopware generates an integration with the exact set of API scopes you declare in the manifest.

Apps cannot access more than what’s explicitly listed – unless, of course, the scopes are overly broad.

👉 As a shop owner, always review which data tables are requested – system_config is commonly used to extract sensitive config and credentials!

🛡 OAuth Flow: /register, /confirm, /activated

The app follows the standard Shopware app lifecycle:

`/register`

Shopware calls this during installation. The app responds with a cryptographic proof.

app.get('/register', (req, res) => {
  const shopUrl = req.query['shop-url'];
  const shopId = req.query['shop-id'];
  const rawData = `${shopId}${shopUrl}${APP_NAME}`;

  const proof = crypto
    .createHmac('sha256', APP_SECRET)
    .update(rawData)
    .digest('hex');

  res.json({
    proof: proof,
    secret: APP_SECRET,
    confirmation_url: 'http://fake-gmv-app:3000/confirm'
  });
});

`/confirm`

Shopware sends client credentials so the app can request access tokens.

app.post('/confirm', express.text({ type: 'application/json' }), (req, res) => {
  const body = req.body;

  const tokenData = {
    shopId: body.shopId,
    clientId: body.apiKey,
    clientSecret: body.secretKey,
    shopUrl: 'http://shopware'
  };

  fs.writeFileSync('./shop-token.json', JSON.stringify(tokenData, null, 2));
  res.sendStatus(204);
});

⚠️ In this example, we store the API credentials in a local file – don’t do this in production!

This is just for demonstration. In a real app, use a secure key vault and avoid persisting credentials as plain text.

`/activated`

app.post('/activated', (req, res) => {
  console.log('✅ App was activated');
  res.sendStatus(200);
});

ℹ️ Note: Our Shopware instance is assumed to be running at http://shopware, and our app lives at http://fake-gmv-app.

📊 API Endpoint: `/gmv`

This is the core logic of our app – fetch orders and calculate GMV.

app.get('/gmv', async (req, res) => {
  const tokenData = JSON.parse(fs.readFileSync('./shop-token.json', 'utf-8'));
  const token = await fetchAccessToken(tokenData.clientId, tokenData.clientSecret, tokenData.shopUrl);

  const response = await axios.get(`${tokenData.shopUrl}/api/order`, {
    headers: { Authorization: `Bearer ${token}` }
  });

  const orders = response.data.data;
  const gmv = orders.reduce((sum, order) => sum + order.amountTotal, 0);

  res.json({
    orders: orders.length,
    gmv: gmv.toFixed(2),
    currency: orders[0]?.currency?.isoCode || 'EUR'
  });
});

Shopware Plugins: Internal Logic, Full Power

Plugins, unlike apps, run inside the Shopware core and have access to everything – services, database, events, etc.

Let’s modify our GMV example:

We’ll create a plugin that recognizes requests made by our app – and manipulates the data being returned.

public function onOrderLoaded(EntityLoadedEvent $event): void
{
    $source = $event->getContext()->getSource();
    if (!$source instanceof AdminApiSource) return;

    $criteria = new Criteria();
    $criteria->addFilter(new EqualsFilter('name', 'FakeGmvReporting'));

    $apps = $this->appRepository->search($criteria, $event->getContext())->getEntities();
    $app = $apps->first();

    if ($app && $source->getIntegrationId() === $app->getIntegrationId()) {
        foreach ($event->getEntities() as $entity) {
            if (!$entity instanceof OrderEntity) continue;

            $entity->setAmountTotal(1.00);
            $entity->setAmountNet(0.84);
            $entity->setShippingTotal(0.00);
            $entity->setTaxStatus('gross');
        }
    }
}

🤯 The plugin detects API requests made by the app and changes the order data on the fly!

Summary

	Shopware App	Shopware Plugin
Runs where?	External server	Inside the Shopware environment
Deployment	No deployment on Shopware required	Installed as plugin
Security	Needs explicit permissions	Has full access
Use Cases	External services, integrations	Deep customizations
Example	Read orders via Admin API	Modify data before it's returned

Need Help with Your Own Shopware App or Plugin?

If you're planning to develop your own Shopware 6 app or plugin and could use some expert support, I’m happy to help.

From figuring out the Shopware API to building a clean plugin structure — I’ve got your back.

You can find more info about my services here: Shopware 6 plugin development.

Things I Wish I Knew Before Building My First Shopware Plugin #shopware #symfony #php

Stefan Pilz — Thu, 27 Mar 2025 14:42:02 +0000

🧠 Things I Wish I Knew Before Building My First Shopware Plugin

Building a custom plugin for Shopware 6 can feel exciting, especially if you come from a Symfony or PHP background. But once you dive in, the learning curve can be surprisingly steep. After developing several Shopware plugins, here are some things I really wish I had known earlier.

Plugin or App?
Dependency Injection
Docs & Core Code
Cache Issues
Twig Logic
Testing
Shopware Services
Conclusion
Need Help?

Plugin or App? Know the Difference

Shopware offers two extension systems: plugins and apps. If you just need to display something, handle webhooks, or connect to an external API, apps are often simpler and update-safe. Plugins, on the other hand, offer deeper system-level integration. I jumped into plugins without realizing an app might've been enough.

Tip: Evaluate your needs carefully – plugins are powerful, but apps are easier to maintain and don't require direct code deployment on the shop server.

Embrace Dependency Injection Early

Shopware is built on Symfony, which means everything revolves around dependency injection. Your custom services, event subscribers, and classes won’t work unless properly defined in services.xml (or services.yaml, depending on setup).

Lesson: Don't assume your service is automatically injected. Use bin/console debug:container to see what's registered and where.

Read the Docs – Then Read the Core Code

The Shopware developer docs are helpful, but they don't cover everything. Some use cases (like customizing admin modules or extending checkout logic) may be outdated or missing. The best resource? The core source code and existing plugins.

Tip: Browse the Shopware GitHub repos and inspect how they build core features. Real examples are better than theory.

Cache: Your Best Friend and Worst Enemy

Made a change but nothing happens? Welcome to Shopware caching. You’ll often need to clear the cache using:

bin/console cache:clear

Also, remember to recompile the storefront or admin if working on those parts.

bin/console theme:compile
bin/console administration:build

Pro tip: Automate cache clearing in your local setup. It'll save your sanity.

Avoid Business Logic in Twig

It's tempting to put logic directly into your Twig templates, especially for quick fixes. But it's a trap. Shopware provides ViewSubscribers and Decorators for a reason.

Better approach: Keep templates clean. Move logic to PHP and inject variables into views.

Start Testing Early

When I built my first plugin, I skipped tests thinking it would be faster. Big mistake. Even a few unit or integration tests can save hours of debugging later on.

Suggestion: Add a basic PHPUnit setup. Even if it's just one or two tests at first, it pays off.

Reuse Existing Shopware Services

Need to upload files? Send emails? Generate thumbnails? Shopware probably already has a service for that. Don't reinvent the wheel.

Example: The media.service handles file uploads and is way more robust than anything I could’ve written on the fly.

Conclusion

Shopware plugin development is incredibly powerful but comes with complexity. Understanding the underlying Symfony architecture, leveraging existing services, and writing clean, maintainable code can make the difference between a headache and a success story.

If you're just starting out: stay curious, stay patient, and read the core.

💬 What about you?

What was your biggest "aha!" moment when working with Shopware (or Symfony)? Drop it in the comments – I'm always curious to hear other devs' lessons learned!

Need help with Shopware plugin development?

I offer freelance services for custom plugin development, troubleshooting, and consulting.

👉 https://stefanpilz.ltd/en/shopware-freelancer/shopware-plugin-development

DEV Community: Stefan Pilz

Shopware Plugin Architecture: How to Build Update-Safe Plugins

Why “update-safe” matters in Shopware

1️⃣ Events instead of core overrides

❌ The classic mistake: overriding core classes

✅ The correct approach: react via events

2️⃣ Services over static helpers

❌ Anti-pattern: static helper classes

✅ Proper service-based architecture

3️⃣ Subscriber > Decorator (most of the time)

4️⃣ Message Bus for async & heavy logic

❌ Anti-pattern: heavy logic in request lifecycle

✅ Use the Message Bus (Symfony Messenger)

5️⃣ Typical anti-patterns

6️⃣ Plugin boundaries

7️⃣ Practical rules

Final thoughts

About the author

Setting Up a New Shop in Shopware: Multi-Sales-Channel Decisions Explained

Setting Up a New Shop in Shopware: Multi-Sales-Channel Decisions Explained

Option 1: Multiple domains on a single channel

Option 2: Subfolders on one main domain

Option 3: Separate sales channels with individual domains

The duplicate content trap (.de vs .at)

Visual comparison

Decision matrix

Conclusion

Next step

What Developers Need to Know About the Shopware 6.7 Update

New Features and Improvements in Shopware 6.7

Key Technical and Breaking Changes

Migration Guide for Developers (Upgrading to 6.7)

🚀 Need help upgrading to Shopware 6.7?

Shopware Apps vs. Plugins – Real-Life Example with Code

What We’re Building

Shopware Apps: External Logic with API Access

🛡 OAuth Flow: /register, /confirm, /activated

/register

/confirm

/activated

📊 API Endpoint: /gmv

Shopware Plugins: Internal Logic, Full Power

Summary

Need Help with Your Own Shopware App or Plugin?

Things I Wish I Knew Before Building My First Shopware Plugin #shopware #symfony #php

🧠 Things I Wish I Knew Before Building My First Shopware Plugin

Table of Contents

Plugin or App? Know the Difference

Embrace Dependency Injection Early

Read the Docs – Then Read the Core Code

Cache: Your Best Friend and Worst Enemy

Avoid Business Logic in Twig

Start Testing Early

Reuse Existing Shopware Services

Conclusion

💬 What about you?

Need help with Shopware plugin development?

`/register`

`/confirm`

`/activated`

📊 API Endpoint: `/gmv`