Shopware 6 changes since the academy training videos

I tried to resume my Shopware side projects only to find out that my current development setup has become deprecated! And I'm not the only one.

On the verge of the Shopware 6.6 release

Shopware is an open-source/freemium e-commerce software. Their online academy courses are free. You only have to pay to take the exam. However, most of the current training videos are based on early versions of Shopware 6. On the verge of the 6.6 release in 2024, I need a selective changelog!

jump to the changelog section

Apart from many deprecations, there are new features and more Symfony standards like autowiring available now. Check out Symfony Dependency Management and theme guide: adding snippets.

What has changed since the tutorial videos

I will try to summarize some of the changes since, I don't know, Shopware 6.0 or Shopware 6.1, compared to the current 6.5 and the upcoming Shopware 6.6 release. I don't remember every detail mentioned in the videos I've watched, so my selection might be a little random. If you read this article in 2024, some things might already have changed again. Shopware released newer videos on YouTube, but I'm talking about these classics:

There are some more public videos and workshop recaps in the online academy, and the official shopwareknowledge channel has more up-to-date information, also linked from the respective documentation articles.

The academy course still shows the original course videos.
I still recommend watching those videos, at least as an inspiration.
But most importantly, you must set up Shopware and make things work to prevent tutorial hell and gain experience!

I also recommend watching Ramona Schwering's talks about end-to-end testing as it should be - Introduction to Cypress (Symfony UK meetup 2020), composable frontends #SCD23 (Shopware Community Day 2023] and Martina Linnemann's Communication is a two-way street about improving open-source community collaboration (Shopware Community Day 2023).

Symfony and Shopware tutorial talks

Alternative ways for setting up Shopware 6

Shopware officially documents two alternative setup approaches:
Dockware (maintained by a third party) and Shopware devenv.

The latter one is based on nix OS using Symfony flex recipes and PHP packagist composer. The flex devenv should work cross-platform on Linux, Windows, and Mac. "The main difference [of devenv/nixOS] to other tools like Docker or a VM is that it neither uses containerization nor virtualization techniques. Instead, the services run natively on your machine."

"Devenvifying" an existing Shopware application?

Do we want to use the new nix-based environment that promised stable cross-platform setups without virtualization? At least we could give it a try.

What might sound confusing if we do: the docs say that if you already have the SW flex template, require the composer package to get a basic devenv config. So what should I do if I don't? Start an empty project from scratch? Install a flex template into it before proceeding with devenv? Is there a best practice to migrate an existing Shopware project based on the deprecated development template? This is probably what Shopware core developer shyim calls devenvify an existing application in his blog post devenv: Compose a Developer Environment easily for PHP with Nix.

To create a new Shopware project based on the flex template:
composer create-project shopware/production <project-name>

Creating the project emits a lot of additional deprecation warnings when run in the IDE console. That might be a PHP version issue. But I am missing at least one local PHP extension.

"Impossible situation" without Docker?

At this point, I am tempted to choose Docker/Dockware again, but someone advised me not to give up on Nix just yet. To rule out additional problems caused by PhpStorm console, I will delete the new directory, install and activate GD and have another go in my regular bash terminal.

sudo apt install php8.2-gd

Some packages could not be installed. This may mean that you have requested an impossible situation [...]
The following packages have unmet dependencies:
php8.2-gd : Depends: libgd3 (>= 2.3.3) but 2.3.0-2ubuntu2 is to be installed
E: Unable to correct problems, you have held broken packages.

Okay, after some googling and trial and error of seemingly obvious manual installation commands, composer still can't create the flex project directory. Now it whines about incompatible plugins and composer versions. What do we need a dependency manager for if it fails to manage dependencies?

Isn't this exactly the kind of situation that made more and more developers choose Docker? What a silly waste of time! 😠😡🤬 I'm a web developer, not a devOps enthusiast! So what about an alternative Dockware setup?

Alternative Dockware Setup 🐋📦💙

"Use it. Love it. Images built for every use case" sounds more promising. But which image should I choose? Dev? Play? Flex? Essentials?

The dockware/flex "is a perfect fit for any Symfony or Shopware project", as it comes "without any additional services like MySQL, Adminer, Mailcatcher" etc., while dockware/dev should be the best match "for instant coding" Shopware 6 customizations and plugins.

