Using Symfony Bundles Instead of Plugins

This guide refers to some basic concepts of Shopware plugins also covered in the Plugin base guide. You may want to refresh your knowledge of Symfony's Bundle system.

INFO

Check out our Shopware Toolbox PHPStorm extension with useful features like autocompletion, code generation or guideline checks.

You might use a Symfony bundle instead of a plugin when:

• You do not need a plugin lifecycle
• You do not want Administration management
• You are building project-level customization
• You want pure Symfony integration

How Plugins extend bundles

Shopware plugins extend Symfony bundles and add:

• Plugin lifecycle (install, update, activate, uninstall)
• Automatic migration handling
• Asset building integration
• Administration management

Class hierarchy: Plugin → Shopware\Bundle → Symfony\Bundle

When to use a bundle

Use a pure Symfony bundle when:

• You are customizing a single project
• You want no plugin lifecycle
• You manage everything via Composer
• You do not distribute the extension

Project structure

How a typical Shopware 6 project structure looks when bundles are used:

project-root/
├── bin/
│   └── console
├── config/
│   ├── bundles.php
│   ├── packages/
│   └── services.yaml
├── public/
│   ├── index.php
│   └── bundles/
├── src/
│   └── YourBundleName/
│       ├── YourBundleName.php
│       ├── Migration/
│       │   └── Migration1234567890YourMigration.php
│       └── Resources/
│           ├── config/
│           │   ├── services.php
│           │   └── routes.php
│           ├── views/
│           │   └── storefront/
│           │       └── page/
│           └── app/
│               ├── storefront/
│               │   └── src/
│               └── administration/
│                   └── src/
├── var/
├── vendor/
├── composer.json
├── composer.lock
└── .shopware-project.yaml

The Bundle is typically placed in a project's src/ folder, which is the standard location for custom code. You still will need to register the bundle in the project's config/bundles.php file.

Choosing the right bundle class

There are two bundle classes you can choose from:

• Shopware\Core\Framework\Bundle: the Shopware bundle class, which extends the Symfony bundle class with additional features like acting as theme, bringing JavaScript/CSS files, and migrations
• Symfony\Component\HttpKernel\Bundle\Bundle: the Symfony bundle class, which you can use if you don't need additional features

Creating a bundle

By default, The namespace App\ is registered to the src folder in any Shopware project to be used for customizations. We recommend using this namespace. To change the project structure, change the App\ namespace in the project's composer.json file.

// <project root>/src/YourBundleName.php
<?php declare(strict_types=1);

namespace App\YourBundleName;

use Shopware\Core\Framework\Bundle;

class YourBundleName extends Bundle
{
}

The bundle class must be registered in the project's config/bundles.php file.

// <project root>/config/bundles.php
//...
App\YourBundleName\YourBundleName::class => ['all' => true],
//...

Adding services, Twig templates, routes, and themes

You can add services, Twig templates, routes, etc. to your bundle just as you would to a plugin. Create Resources/config/services.php and Resources/config/routes.php files, or Resources/views for Twig templates. The bundle will be automatically detected and the files will be loaded.

To mark your bundle as a theme, it's enough to implement the Shopware\Core\Framework\ThemeInterface interface in your bundle class. This will automatically register your bundle as a theme and make it available in the Shopware administration. You can also add a theme.json file to define the theme configuration like described here.

Adding migrations

Migrations are not automatically detected in bundles. To enable migrations, overwrite the build method in the bundle class:

// <project root>/src/YourBundleName.php
<?php declare(strict_types=1);

namespace App\YourBundleName;

use Shopware\Core\Framework\Bundle;

class YourBundleName extends Bundle
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $this->registerMigrationPath($container);
    }
}

As Bundles don't have a lifecycle, the migrations are not automatically executed. Execute them manually via the console command:

bin/console database:migrate <BundleName> --all

If you use Deployment Helper, you can add it to the .shopware-project.yaml file:

deployment:
    hooks:
        pre-update: |
            bin/console database:migrate <BundleName> --all

Integration into Shopware CLI

The Shopware CLI cannot detect bundles automatically. Therefore, bundle assets are not built automatically. Adjust the project's composer.json file to specify the path to the bundle. Do this by adding the extra section to the composer.json file:

{
    "extra": {
        "shopware-bundles": {
          "src/<BundleName>": {
            "name": "<BundleName>",
          }
        }
    }
}

This will tell Shopware CLI where the bundle is located and its name.

Next steps

Now that you know about the differences between a Symfony bundle and a Shopware plugin, review the following guides:

• Dependency Injection
• Listening to events

Also check out these useful videos:

• Bundle Methods in a plugin
• Symfony services in Shopware 6
• The free online training "Shopware 6 Backend Development"