DEV Community: shopware

Adding and maintaining new languages in Shopware is now dead simple

Marco Steinhaeuser — Tue, 03 Mar 2026 15:52:30 +0000

With Shopware v6.7.3.0, we introduced a very interesting feature for those of you who have to deal with languages and translations in your online shops. As we ported the functionality of the formerly known Shopware language pack into the core of Shopware, installing and maintaining languages in Shopware became dead-simple. In this blog post, you will learn how it works and what the limits of this modus operandi are.

Translation platform on Crowdin

The basis is our translation platform with the generous help of Crowdin. All newly appeared language keys (AKA "snippets") in the Shopware core will automatically be available in Crowdin, followed by an automatic translation utilising Amazon Translate. Crowdin shows how much of a language is human-translated via the colour of the status bar in the language overview: Blue means machine translated, green means human translated.

All translations will be synchronised daily to the repository github.com/shopware/translations/, after synchronisation they can be used as shown in the following steps.

Adding a new translation to Shopware

Shopware comes with just three pre-installed languages: English – British and American – plus German. Let's say you want to extend your online shop with Spanish like it is spoken in Spain (es-ES).

$ php bin/console translation:install --locales=es-ES

Just like that, Spanish is installed and already activated in your Shopware instance. All you have to do now is login to your administration panel and adjust the URL for your new language, for example https://example.com/es/ (replace example.com with your domain). When you navigate to this URL, you'll now see Spanish translations all over – well, except for your products and custom text. 😉

Maintaining translations

Let's go a step further and update your new translation:

$ php bin/console translation:update --locales=es-ES

This way, you will fetch the latest language keys, no matter if used or not, and also the latest human approved translations by the community.

There are even more commands and options available. Read more about it in the documentation.

If you want to have your very own behaviour for special language keys in your online shop, there is no need to fight about the correct phrase on our translation platform. Think of cart vs. basket vs. trolley, for example. In this case, simply make use of Shopware admin » General » Languages » Manage Snippets. These changes will be stored in the database and have first loading priority. This way, your newly installed Spanish translation set stays update-safe, and you can have your very own style without bothering others. However, other community members still can make use of it.

The coolest advantage of these CLI commands is that you could even use the update method described above in a cron job or even in your continuous integration setup – at least for staging: stay up-to-date with the latest community corrections in this translation.

A bit off-topic and out of scope for this blog post, but I don't want to miss pointing you to this great translation QA-tool for your CI: https://github.com/boxblinkracer/phpunuhi – indispensable for bigger online shops with any quality approach, isn't it? Especially, as it was developed by one of my best mates in the community, @boxblinkracer

Limits and disclaimer

Please note that this blog post is about translations of the core language keys / snippets for the storefront as well as the administration panel of your Shopware instance. No product information nor any other database entries have automatically been translated.

With the method described above, you are installing translations made by the community. Shopware can not give any guarantee on the quality nor the content of these translations. We cannot proofread languages we do not speak, which means there is the possibility of a bad actor adding wrong or even offensive text into translations. If you gain knowledge of it, please inform us as soon as possible to help keeping the quality of the translations high. Also, please avoid the automatic update method in production and only use it on staging for this reason.

What I have described here will only work for translations available on translate.shopware.com. There are two other methods if you need a language not available through the Crowdin setup:

(Preferred) Get in touch and request another language to be added to our Crowdin instance. We can quickly provide at least an automated translation, which will – over time, and depending on the quality of the automation – be approved by a human being.
Create your own plugin on the basis of the Shopware language plugin. This way, you have full ownership, without any community connection.

Last but not least: We will deliver any language available on translate.shopware.com, be it LTR (left to right) or RTL (right to left, like Arabic, for example), the way described above knowing that there might be some display glitches. This is because we rely on you, the community. You as native speakers have more experience in properly solving this topic in no time as we might still struggle in planning, sorting it out, resolving and testing it. Looking forward to a proper solution, best as a free/libre and open source plugin for Shopware. Don't hesitate to ping us once you're done with it!

Next steps

Send your translators to translate.shopware.com for approving existing auto-translations, correcting them and let the remaining language keys be translated for the benefit of the whole community.

We are planning to publish a so called "in-context translation": There will be a demo Shopware instance that translators can use to see the context of what they are translating – everything connected to Crowdin. Once this is finished, we will announce it in this channel as well as social media.

Looking for help or experienced translators? We created a club in hub.shopware.com, especially for translators. We will be there to answer your translator questions.

Have fun with this new feature and let us know how it is working for you!

How to update php-redis extension (and why you might need to do so during shopware updates)

Jonas Elfering — Fri, 27 Feb 2026 09:00:00 +0000

This post gives you an explanation on why you might need to update the php-redis when upgrading to the latest shopware versions and how you can do so hassle-free

Why you might need to update the `php-redis` extension during shopware updates?

The latest shopware 6.7.7.0 version included the upgrade to Symfony LTS version 7.4. Because the previously used Symfony 7.3 version stopped being actively supported in Jan 2026, shopwares 6.6 LTS version will receive the Symfony update as well as part of the next release.
The update from Symfony 7.3 to 7.4 is only a minor upgrade, so it should not include any breaking changes. While that is true on the code level of Symfony itself, Symfony did increase the needed minimum version of the php-redis extension to 6.1 as part of the minor update. So if you currently use an older version of the extension, you will need to update the extension in order to successfully update shopware. This might especially be the case if you rely on older versions of Linux distributions; the 24.04 LTS version of Ubuntu, for example, ships php-redis extension in version 5.3, which is not compatible, and you need to take action to update the package accordingly.

How can I figure out which `php-redis` version I'm currently running?

You can check the installed version of php-redis extension by running the following command:

php --re redis | head -1

When that command indicates that you are running on version 6.1 or newer, you are ready to update to the latest shopware version without further action. If you're currently running an older version, you need to update it first.