We can create a persistent development environment with docker-compose (not unlike the deprecated psh setup) as described in the Advanced Run Dockware documentation and the example files on GitHub. This runs the latest dev container with an additional explicit shared folder configuration mapping custom/plugins to the project src folder:

version: "3"

services:
  shop:
    container_name: shop
    image: dockware/dev:latest
    ports:
      - "22:22"     # ssh
      - "80:80"     # apache2
      - "443:443"   # apache2 https
      - "8888:8888" # watch admin
      - "9998:9998" # watch storefront proxy
      - "9999:9999" # watch storefront
      - "3306:3306" # mysql port
    volumes:
      - "./src:/var/www/html/custom/plugins"
    networks:
      - web
    environment:
      - XDEBUG_ENABLED=0

networks:
  web:
    external: false

Instead of psh.phar docker:start we can now use docker-compose up (-d, --build etc.), docker-compose stop and docker-compose down like in many other Docker-based web projects ...

... unless the SQL port is already in use. A relevant port lookup sudo netstat -tulpn | grep ':80\|:3306\|:6379' shows me I have a mysql daemon and a Mailhog service running. Maybe left over from trying to install the nix environment? I can stop and disable the obsolete database with sudo systemctl stop mysql && sudo systemctl disable mysql, but what about Mailhog? At least it does not conflict with the default dockware setup (yet).

The new shop runs on port 80 by default, so we can simply open http://localhost in our browser to see the demo store.

We will also see a new src folder where we can start developing plugins now, after adjusting write permissions or ownership, if necessary: sudo chmod ug+rwx src

You might notice something is missing no my screenshot, though. Where has the Symfony profiler toolbar gone?

Reactivating the Symfony profiler toolbar

No deprecation, but another regression: there is no more Symfony profiler toolbar after starting Shopware 6.5 in a dockware/dev:latest container (reproduced with Shopware 6.5.7.3, first mentioned in a forum post after upgrading to Shopware 6.5 by sh0p in the German Shopware 6 community forum: Symfony Profiler wird in Shopware 6.5 nicht angezeigt). Recommended solution:

• composer require --dev symfony/profiler-pack
• ensure that the .env file sets APP_ENV="dev"

Another gotcha: the composer command failed in my case due to an invalid line in my theme's composer.json that the theme commands didn't warn about. See: Theme create wizard generates invalid JSON. So if you create plugins or themes using the wizard, always check and edit the generated files before proceeding!

Getting Shopware running (again) locally is already the first point on my subjective selective changelog list:

Selective changelog since the academy videos

• devenv and dockware are the only officially supported development environments, don't use anything else!

• PHP 8: see the migrating from 7.x guide on php.net

• Shopware 6.5 supports PHP up to PHP 8.2. "The January update of 6.5 will allow PHP 8.3 installations." (shyim on Slack)

• "since 6.5 there is no psh.phar anymore. You can find the replacements in the bin folder just ./bin/watch-administration.sh and so on" (shyim)

• The permission system has changed shortly after the videos. Quoting myself:

  Adding an "Integration" for Insomnia with "Read" permissions can now be achieved at Settings -> System -> Users & Permissions by creating a new role admin_api_reader. If that's not documented and straightforward enough, there is a tab called "detailed privileges" that shows the technical names like acl_role, plugin, foo_log_entry etc.

• addExtension does not accept null as a second parameter anymore: Replacement for deprecated Shopware 6 addExtension method?

• EntityRepositoryInterface has been deprecated and should be replaced by EntityRepository according to SW 6.4.13.0 upgrade instructions

• The SalesChannelRepositoryInterface class is also deprecated. The EntityRepository and SalesChannelRepository are have been marked as final, to be able to release future optimizations more easily. (UPGRADE-6.4.md)

• AjaxModal route: @Captcha, @LoginRequired, @Acl, @ContextTokenRequired and @RouteScope annotations have been removed and replaced with Route defaults. (UPGRADE-6.4.md)

• \Shopware\Administration\Service\AdminOrderCartService was deprecated and removed. Use the newly added \Shopware\Core\Checkout\Cart\ApiOrderCartService instead. (UPGRADE-6.4.md)

• \Shopware\Storefront\Page\Address\Listing\AddressListingCriteriaEvent was deprecated and removed. Use the newly added \Shopware\Core\Checkout\Customer\Event\AddressListingCriteriaEvent instead. (UPGRADE-6.4.md)

