Shopware 6 changes since the academy training videos
Tags: webdev, php, shopware, learning
Published: 2023-12-12 14:37:17

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!

<a href="#thechanges">jump to the changelog section</a>

Apart from many deprecations, there are new features and more Symfony standards like [autowiring](https://symfony.com/doc/current/service_container/autowiring.html) available now. Check out [Symfony Dependency Management](https://developer.shopware.com/docs/resources/references/adr/2023-05-16-symfony-dependency-management.html#decision) and [theme guide: adding snippets](https://developer.shopware.com/docs/guides/plugins/plugins/administration/adding-snippets.html).

## 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:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/46to6haynyou09lrv6lu.png)

There are some more public videos and workshop recaps in the online academy, and the official [shopwareknowledge channel](https://www.youtube.com/@shopwareknowledge) has more up-to-date information, also linked from the respective documentation articles.

[![shopwareknowledge channel screenshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/emmrqplrlydrxw8gikj6.png)](https://www.youtube.com/@shopwareknowledge)

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](https://leichteckig.com)'s talks about [end-to-end testing as it should be - Introduction to Cypress](https://www.youtube.com/watch?v=4BPKVSWsolI) (Symfony UK meetup 2020), [composable frontends #SCD23](https://www.youtube.com/watch?v=hN3t96zVfpw) (Shopware Community Day 2023] and Martina Linnemann's [Communication is a two-way street](https://www.youtube.com/watch?v=DDwZRytti6w) about improving open-source community collaboration (Shopware Community Day 2023).

![Screenshot collage of the videos mentioned above by Ramona Schwering and Martina Linnemann](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pav2k107fonbus0jbo98.png)

Symfony and Shopware tutorial talks

## Alternative ways for setting up Shopware 6

Shopware officially documents two alternative setup approaches:
[Dockware](https://dockware.io/) (maintained by a third party) and [Shopware devenv](https://developer.shopware.com/docs/guides/installation/devenv.html).

The latter one is based on [nix OS](https://nixos.org) using [Symfony flex recipes](https://symfony.com/doc/current/quick_tour/flex_recipes.html) and [PHP packagist composer](https://packagist.org). 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."

![Shopware documentation screenshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ck4x2x0h7shcdt943iol.png)

### "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](https://shyim.me/blog/devenv-compose-developer-environment-for-php-with-nix/#devenvify-an-existing-application) in his blog post [devenv: Compose a Developer Environment easily for PHP with Nix](https://shyim.me/blog/devenv-compose-developer-environment-for-php-with-nix/).

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

![Screenshot: creating the project emits a lot of additional deprecation warnings.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/udvrsm807m5kq21r16gr.png)

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.

![Screenshot: installation stopped due to missing GD extension](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gsd77js523gw8nyogir1.png)

### "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](https://dev.to/ryuheechul/don-t-give-up-on-nix-just-yet-37mh). 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?](https://docs.dockware.io/setup/what-image-should-you-use) Dev? Play? Flex? Essentials?

The [dockware/flex](https://hub.docker.com/r/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](https://hub.docker.com/r/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](https://docs.dockware.io/use-dockware/advanced-run) Dockware documentation and the [example files on GitHub](https://github.com/dockware/examples). This runs the latest `dev` container with an additional explicit shared folder configuration mapping `custom/plugins` to the project `src` folder:

```yml
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 ...

![Screenshot: address already in use...](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0xfd2cl8vrbpa1vq7fkh.png)

... 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` 

![Screenshot: Shopware demo store and new source code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ioq2xm2cw0el5n0nz369.png)

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](https://forum.shopware.com/t/symfony-profiler-wird-in-shopware-6-5-nicht-angezeigt/99718)). 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](https://forum.shopware.com/t/theme-create-wizard-generates-invalid-json/102360). 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:

<a name="thechanges" id="thechanges"></a>
## Selective changelog since the academy videos

- [devenv](https://developer.shopware.com/docs/guides/installation/devenv.html) and [dockware](https://dockware.io/) are the only officially supported development environments, don't use anything else!

- PHP 8: see the  [migrating from 7.x](https://www.php.net/manual/en/migration80.deprecated.php) 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](https://shyim.me) 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?](https://stackoverflow.com/questions/72968625/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](https://github.com/shopware/platform/blob/v6.4.13.0/UPGRADE-6.4.md#internal-entity-repositories)

- 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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.4.md))

- Repository decorator type hints like `MediaRepositoryDecorator`, `MediaThumbnailRepositoryDecorator`, `MediaFolderRepositoryDecorator`, and `PaymentMethodRepositoryDecorator` must be changed to `EntityRepository`. ([UPGRADE-6.4.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.4.md))

- Several twig blocks have been refactored, renamed and removed, respectively. ([UPGRADE-6.3.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.3.md))

- `<sw-simple-search-field>` property changed from `search-term` to `value`. ([UPGRADE-6.5.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.3.md)) 

- The Sales Channel API has been deprecated in favour of the new Store API route base. ([UPGRADE-6.3.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.3.md))

- API version 1 is no longer supported. ([UPGRADE-6.3.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.3.md))

- Permissions can be configured in the SalesChannelContext.  ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.2.md))

- `LongTextWithHtmlField` has been deprecated, use `LongTextField` with an `AllowHtml` flag instead.  ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.2.md))

- Deprecated `\Shopware\Core\Framework\Routing\RouteScopeInterface`: use abstract class `\Shopware\Core\Framework\Routing\AbstractRouteScope` instead. ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.2.md))