Additionally, Symfony added a composer conflict with older php-redis versions, which means that the shopware upgrade (with the included Symfony upgrade) will throw a composer error if you still use an older version.

Should I update my `php-redis` extension now?

Generally, you should only look at upgrading php-redis when you plan to upgrade to the latest shopware versions, which include the upgrade to Symfony 7.4. Upgrading the php-redis version in existing, running applications provides no real benefit. And quite to the contrary, older shopware versions (especially when you are still on shopware 6.5) might not work with the latest php-redis version. Therefore, you shouldn't upgrade just in case, only if you are affected and want to upgrade to the latest shopware versions that require this. This guide shouldn't be considered a general best practice, but rather a troubleshooting guide for when you're upgrading and run into the need to update the php-redis extension.

How to update the `php-redis` extension in Docker

Docker makes it easy to control the full environment; therefore, it is straightforward to update the php-redis extension in your Dockerfile.

First you should download the php extension installer for Docker and make it executable:

ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions

That script helps you to manage php extensions.

Next you can install the php-redis extension:

RUN install-php-extensions redis

By default, that will install the latest stable version of the extension. It might be the case that you pinned the installed version, and you need to upgrade that:

-RUN install-php-extensions redis-6.0
+RUN install-php-extensions redis-6.3

When you use the official shopware/docker image, that update is already done automatically, and you just need to make sure that you update to the latest version of the image.

How to update the `php-redis` extension in Ubuntu

You can install the php-redis extension in Ubuntu through the default package manager:

sudo apt install -y php-redis

However, depending on the Ubuntu version you are using, the extension available in the official package repository might be too old.

In that case, you can install the package from the ondrej/php package repository, which is the trusted source for pre-built php packages:

sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update

After that when you install the php-redis extension it should pick up the latest version:

sudo apt install -y php-redis

How to install the extension locally (with PIE)

There is a new extension installer in the PHP ecosystem called PIE. PIE makes installing extensions easier and installs the latest versions from Packagist. PIE is intended to replace the old PECL installer and works similarly to Composer.

To install PIE follow the installation instructions from the official repository:

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

When you have PIE installed, you can install the php-redis extension by running:

pie install phpredis/phpredis

How to install the extension locally (with PECL)

PECL is the old-school extension installer in the PHP ecosystem; setting it up is not as straightforward as PIE, so it is not recommended anymore. However, if you have already set up PECL, you can continue using that.

If you have PECL set up, you can install the latest extension by running:

pecl install redis

Automate Procurement in Shopware with EDI integrations

Sander Mangel — Wed, 07 Aug 2024 13:24:37 +0000

As a retailer or wholesaler, much of the daily operations revolves around data exchange with suppliers. Product stock and pricing is continuously updated, new product offerings need to be added, and purchase orders must be sent out to fulfill client orders or replenish stock. This can equate to a full-time job for several employees, if not entire departments.

Electronic Data Interchange (EDI) integrations are a great solution to reduce manual effort in many of these processes. EDI helps automate communication with your suppliers, improving efficiency and reducing errors. This article will explain the benefits of EDI integrations for catalog management, stock updates, and purchase orders. We will discuss what EDI is, the different EDI formats, why the right solution partner is crucial, and how to use an Integration Platform as a Service (IPaaS) solution to integrate EDI into Shopware.

Benefits of Automating Integrations

Catalog Management: With EDI, product catalogs are automatically updated. You don't need to manually enter new products or change details. This saves time and ensures accuracy.
Stock Updates: EDI keeps your stock levels accurate. Suppliers can send stock updates directly to your system, so your Shopware store always shows correct stock levels.
Purchase Orders: Automating purchase orders with EDI means orders are sent to suppliers instantly. This speeds up the process and reduces the risk of errors in order details.

What is EDI?

Electronic Data Interchange (EDI) is a technology that allows different businesses to exchange documents in a standardized electronic format. Instead of using paper, email, or fax, businesses can send documents like purchase orders and invoices directly from one computer system to another. EDI was first introduced in the 1960s and became more widely adopted in the 1980s and 1990s. This technology helps ensure that the data is accurate and sent quickly.
For EDI to work, both the supplier and the retailer need to have EDI implemented. This is often initiated by the supplier. EDI is ideal for automating integrations because it standardizes the data exchange process. It allows different systems to communicate easily, reducing the need for manual work and minimizing mistakes.

Understanding EDI Formats

There are different EDI formats, and knowing their differences is important:

ANSI X12: Common in the United States, used for various business documents.
EDIFACT: Widely used in Europe and internationally.
Proprietary Variants: Some companies and software providers, like COMARCH, have their own EDI standards. These are tailored to specific business needs and may offer additional features.
Industry-Specific Variants: Certain industries have their own EDI standards. For example, the automotive industry uses standards like ODETTE, while the retail industry may use standards developed by GS1.

Each format has its strengths, and the choice depends on your specific needs and the region you operate in.
While EDI is a standardized document format, it is by no means plug and play. Each party has their own specific values for specific fields, and ultimately a mapping between these values needs to be made. For example, while you might use a product property called "table top color" with a value such as "Dark Oak", a supplier might call that same property "surface color" with a property value of "Brown wood".

The Value of an EDI Implementation Partner

Reaping the benefits of EDI is as much a technical matter as it is one of connecting to the right network. EDI implementation partners build networks of companies for which they already have existing integrations and, more importantly, value mappings. These companies might also have their own format standards, such as COMARCH.
Most EDI implementation partners offer their own modern API layer, which simplifies the integration process. This API layer allows you to connect your Shopware system to the EDI network more easily and efficiently.
The right partner will advise on which formats to support, can quickly integrate a large number of suppliers, and helps with creating the mapping to your specific data models. This means you can leverage their expertise and existing connections to make the integration process smoother and more efficient.

Integrating via EDI with Shopware