• \Shopware\Storefront\Event\ProductExportContentTypeEvent was deprecated and removed. Use the newly added \Shopware\Core\Content\ProductExport\Event\ProductExportContentTypeEvent instead. (UPGRADE-6.4.md)

• Repository decorator type hints like MediaRepositoryDecorator, MediaThumbnailRepositoryDecorator, MediaFolderRepositoryDecorator, and PaymentMethodRepositoryDecorator must be changed to EntityRepository. (UPGRADE-6.4.md)

• MessageQueue wrapper around the Symfony messenger component is deprecated and removed in 6.5. Instead of using Shopware\Core\Framework\MessageQueue\Handler\AbstractMessageHandler, you should directly implement the \Symfony\Component\Messenger\Handler\MessageSubscriberInterface instead. (UPGRADE-6.4.md)

• SCSS files need to be imported explicitly by scss/base.css. They are no longer loaded automatically.(UPGRADE-6.4.md)

• $asset-path has been deprecated. Use $app-css-relative-asset-path instead, which is relative to the app.css that points to the asset folder. As a side effect, the fonts are now loaded from the theme folder instead of the bundle asset folder. This should work out of the box, because all assets of the theme are also copied into the theme folder. (UPGRADE-6.4.md)

• Twig template files for cart, checkout, and account details have been refactored and unified in favor of a new line item base template. (UPGRADE-6.4.md)

• Several twig blocks have been refactored, renamed and removed, respectively. (UPGRADE-6.3.md)

• <sw-simple-search-field> property changed from search-term to value. (UPGRADE-6.5.md)

• The \Shopware\Core\System\Snippet\Files\SnippetFileInterface is deprecated, please provide your snippet files in the right directory with the right name so Shopware can autoload them. (UPGRADE-6.3.md)

• The Sales Channel API has been deprecated in favour of the new Store API route base. (UPGRADE-6.3.md)

• API version 1 is no longer supported. (UPGRADE-6.3.md)

• Permissions can be configured in the SalesChannelContext. (UPGRADE-6.2.md)

• The usage of entity attributes in the shopware.entity.definition tag has been deprecated. Entity attributes must be removed. (UPGRADE-6.2.md)

• LongTextWithHtmlField has been deprecated, use LongTextField with an AllowHtml flag instead. (UPGRADE-6.2.md)

• Deprecated \Shopware\Core\Framework\Routing\RouteScopeInterface: use abstract class \Shopware\Core\Framework\Routing\AbstractRouteScope instead. (UPGRADE-6.2.md)

• \Shopware\Core\Framework\DataAbstractionLayer\EntityExtensionInterface has been removed. Extend from the abstract class \Shopware\Core\Framework\DataAbstractionLayer\EntityExtension instead. (UPGRADE-6.2.md)

• The usage of $connection->executeQuery() for write operations is deprecated, use $connection->executeUpdate() instead. (UPGRADE-6.2.md)

• \Shopware\Core\Checkout\Customer\SalesChannel\AccountService is deprecated. Use more specific sales channel services instead. (UPGRADE-6.2.md)

• Deprecated method getFields, use getStructuredFields instead. (UPGRADE-6.2.md)

• It is no longer possible to send requests against the sales-channel-api with the HttpClient. You have to use the StoreApiClient. (UPGRADE-6.2.md)

• With 6.6 the ProductListingFeaturesSubscriber is removed. The AbstractListingProcessor follows a more service oriented approach.

• Removed deprecated UrlGeneratorInterface interface, use AbstractMediaUrlGenerator instead to generate the urls for media entities (UPGRADE-6.6.md)

• Removed deprecated AbstractPathNameStrategy abstract class, use AbstractMediaPathStrategy instead to implement own strategies (UPGRADE-6.6.md)

• \Shopware\Core\Framework\Log\LoggerFactory will be removed. You can use monolog configuration to achieve the same results. (UPGRADE-6.6.md)

• ElasticsearchProductCustomFieldsMappingEvent will be replaced by Shopware\Elasticsearch\Event\ElasticsearchCustomFieldsMappingEvent, dispatched when creating a new Elastic Search index (UPGRADE-6.6.md)

• \Shopware\Core\Content\Product\DataAbstractionLayer\StockUpdater will be replaced by \Shopware\Core\Content\Product\Stock\OrderStockSubscriber (UPGRADE-6.6.md)