- The usage of `$connection->executeQuery()` for write operations is deprecated, use `$connection->executeUpdate()` instead. ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.2.md))

- `\Shopware\Core\Checkout\Customer\SalesChannel\AccountService` is deprecated. Use more specific sales channel services instead. ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.2.md))

- Deprecated method `getFields`, use `getStructuredFields` instead. ([UPGRADE-6.2.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.6.md))

- Removed deprecated `AbstractPathNameStrategy` abstract class, use `AbstractMediaPathStrategy` instead to implement own strategies ([UPGRADE-6.6.md](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.6.md))

- `\Shopware\Core\Framework\Log\LoggerFactory` will be removed. You can use [monolog configuration](https://symfony.com/doc/current/logging/channels_handlers.html) to achieve the same results. ([UPGRADE-6.6.md](https://github.com/shopware/shopware/blob/trunk/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](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.6.md))

- `\Shopware\Core\Content\Product\DataAbstractionLayer\StockUpdater` will be replaced by `\Shopware\Core\Content\Product\Stock\OrderStockSubscriber` ([UPGRADE-6.6.md](https://github.com/shopware/shopware/blob/trunk/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](https://developer.shopware.com/docs/guides/plugins/apps/starter/add-api-endpoint.html).

You can ignore what the old Academy tutorials say about route permissions. An up-to-date documentation is here: [Plugins -> Administration -> Adding permissions](https://developer.shopware.com/docs/v6.3/guides/plugins/plugins/administration/add-acl-rules.html)

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.

![Academy video screenshot showing a 2019 deprecation page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gfsfco0odyhyouuaw8j1.png)

### 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](https://stackoverflow.com/questions/72921494/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](https://stackoverflow.com/questions/74358190/shopware-update-fails-due-to-exhausted-memory-size-caused-by-deactivating-extens): increase memory limit to [recommended 512M](https://docs.shopware.com/en/shopware-6-en/first-steps/system-requirements).

### 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?](https://www.shopware.com/en/news/shopware-6-6-rc/) 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](https://www.shopware.com/en/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](https://github.com/shopware/shopware/blob/trunk/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](https://docs.shopware.com/), 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](https://symfony.com/doc/current/profiler.html), which should be active in a development environment by default. We can even check out the [Shopware platform core source code](https://github.com/shopware/shopware/) 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](https://store.shopware.com/en/swag202243902344f/internationalization-turkey.html), 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](https://academy.shopware.com)
- other public videos and workshops
- word of mouth (conference hallway talks)
- [www.shopware.com](https://www.shopware.com/) (release notes and announcements)
- [developer.shopware.com](https://developer.shopware.com/docs/) (also has an invite link to Slack)
- [Shopware Slack community](https://app.slack.com/client/T011TTK0DMK/C011VFQT7GB)
- [StackOverflow questions tagged as `[shopware]`](https://stackoverflow.com/questions/tagged/shopware)
- [forum.shopware.com](https://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](https://symfonycasts.com), [symfony.com](https://symfony.com/), [php.net](https://www.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!