Generally, integrations are made via an ERP, OMS, or IMS system, and less so directly with an ecommerce platform. Having said that, direct integration with Shopware can be a valid approach.
We recommend leveraging an IPaaS solution to connect with the APIs of the EDI implementation partner.
If only one supplier is integrated, it might be an option to directly ingest the EDI documents into the IPaaS solution, although this might lead to more maintenance work over time.
From the IPaaS solution, the integration with Shopware is quickly made by finding the standard integration in the IPaaS solution's integration store.

Conclusion

Leveraging EDI integrations with Shopware can greatly enhance your business operations. Automating catalog updates, stock management, and purchase orders improves efficiency and accuracy. Understanding different EDI formats helps you choose the right one for your needs. Finding a partner with a large network can simplify the process, or you can opt for an IPaaS solution to manage integrations yourself. Embracing EDI integrations will streamline your business and help you stay competitive in the market.

Gross and Net-Switch for B2B and B2C Shops built with Composable Frontends

Björn Meyer — Wed, 04 Oct 2023 10:11:49 +0000

As a seller, you always want to offer your customers the best possible user experience. If an online store is not exclusively geared towards B2C or B2B, this becomes difficult, as these target groups have different requirements. One of the main requirements of B2B customers is, for example, the display of prices without VAT.

Whether the prices are displayed with or without VAT is controlled in Shopware via the customer group. However, if the user is not logged in, he automatically receives the default customer group, which has set the price display incl. VAT in the default.

In order to enable the user to switch from B2C to B2B in a non-logged-in state, a corresponding switch is offered in the store in many cases.

For a Shopware installation with default storefront (Twig) the way seems very obvious, but for the implementation with Composable Frontends we asked ourselves some questions:

Where should the setting of the switch be stored?
How does the correct price output take place?
How can a corporate customer be automatically registered with the B2B customer group?

Local storage instead of session

If we would probably store the switch setting in the session (PHP) so far, our choice for Composable Frontends falls on the local storage. The reason for this is that the handling of the price display mainly takes place in the frontend and the adjustment is easier to implement here.

For this purpose we use the useLocalStorage() function of the VueUse Collection, which simplifies the handling of the variable from the local storage and brings the usual reactivity of Vue at the same time.

So we need a Vue component for the switch, we call this component TaxSwitch. We include this in the header so that it is visible on every page in the store.

The switch receives the values net (for B2C) and gross (for B2B). Since by default the customers are B2C customers, the local storage variable in the second parameter receives the default value gross.

The button should only be visible when the customer is not logged in, which we achieve with the simple query v-if="!isLoggedIn" within the component.

💡 We use Vuetify components (v-switch, v-col) in the templates above, these are recognizable by the v- prefix. To use the same components you need to install it into your project via a package manager.

<script setup lang="ts">
import { useLocalStorage } from "@vueuse/core";
const { isLoggedIn } = useUser();
const taxSwitch = useLocalStorage("taxSwitch", "gross");
</script>
<template>
  // ... v-switch component is provided by vuetify
  <v-switch
    v-if="!isLoggedIn"
    v-model="taxSwitch"
    hide-details
    true-value="net"
    false-value="gross"
    class="flex-0-0"
    data-testid="tax-switch"
  >
    <template #prepend> Private</template>
    <template #append> Company</template>
  </v-switch>
</template>

Price calculation based on the setting of the B2C / B2B switch

In Shopware store API, gross and net prices are not returned at the same time, so we need to calculate the prices according to the switch setting.

To simplify this, we use the SharedPrice component from the Demo Store template consistently for every price display in the store. This way we only have to implement the logic in one place.

We have to calculate the price only in the following case:

If the customer is not logged in
and the switch has the value net
and the store setting of the tax has the value gross.

In all other situations, the price is passed on without calculation.

Depending on the implementation, there are places in the cart and checkout where no calculation of the tax should take place. That's why we decided to use the props.taxRate as an indicator for this purpose. If this is not passed to the SharedPrice component, nothing has to be calculated.

Furthermore, we have added an output to the price, which gives the user a hint (taxHint) whether the price is displayed including or excluding VAT.

Thanks to the reactive mechanics of the Vue framework, all prices in the frontend are automatically adjusted when the switch is changed.

<script setup lang="ts">
const { getFormattedPrice } = usePrice();
const { isLoggedIn } = useUser();
const { taxState } = useSessionContext();
const taxSwitch = useLocalStorage("taxSwitch", "gross");
const props = defineProps<{
  value: object | undefined;
}>();
const getPrice = computed<string>(() => {
  return !isLoggedIn.value &&
    taxSwitch.value === "net" &&
    taxState.value === "gross" &&
    props.value.taxRate !== undefined
    ? getFormattedPrice((props.value.price / (100 + props.value.taxRate)) * 100)
    : getFormattedPrice(props.value.price);
});
const taxHint = computed(() => {
  if (props.value.taxRate === undefined) {
    return "";
  }
  if (
    (!isLoggedIn.value && taxSwitch.value === "net") ||
    (isLoggedIn.value && taxState.value === "net")
  ) {
    return "ohne&nbsp;USt.";
  } else {
    return "inkl.&nbsp;USt.";
  }
});
</script>
<template>
  <span>
    <slot name="beforePrice" />
    <span data-testid="shared-price">{{ getPrice }}</span>
    &nbsp;<span class="text-caption" v-html="taxHint"></span>
    <slot name="afterPrice" />
  </span>
</template>

Automatic registration of the customer group based on the setting of the B2C / B2B switch

To ensure that a new B2B customer retains the correct display of VAT in the order process after registration, the B2B customer group must be set during registration.

Plugin configuration

For this reason, we create a plugin configuration with a selection field that allows you to specify the B2B customer group. Additionally, we added an option to activate the plugin.