Please be aware that this list is incomplete and unordered! These are just some personal notes that I took for my own projects.
Always check out the official documentation!

Updates

More deprecations, updated in December 2023:

• bin/console theme:compile warns "User Deprecated ... UrlGenerator::getAbsoluteMediaUrl()" is deprecated"
  This seems to be uncritical and can safely be ignored by using bin/console theme:compile --no-debug for what I would have expected as default behaviour without a --verbose or similar switch (which bin/console theme doesn't have). Source: [Shopware theme commands returns error:E_USER_DEPRECATED` on StackOverflow](https://stackoverflow.com/questions/77584483/shopware-theme-commands-returns-error-e-user-deprecated).

• bin/build-storefront.sh also throws the above warning and does not seem to accept a --no-debug switch. Fix? No fix! Ignore!

Route annotations and app scripts

Another important change: backend routes (or any other non-public endpoints) should now use App Scripts, as explained in the Started Guide: Add an API Endpoint.

You can ignore what the old Academy tutorials say about route permissions. An up-to-date documentation is here: Plugins -> Administration -> Adding permissions

Route annotation syntax has changed as it did in Symfony, so @RouteScope(scopes={"api"}) becomes #[Route(defaults: ['_routeScope' => ['api']])] and other route annotations have to change accordingly.

Ironically, even the old Academy tutorial videos show a Shopware 6 documentation page announcing a "breaking change: route scopes added" in 2019. So I guess that constant change is maybe the only thing that will never change.

Accidental deprecations, bugfixes and answers

Some problems have since been fixed, and questions answered, so if you encounter a new deprecation warning or any other problem, don't hesitate to open an issue or a StackOverflow question.

• Replacement for deprecated Shopware EntityRepositoryInterface is also deprecated: has been fixed, it has now only @final.

• Shopware Update fails due to exhausted memory size caused by deactivating extensions: increase memory limit to recommended 512M.

Future feature roadmap and blog posts

Blog posts about upcoming releases like Shopware 6.6 RC will be available soon. What will happen under the hood? also cover planned deprecations and removals like

• Vue.js 2 will no longer be supported by the end of 2023
• Plugins that provide their own Webpack configuration need to be migrated to Webpack 5 API.
• Maria DB 10.11 minimum requirement.
• Redis 7.0 minimum requirement.
• Node 20 as minimum version.
• PHP 8.2 as minimum requirement.
• Symfony 7 upgrade.

but also Shopware-specific changes like

• Stock API changes (previously behind a feature flag)

and various planned removals of announced deprecations, experimental state and feature flags.

The Shopware roadmap has sections for ongoing, next, future, and released features. We can find more details of the imminent 6.6 release in UPGRADE-6.6.md on GitHub. If you read this article in 2024, you will hopefully find similar detailed announcements for future releases beyond Shopware 6.6.

Research and debug

I believe that we should always prefer official documentation, but researching and debugging can result in a deeper understanding, and it can help us find a quick answer if the documentation is incomplete or outdated. We can write log messages, dump variables, and use the Symfony profiler, which should be active in a development environment by default. We can even check out the Shopware platform core source code on GitHub!

Possible training tasks and considerations

After watching the training videos, we can delete our tutorial code and try to code something similar from scratch, i.e. create a Shopware 6 plugin using a controller to create a new public API endpoint to display custom content in the storefront. Add some custom styles and consider that plugin reviewers might install your plugin in a subdomain using an non-default locale like Dutch or Turkish, e.g. https://shopware.example.com/pazar/tr_TR/

Our code should be flexible enough to handle that situation.

Community knowledge

There is a lot of free training material to learn Shopware development basics:

• academy.shopware.com
• other public videos and workshops
• word of mouth (conference hallway talks)
• www.shopware.com (release notes and announcements)
• developer.shopware.com (also has an invite link to Slack)
• Shopware Slack community
• StackOverflow questions tagged as [shopware]
• forum.shopware.com (not deprecated, but not very active)

As Shopware (community edition) is mostly based on the Symfony framework, which is in turn based on PHP, we should also consider learning about the basics. That knowledge can also be useful for working with other frameworks. Check Symfonycasts, symfony.com, php.net.

I hope that collecting and sharing some publicly available information might be helpful for fellow developers. Feel free to add more stuff and ask questions in the comments section!