<?xml version="1.0" encoding="UTF-8"?>
<config
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/System/SystemConfig/Schema/config.xsd"
>
  <card>
    <title>#ConVisTaxSwitch# Settings</title>
    <title lang="de-DE">#ConVisTaxSwitch# Einstellungen</title>
    <input-field type="bool">
      <label>Active</label>
      <label lang="de-DE">Aktiviert</label>
    </input-field>
    <component name="sw-entity-single-select">
      <name>b2bCustomerGroup</name>
      <entity>customer_group</entity>
      <label>Choose the B2B customer group.</label>
    </component>
  </card>
</config>

Customize registration form

To allow the user to register as a company in the registration process, we have added the fields AccountType and Company to the registration form of the Demo Store template.

In the initial state we automatically set the AccountType to private, if the switch is set to gross we change it to business. To make the Company field mandatory for the AccountType business, we extend the form validation rules accordingly.

// pages/checkout/index.vue
<script setup lang="ts">
// ...
const state = reactive({
  accountType: taxSwitch.value === "gross" ? "private" : "business",
  salutationId: "",
  firstName: "",
  lastName: "",
  email: "",
  password: "",
  guest: false,
  billingAddress: {
    company: "",
    street: "",
    zipcode: "",
    city: "",
    countryId: "",
    countryStateId: "",
  },
  customShipping: false,
});
// ...
const rules = computed(() => ({
  accountType: {
    required,
  },
  salutationId: {
    required,
  },
  firstName: {
    required,
    minLength: minLength(3),
  },
  lastName: {
    required,
    minLength: minLength(3),
  },
  email: {
    required,
    email,
  },
  password: {
    required: requiredIf(() => {
      return !state.guest;
    }),
    minLength: minLength(8),
  },
  billingAddress: {
    company: {
      required: requiredIf(() => {
        return state.accountType === "business";
      }),
    },
    street: {
      required,
      minLength: minLength(3),
    },
    zipcode: {
      required,
    },
    city: {
      required,
    },
    countryId: {
      required,
    },
    countryStateId: {
      required: requiredIf(() => {
        return
        !!getStatesForCountry(state.billingAddress.countryId)?.length;
      }),
    },
  },
}));
// ...
</script>

// pages/checkout/index.vue
<template>
  // ... v-col component is provided by vuetify
  <v-col cols="12">
    <v-select
      v-model="state.accountType"
      id="accountType"
      :label="$t('form.accountType')"
      :items="accountTypes"
      name="accountType"
      :disabled="loading"
      data-testid="registration-account-type-select"
      :error-messages="$v.accountType.$errors.map((e) => e.$message)"
      @blur="$v.accountType.$touch()"
      @update:modelValue="changeTaxSwitchByAccountType"
    ></v-select>
  </v-col>
  // ... v-col component is provided by vuetify
  <v-col v-if="state.accountType === 'business'" cols="12">
    <v-text-field
      id="company"
      v-model="state.billingAddress.company"
      :label="$t('form.company') + ' *'"
      name="company"
      type="text"
      autocomplete="company"
      :disabled="loading"
      data-testid="registration-company-input"
      :error-messages="$v.billingAddress.company.$errors.map((e) => e.$message)"
      @blur="$v.billingAddress.company.$touch()"
    />
  </v-col>
  // ...
</template>

Create Subscriber

In order to be able to directly overwrite the customer data with the B2B customer group after registration, we create a subscriber for the CustomerEvents::CUSTOMER_WRITTEN_EVENT.

If the plugin is active and the Company field has a value, the user is a B2B customer according to our definition. Thus, we set the B2B customer group that we had previously defined in the plugin configuration for this customer.

<?php declare(strict_types=1);

namespace ConVis\TaxSwitch\Subscriber;

use Shopware\Core\Checkout\Customer\CustomerEvents;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Shopware\Core\System\SystemConfig\SystemConfigService;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class CreateCustomerSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private readonly EntityRepository $customerRepository,
        private readonly SystemConfigService $systemConfigService
    ) {}

    public static function getSubscribedEvents(): array
    {
        return [
            CustomerEvents::CUSTOMER_WRITTEN_EVENT => 'onCustomerWritten'
        ];
    }

    public function onCustomerWritten(EntityWrittenEvent $event): void
    {
        $context = $event->getContext();
        $salesChannelId = $context->getSource()->getSalesChannelId();
        $pluginActive = $this->systemConfigService->get('ConVisTaxSwitch.config.active', $salesChannelId);

        if (!$pluginActive) {
            return;
        }

        $b2bCustomerGroupId = $this->systemConfigService->get('ConVisTaxSwitch.config.b2bCustomerGroup', $salesChannelId);
        $writeResults = $event->getWriteResults();
        $payload = $writeResults[0]->getPayload();

        if (!empty($payload['company']) && $payload['groupId'] !== $b2bCustomerGroupId) {
            $this->customerRepository->update([
                [
                    'id' => $payload['id'],
                    'groupId' => $b2bCustomerGroupId,
                    'requestedGroupId' => null,
                ]
            ], $context);
        }
    }
}

If the customer has set the switch to B2B, now in the store not only the price display is adjusted, but also automatically receives the B2B customer group during registration and during checkout.

This blog post was provided by our partner con-vis and René Altmann. It shows very well that the headless approach with Shopware Composable Frontends can be suitable for both B2C and B2B customers. Thank you for sharing this knowledge.

Mocks and their Influence on Software Design

Jonas Elfering — Fri, 08 Sep 2023 09:05:00 +0000

When speaking about unit testing, one automatically also speaks about mocks and the need to mock away dependencies.

It seems to be quite a typical attitude towards mocks along the lines of "Mock every external dependency of the class under test" and this attitude can be quite dangerous.

Therefore, here are some words of caution on the implication that the heavy use of mocks in your code base can have in terms of the overall system design or architecture.

TL;DR

Mocks are used to provide isolation in unit tests, and thus should help to create software that is easy to test and easy to change. But in fact, an over-usage of mocks in any unit test suite can cover up underlying issues in the software design that make the software hard to test and hard to change. So Mocks should be treated as one tool in your toolbox that one can use to build high-quality and maintainable software. That means one should know when to apply this specific tool, or when should rather use another tool from the toolbox.

Mocks are hard to refactor

Be cautious when utilizing mocks extensively because it can be hard to automatically refactor classes. This is because IDEs do not provide robust support for refactoring classes that are heavily mocked, and tools like PHPStan may not effectively detect these mock-related issues.

More broadly speaking, it is hard to guarantee that the mock behaves in the same/or intended manner as the real implementation (especially when the underlying implementation changes).

Use mocks only where you need to because:

creating the objects is hard as you need tons of nested dependencies to create the object.

the class produces some side effects that you don't want in unit tests (e.g., DB writes).

For all other cases, use real implementations and rely as minimally as possible on the magic of PHPUnit's mocking framework.

Focus on behavior, not implementation: Effective unit testing principles

Relying heavily on mocks creates a bad pattern in unit tests of testing how something is implemented and not what the implementation actually does. If tests are implemented in a mock-heavy way, they are tightly coupled to the implementation, meaning they rely on implementation details and may fail more often when the implementation details change than when the actual behavior of the class under test changes. Consider these two example changes to some classes:

Before:

$id = $this->repository->search($criteria, $context)->first()?->getId();

After:

$id = $this->repository->searchIds($criteria, $context)->firstId();

Before:

$values = $this->connection->fetchAllAssociative('SELECT first, second FROM foo ...');
$values = $this->mapToKeyValue($values);

After:

$values = $this->connection->fetchKeyValue('SELECT first, second FROM foo ...');

By definition, both changes are a pure example of refactoring:

Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior.
-> Martin Fowler

But when the unit test mocked the repository or connection dependencies, the unit tests will fail after the change, even though the external behaviour (that's what a test should really test) was not changed.

Using mocks is ok in some cases, but not all.

Probably the examples from above are ones that are totally valid (as the mocked classes rely on a DB), which can be commonly encountered in real life.

Furthermore, the intention of this document is to keep you aware of the downsides that come with using mocks.

Mocks might indicate your class is not well-designed

In a well-designed and testable system, it is relatively easy to isolate individual classes or modules and distinguish them between the components that contain the core business logic, which should be extensively unit tested, and the portions responsible for interfacing with the external environment and generating side effects. These side-effect-prone elements should be substituted in the unit tests. In fact, it is advisable to perform integration testing since their primary purpose is to abstract and facilitate the replacement of side effects in tests.

This kind of abstraction follows when you apply the principles of Domain Driven Design and Hexagonal Architecture (aka Ports & Adapters). I've written in more detail about those architectural considerations in my previous post.

The absence of such abstraction in an existing codebase is one of the reasons why it can be quite hard to write "good" unit tests.

So, a heavy reliance on mocks when writing unit tests can indicate a potential issue with the software design, suggesting insufficient encapsulation. Hence, designing code to promote better encapsulation and reduce the need for extensive mocking is advisable. This can lead to improved testability and overall software quality.

Better options than mocks

There are better options, but that depends on the use cases. Here are a few alternatives:

Use the real implementation (this means the real dependency is easy to create and does not produce side effects)
Use a hand-crafted dummy implementation of the real dependency, that is easy to configure and behaves like a stub in that use case (this means that the real dependency probably needs to be designed in a way to be easy to replace)
Fallback to using a mocking framework (when the real dependency is not designed to be replaced easily)

The way you design your codebase directly impacts whether you can rely on option 1 or option 2 without resorting to heavy mocking.

Conclusion: Write tests first!

When you write tests first, most of the points described above should come out of the box!

Nobody who starts with a test would start with configuring a mock.

While we provide insights on this, it is essential to validate the information. So we encourage you to explore the following references to gain a deeper understanding and form your own opinion.

References

Frank De Jonge on the exact same topic (with more examples in PHP): https://blog.frankdejonge.nl/testing-without-mocking-frameworks/

Martin Fowler on the differences between mocks (option 3) and stubs (option 2): https://martinfowler.com/articles/mocksArentStubs.html

Presentation by Mathias Noback on testing hexagonal architectures: https://matthiasnoback.nl/talk/a-testing-strategy-for-hexagonal-applications/

Some good real-life examples on unit tests in php: https://github.com/sarven/unit-testing-tips

A great write-up on testing in general: https://dannorth.net/2021/07/26/we-need-to-talk-about-testing/

Quite an old (1997!) paper on how not to use code coverage: http://www.exampler.com/testing-com/writings/coverage.pdf

Great blog post series on how to avoid mocks: https://philippe.bourgau.net/categories/#how-to-avoid-mocks-series

Benefits of separating core code from infrastructure code

Jonas Elfering — Thu, 31 Aug 2023 12:54:00 +0000

When it comes to software design and software architecture, there are many theoretical approaches with fancy acronyms (like SOLID, CUPID, DDD, hexagonal architecture, clean architecture, …). However, it is not always easy to translate these concepts into the practical world, and it is not clear where they overlap or not. Therefore, it's important to think about the practices all academic design patterns have in common and start from first principles. One really concrete practice that is encouraged by almost all software design flavors is the separation of core and infrastructure code. This post will explore many of the benefits and challenges through a real-life, practical example, so that by the end you will have a better understanding of how and why any software system might implement this tenant of sustainable architecture.

What is core and what is infrastructure code anyways?

Every software system consists of core and infrastructure code. Infrastructure code, in simple terms, is the code that connects the main business logic (core code) to the outside world (e.g. to the web server or database). For a definition of core code, we can refer to Matthias Noback's book “Advanced Web Application Architecture”:

Rule 1:
Core code doesn’t directly depend on external systems, nor does it depend on code written for interacting with a specific type of external system.
Rule 2:
Core code doesn’t need a specific environment to run in, nor does it have dependencies that are designed to run in a specific context only.

A common symptom of weak software design is if, at the code level, it is difficult to distinguish between the two. This lack of separation reflects a web of dependencies that create a host of issues, all of which we will gradually walk through with the example, below.

For the purpose of this blog post, Infrastructure code should not be confused with “Infrastructure as Code” (the code needed to spin up the server/cloud infrastructure that the application runs on).

An example

Consider the following Symfony controller used to post a new review by a customer for a given product:

#[Route(path: '/store-api/product/{productId}/review', methods: ['POST']]
public function save(
    string $productId, 
    RequestDataBag $data, 
    SalesChannelContext $context
): NoContentResponse {
    /** @var CustomerEntity $customer */
    $customer = $context->getCustomer();
    $customerId = $customer->getId();

    if (!$data->has('name')) {
        $data->set('name', $customer->getFirstName());
    }

    if (!$data->has('lastName')) {
        $data->set('lastName', $customer->getLastName());
    }

    $data->set('customerId', $customerId);
    $data->set('productId', $productId);

    $this->validate($data, $context->getContext());

    $review = [
        'productId' => $productId,
        'customerId' => $customerId,
        'externalUser' => $data->get('name'),
        'content' => $data->get('content'),
        'points' => $data->get('points'),
        'status' => false,
    ];

    if ($data->get('id')) {
        $review['id'] = $data->get('id');
    }

    $this->repository->upsert([$review], $context->getContext());

    $this->eventDispatcher->dispatch(
        new ReviewFormEvent($productId, $customerId, $data, $context)
    );

    return new NoContentResponse();
}

The code is rather straight forward to read: the controller accepts some data, fills in some fall-back data based on the customer currently logged-in, validates the input, saves the review to the database and dispatches a domain event. In a nutshell, this controller does too much at once. Through the course of this post, we will use this example to study the problems this can cause, and gradually refactor it to illustrate how separating the core code from infrastructure code inherently minimizes these issues or resolves them entirely.

Evolve infrastructure and core independently

Over time, your understanding of the underlying domain you are working in will improve, and you naturally will update your business logic to reflect this learning. In the best case, you want to have a single place where this knowledge is stored. On the other hand, if you want to grow your business, there may be other use cases where you want to provide the same business functionality (posting reviews) in different contexts. So there is a need for the infrastructure code and the core code to be able to evolve independently.

Reusability

In the controller example above, one can easily imagine that a new business requirement may arise that a merchant should be able to bulk import reviews from an existing review system. In the current implementation, this is not easily possible, because all the code is in a single place and it is not really reusable. In this scenario, the same business rules should apply, and the same domain events should be dispatched, because for the core domain logic, it is probably not that important from which source a new review was posted. Instead of copy & pasting a bunch of code to make the new use case work, the better option would be to separate the domain logic that is responsible for posting a review from the controller that provides that functionality over an HTTP-API.

So our code may now look like this:

#[Route(path: '/store-api/product/{productId}/review', methods: ['POST'])]
public function save(
    string $productId, 
    RequestDataBag $data, 
    SalesChannelContext $context
): NoContentResponse {
    /** @var CustomerEntity $customer */
    $customer = $context->getCustomer();
    $customerId = $customer->getId();

    if (!$data->has('name')) {
        $data->set('name', $customer->getFirstName());
    }

    if (!$data->has('lastName')) {
        $data->set('lastName', $customer->getLastName());
    }

    $data->set('customerId', $customerId);
    $data->set('productId', $productId);

    $this->postProductReviewService->post($data, $context->getContext());

    return new NoContentResponse();
}

class PostProductReviewService
{
    public function post(RequestDataBag $data, Context $context): void
    {
        $this->validate($data, $context);

        $review = [
            'productId' => $data->get('productId'),
            'customerId' => $data->get('customerId'),
            'externalUser' => $data->get('name'),
            'content' => $data->get('content'),
            'points' => $data->get('points'),
            'status' => false,
        ];

        if ($data->get('id')) {
            $review['id'] = $data->get('id');
        }

        $this->repository->upsert([$review], $context);

        $this->eventDispatcher->dispatch(
            new ReviewFormEvent($productId, $customerId, $data, $context)
        );
    }
}

With that structure in place, it is now rather easy to implement the “Bulk Import Reviews” functionality, by reusing the extracted service.

Note: The new core service still expects a RequestDataBag parameter, which is not optimal but will be tackled further down.

This refactoring step also greatly helps in cases when there comes a requirement for additional validation, that a customer actually has purchased the product in the past before the review is saved. After the refactoring, there is a single place where that logic can be added and we can evolve the core code independently from the infrastructure.

Switching the underlying technology

Another case where infrastructure code may change but the core code should not be affected is when there is the need to switch the underlying technology. There is much talk about being able to (theoretically) switch the whole data storage layer for the complete application without affecting the core code. I have to admit that I have never seen that work out in real life, and I think that these kinds of replacements should not be our end goal, as such an application probably would be over-engineered. But the possibility to switch out underlying technology for specific parts of the application without having to touch the rest of the system can be a sweet spot.

Back to our code example, perhaps some requirement arises where product reviews should not be saved in the relational database, but rather posted to an external review system that should be integrated. To make this change easier, the code that actually takes care of saving the data should be extracted from the core service (as that is actually infrastructure code) and an interface should be introduced, so that the core service only relies on the interface.

The code could be refactored like this:

class PostProductReviewService
{
    public function post(RequestDataBag $data, Context $context): void
    {
        $this->validate($data, $context);

        $this->productReviewGateway->postReviewByCustomer($data, $context);

        $this->eventDispatcher->dispatch(
            new ReviewFormEvent($data->get('productId'), $data->get('customerId'), $data, $context)
        );
    }
}

interface ProductReviewGateway
{
    public function postReviewByCustomer(RequestData $data, Context $context): void;
}

class DalProductReviewDataGateway implements ProductReviewGateway
{
    public function postReviewByCustomer(ProductReviewPostData $data, ProductReviewStatus $status, Context $context): void
    {
        $review = [
            'productId' => $data->get('productId'),
            'customerId' => $data->get('customerId'),
            'externalUser' => $data->get('name'),
            'content' => $data->get('content'),
            'points' => $data->get('points'),
            'status' => false,
        ];

        if ($data->get('id')) {
            $review['id'] = $data->get('id');
        }

        $this->repository->upsert([$review], $context);
    }
}

The fact that we use the Shopware DAL to store the reviews is now an implementation detail. We can easily change that storage layer without having to touch the core business logic.

Caveat: Finding the right abstractions

When creating abstractions to hide technical decisions from the consumer of that code, a major challenge is defining the right level of abstraction.

On the one hand, it is easy to create an “abstraction” that is too specific and tightly coupled to the implementation by leaking technical details as part of the interface. This leads to a situation where even if there is an abstraction in place, it is not possible to switch the actual implementation without breaking the abstraction.

On the other hand, it might also happen that abstractions are too generic. If that is the case, then clients of the abstraction have to implement solutions for common cases that are actually better solved by the implementation of that abstraction.

So finding the right level of abstraction is always a trade-off between either too specific or too general.

Testability

Being able to easily write unit tests for your mission critical business logic is a prerequisite in order to deliver high-quality software. If the infrastructure and the core code are not separated, it is hard to write these unit tests, as basically the whole system has to be in place in order to perform them. Looking back at the original single controller example from the beginning, in order to write a test for that piece of code, a database needs to be set up, the Shopware DAL needs to be functional, which means that the Symfony container must be set up properly, and you have to fake a request in order for the tests to run at all.

We can already see that the refactoring we made in order to evolve the infrastructure separately from the core code already improves testability a lot, as we can now test the infrastructure code and the core code separately. The core code is especially easier to test, as we don’t need to have a running database and the Symfony container set up anymore; instead, we can use a Mock or dummy implementation of our ProductReviewGateway interface. The only thing that makes unit testing of our core code (the PostProductReviewService) harder than it needs to be is the dependency on an HTTP-Request in the form of the RequestDataBag argument. In order to make it easier to test, we can define a DTO that encapsulates the actual parameters that our service needs.

class ProductReviewPostData
{
    private function __construct(
        private string $productId,
        private string $customerId,
        private string $name,
        private string $content,
        private int $points,
    ) {
    }

    public static function fromRequestData(
        string $productId,
        string $customerId,
        RequestDataBag $data,
    ): self {
        return new self(
            $productId,
            $customerId,
            $data->get('name'),
            $data->get('content'),
            $data->get('points'),
        );
    }
}

This DTO object can in itself be easily unit tested, and the adjusted service is now also easier to test:

class PostProductReviewService
{
    public function post(ProductReviewPostData $data, Context $context): void
    {
        $this->validate($data, $context);

        $this->productReviewGateway->postReviewByCustomer($data, $context);

        $this->eventDispatcher->dispatch(
            new ReviewFormEvent($data->getProductId(), $data->getCustomerId(), $data, $context)
        );
    }
}

Not only is the service now easier to test, but it is also easier to consume the service API as the expected input parameters are now well defined in the DTO, and there is no need anymore to guess the parameters and their names based on the implementation. Additionally, the type system gives us some simple validation for free, like validating required and optional parameters as well as their basic types.

The controller now looks like this:

#[Route(path: '/store-api/product/{productId}/review', methods: ['POST'])]
public function save(
    string $productId, 
    RequestDataBag $data, 
    SalesChannelContext $context
): NoContentResponse {
    /** @var CustomerEntity $customer */
    $customer = $context->getCustomer();
    $customerId = $customer->getId();

    if (!$data->has('name')) {
        $data->set('name', $customer->getFirstName());
    }

    if (!$data->has('lastName')) {
        $data->set('lastName', $customer->getLastName());
    }

    $postData = ProductReviewPostData::fromRequestData($productId, $customerId, $data);

    $this->postProductReviewService->post($postData, $context->getContext());

    return new NoContentResponse();
}

The influence on complexity

In order to keep a system in a state where it can be easily changed and evolved based on current needs, it is essential to keep the complexity of the overall system low. In general, the more things the system does, the more complex it becomes, but separating core from infrastructure code will help to keep complexity minimal. To see how many different things our original code does, we can separate it into the following “concerns”:

How are the HTTP-Request parameters transformed so our application can handle them? (Infrastructure concern)
What business rules apply when a product review is posted? (Core concern)
How is a product review stored in a persistent storage? (Infrastructure concern)

Our initial code handled all three concerns at the same time. That means when you want to understand how one of those concerns is solved, the code related to the other concerns is in fact adding complexity, which makes the part of the code you are actually interested in harder to understand. By separating out the concerns and handling them separately, it is easier to focus on one of the concerns without having to care how the others are solved; the level of complexity is reduced to a minimum.

We can even improve our code a little bit further by moving the fallback handling (which gets the name from the currently logged-in customer) to where the rest of the DTO is created to have that in a single place as well. So the code might look like this:

#[Route(path: '/store-api/product/{productId}/review', methods: ['POST'])]
public function save(
    string $productId,
    RequestDataBag $data, 
    SalesChannelContext $context
): NoContentResponse {
    /** @var CustomerEntity $customer */
    $customer = $context->getCustomer();

    $postData = ProductReviewPostData::fromRequestData($productId, $customer, $data);

    $this->postProductReviewService->post($postData, $context->getContext());

    return new NoContentResponse();
}

class ProductReviewPostData
{
    private function __construct(
        private string $productId,
        private string $customerId,
        private string $name,
        private string $content,
        private int $points,
    ) {
    }

    public static function fromRequestData(
        string $productId,
        CustomerEntity $customer,
        RequestDataBag $data,
    ): self {
        $name = $data->get('name') ?? $customer->getFirstName();
        $lastName = $data->get('lastName') ?? $customer->getLastName();

        return new self(
            $productId,
            $customer->getId(),
            $name,
            $data->get('content'),
            $data->get('points'),
        );
    }
}

With that refactoring, it’s now obvious we added a lastName field to the request based on the logged-in user, in case it was not provided by the client. But we actually never used lastName anywhere when storing the review; the product review does not distinguish between first and last names, and has only one name field. So in the original code, there lay a bug in plain sight, but it was hidden by all the accidental complexity surrounding it. By separating the different concerns, the bug becomes obvious and easy to fix.

class ProductReviewPostData
{
    private function __construct(
        private string $productId,
        private string $customerId,
        private string $name,
        private string $content,
        private int $points,
    ) {
    }

    public static function fromRequestData(
        string $productId,
        CustomerEntity $customer,
        RequestDataBag $data,
    ): self {
        $name = $data->get('name') ?? ($customer->getFirstName() . ' ' . $customer->getLastName());

        return new self(
            $productId,
            $customer->getId(),
            $name,
            $data->get('content'),
            $data->get('points'),
        );
    }
}

Improvements in collaboration

Another big benefit of separating core code from infrastructure code is that it can help you improve the collaboration with the non-engineers in your team, be it QA, designers or the people from the business side. When you separate the infrastructure-related code from the core code, it is way easier to see how the business rules for your application are implemented and if they match what the domain experts would expect. In the example case, some of the most interesting parts of the code are quite hidden in the $this->validate($data, $context) call. That method currently looks like this:

public function validate(ProductReviewPostData $data, Context $context): void
{
    $definition = new DataValidationDefinition('product.create_rating');

    $definition->add('name', new NotBlank());
    $definition->add('content', new NotBlank(), new Length(['min' => 40]));
    $definition->add('points', new GreaterThanOrEqual(1), new LessThanOrEqual(5));

    $criteria = new Criteria();
    $criteria->addFilter(new EqualsFilter('customerId', $this->customerId));
    $criteria->addFilter(new EqualsFilter('productId', $this->productId));

    // ensure that the customer can only post one review per product
    $definition->add('id', new EntityNotExists([
        'entity' => 'product_review',
        'context' => $context,
        'criteria' => $criteria,
    ]));

    $this->validator->validate($data, $definition);
}

The code uses the Symfony validator component to perform the validation. The first part of the validation is rather straightforward: it performs some basic consistency checks on the data, e.g. that the name is filled, that the content of the review is at least 40 characters long and that the rating points are between one and five. With the new code structure, it would probably be best to move this part of the validation to the DTO object itself, so that it is not even possible to create a DTO that is invalid. One can still use the Symfony validator or perform those checks manually in the constructors.

But the more interesting part is the last part of the code. There it uses some Shopware DAL magic to validate that the customer has not already reviewed the same product. This is a core business rule that should be enforced, but for now it is quite hidden in the validation code. To bring it into plain sight, we want to move this check into the body of the service, as that method should read like a workflow of what happens when a review is posted. To do so, we first create a new Interface for this kind of check, as only the Infrastructure layer can provide the information we need in the service, but those two layers should be kept separate. The interface might look like this:

interface ProductReviewConstraints
{
    public function hasCustomerAlreadyReviewedProduct(
        string $productId, 
        string $customerId, 
        Context $context
    ): bool;
}

And the implementation using the Shopware DAL might look like this:

class DALProductReviewConstraints
{
    public function hasCustomerAlreadyReviewedProduct(
        string $productId, 
        string $customerId, 
        Context $context
    ): bool {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('productId', $productId));
        $criteria->addFilter(new EqualsFilter('customerId', $customerId));

        return $this->productReviewRepository->searchIds($criteria, $context)->firstId() !== null;
    }
}

The business rule that says a customer can only post a review for a product once is now more obvious in the domain flow:

class PostProductReviewService
{
    public function post(ProductReviewPostData $data, Context $context): void
    {
        if ($this->reviewConstraints->hasCustomerAlreadyReviewedProduct(
            $data->getProductId(),
            $data->getCustomerId(),
            $context
        )) {
            throw new CustomerAlreadyReviewedProductException($data->getCustomerId(), $data->getProductId());
        }

        $this->productReviewGateway->postReviewByCustomer($data, $context);

        $this->eventDispatcher->dispatch(
            new ReviewFormEvent($data->getProductId(), $data->getCustomerId(), $data, $context)
        );
    }
}

With a structure like that, it is easy to discuss with other peers if we actually implemented the requirements the right way or if there is something missing. It is easy to spot that there is no check in place whether the customer actually bought that product or not, so it can spark discussions about whether and how to add such an additional check.

Conclusion: Keep infrastructure code at the boundaries of your codebase

The code as we left it at the end of this post is by no means perfect, but it is a perfect starting point for further refactoring based on the advanced architecture patterns mentioned in the beginning (DDD, hexagonal architecture, clean architecture, …). For example, proponents of DDD probably would refactor the service in a way to encapsulate the business logic inside a rich domain model and not let it stay directly in the service itself. But especially in DDD, you also don’t want any outside dependencies in your domain model, so it’s a necessary step to first separate your core code from the infrastructure code.

By now, this example walkthrough should already explain a lot of the benefits of separating the two. It makes it easier to interact with and evolve the codebase for you and your peers even when the requirements or the technology might considerably change. Ultimately, this is a general pattern that should be applied regardless of the architecture you have in place in your application, as it lays a concrete foundation for quality, sustainability and, dare I suggest, pleasure to work within your codebase.