Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 30 ยท Practice and Review

Shopware Plugin Cheat Sheet

A quick Shopware 6 plugin reference: bin/console commands, plugin directory layout, service tags, Criteria snippets, event names and the pitfalls that cost the most time.

This page is a lookup table, not a lesson. When you cannot remember whether the command is plugin:refresh or plugin:update, which tag registers an entity definition, or how to write an OR filter, come here. Everything targets Shopware 6 and links back to the lesson that explains the idea. Names and flags can shift between minor versions, so run bin/console list and bin/console help <command> on your own installation when you need certainty.

Shopware cannot run on this site, so all commands, XML and PHP below are read-only. Two small runnable plain-PHP stand-ins at the end help with things that are easy to get wrong: the shape of the Admin API search body, and a linter for plugin naming rules. They are not Shopware code.

flowchart LR
    A["Need a command"] --> CLI["Commands table"]
    B["Need a file location"] --> FILES["Directory layout"]
    C["Need a tag or event"] --> TAGS["Tags and events"]
    D["Need a query"] --> CRIT["Criteria snippets"]
    E["Something is wrong"] --> PIT["Pitfalls"]

Jump to the section that matches what you are looking for.

bin/console commands

Run from the project root. Add -vvv for more detail on failures.

Task Command
List all commands bin/console list
Help for a command bin/console help plugin:install
Install a fresh system bin/console system:install --basic-setup
Create an admin user bin/console user:create
Find new plugins on disk bin/console plugin:refresh
Install and activate bin/console plugin:install --activate AcmeWishlist
Activate or deactivate bin/console plugin:activate AcmeWishlist / plugin:deactivate AcmeWishlist
Run a plugin update bin/console plugin:update AcmeWishlist
Uninstall (add --keep-user-data to keep data) bin/console plugin:uninstall AcmeWishlist
List plugins bin/console plugin:list
Clear the cache bin/console cache:clear
Run all pending migrations of a plugin bin/console database:migrate --all AcmeWishlist
Run destructive migrations bin/console database:migrate-destructive --all AcmeWishlist
Create a migration file bin/console database:create-migration -p AcmeWishlist --name CreateWishlistItem
Rebuild DAL indexes bin/console dal:refresh:index
Register scheduled tasks bin/console scheduled-task:register
Run due scheduled tasks once bin/console scheduled-task:run --no-wait
Consume the message queue bin/console messenger:consume async low_priority
Compile the theme bin/console theme:compile
Change a theme for a sales channel bin/console theme:change
Show a system config value bin/console system:config:get AcmeWishlist.config.maxItems
Set a system config value bin/console system:config:set AcmeWishlist.config.maxItems 50
Finish an update (migrations, assets) bin/console system:update:finish
Inspect a service bin/console debug:container acme_wishlist_item.repository
List event listeners bin/console debug:event-dispatcher product.loaded
List routes bin/console debug:router
Dump the entity schema bin/console framework:schema -s 'entity-schema' schema.json

Build scripts for the frontends live in bin/: build-administration.sh, build-storefront.sh, watch-administration.sh and watch-storefront.sh. In a Composer project they may be in a different folder, so check yours. A typical loop while developing: edit PHP, cache:clear, reload; edit services.xml or routes, cache:clear; change a migration, run database:migrate; change SCSS or JS, run the watcher or theme:compile. See Setting Up a Development Environment.

Plugin directory layout

TEXT
AcmeWishlist/
โ”œโ”€โ”€ composer.json                 type shopware-platform-plugin, extra.shopware-plugin-class
โ””โ”€โ”€ src/
    โ”œโ”€โ”€ AcmeWishlist.php          main class extends Shopware\Core\Framework\Plugin
    โ”œโ”€โ”€ Core/Content/...          definitions, entities, collections, routes
    โ”œโ”€โ”€ Subscriber/               event subscribers
    โ”œโ”€โ”€ ScheduledTask/            tasks and handlers
    โ”œโ”€โ”€ Migration/                MigrationStep classes (Migration<timestamp><Name>)
    โ””โ”€โ”€ Resources/
        โ”œโ”€โ”€ config/
        โ”‚   โ”œโ”€โ”€ services.xml      service definitions and tags
        โ”‚   โ”œโ”€โ”€ routes.xml        route imports
        โ”‚   โ””โ”€โ”€ config.xml        plugin settings shown in the admin
        โ”œโ”€โ”€ snippet/              translation JSON files
        โ”œโ”€โ”€ views/storefront/     Twig templates extending core templates
        โ””โ”€โ”€ app/
            โ”œโ”€โ”€ administration/src/main.js    admin entry point (Vue)
            โ””โ”€โ”€ storefront/src/               main.js and scss/base.scss

The main class and the composer.json entry must agree, or plugin:refresh will not find the plugin. See Your First Plugin and Plugin Structure and Lifecycle.

Service tags

Tags go inside a <service> element in services.xml: <tag name="..."/>.

Tag Used for
kernel.event_subscriber An event subscriber class
shopware.entity.definition (with entity="...") A DAL entity definition
shopware.entity.extension An entity extension
shopware.scheduled.task A scheduled task definition
messenger.message_handler A message handler (older versions; newer ones use the AsMessageHandler attribute)
console.command A CLI command
flow.action A Flow Builder action
controller.service_arguments A controller or route class that receives arguments

To decorate a core service, add decorates="CoreServiceId" to your service and inject the original with the .inner argument. See Services and the Dependency Injection Container.

Criteria snippets

PHP
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\ContainsFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsAnyFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\MultiFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\NotFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\RangeFilter;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Sorting\FieldSorting;

$criteria = new Criteria();                              // or new Criteria([$id1, $id2])

$criteria->addFilter(new EqualsFilter('active', true));
$criteria->addFilter(new EqualsAnyFilter('productNumber', ['SW-1', 'SW-2']));
$criteria->addFilter(new ContainsFilter('name', 'shirt'));
$criteria->addFilter(new RangeFilter('stock', [RangeFilter::GTE => 1]));
$criteria->addFilter(new NotFilter(NotFilter::CONNECTION_AND, [new EqualsFilter('active', false)]));
$criteria->addFilter(new MultiFilter(MultiFilter::CONNECTION_OR, [
    new EqualsFilter('manufacturer.name', 'Acme'),
    new EqualsFilter('manufacturer.name', 'Globex'),
]));

$criteria->addSorting(new FieldSorting('createdAt', FieldSorting::DESCENDING));
$criteria->setLimit(25);
$criteria->setOffset(0);
$criteria->setTotalCountMode(Criteria::TOTAL_COUNT_MODE_EXACT);

$criteria->addAssociation('manufacturer');
$criteria->addAssociation('cover.media');                // nested path

$result = $repository->search($criteria, $context);      // EntitySearchResult
$result->getEntities();  $result->first();  $result->getTotal();

$ids = $repository->searchIds($criteria, $context)->getIds();

$repository->create([[ 'id' => $id, 'name' => 'A' ]], $context);
$repository->update([[ 'id' => $id, 'name' => 'B' ]], $context);
$repository->upsert([[ 'id' => $id, 'name' => 'C' ]], $context);
$repository->delete([[ 'id' => $id ]], $context);

Use Context::createDefaultContext() in tests and Context::createCLIContext() in commands and tasks; in a storefront or Store API request use the context from the SalesChannelContext. The full story is in Reading and Writing with Repositories.

Event names

Event When it fires
product.loaded, product.written, product.deleted After the DAL loads, writes or deletes products (every entity has <entity>.loaded and so on)
ProductPageLoadedEvent (class name) The product detail page data is ready
CheckoutConfirmPageLoadedEvent (class name) The checkout confirm page data is ready
checkout.order.placed An order has been placed
checkout.customer.register / checkout.customer.login A customer registers or logs in
state_enter.order.state.<state> An order enters a state, for example completed
state_enter.order_transaction.state.<state> A payment transaction enters a state, for example paid

Page events are named after their class, so you subscribe with ProductPageLoadedEvent::class. List what is registered for an event with debug:event-dispatcher. See Subscribers and Core Events.

Common pitfalls

Symptom Likely cause
Plugin does not show up in the list composer.json class does not match the main class, or you forgot plugin:refresh
New service or route is ignored Cache not cleared, route file not imported, or the service is not public/tagged
Entity write fails on the first try Migration columns do not match the definition (check created_at and updated_at)
Required field error The payload key must be the property name (productId), not the column name (product_id)
Association is empty It was not added to the Criteria, or the foreign key lacks the version field
Everything slows down A subscriber runs queries per entity, or associations are loaded but unused
Scheduled task never runs No worker running, or the task was never registered
Storefront change not visible Theme not compiled, cache not cleared, or HTTP cache serving an old page
Customer data appears for others A personal page was publicly cached
Uninstall removes merchant data keepUserData was ignored
Update works locally, fails in production A destructive migration ran too early, or a column was assumed to exist

Two stand-ins to play with

The Admin API search body

The Admin API's search endpoint takes the same ideas as Criteria, written as JSON. Seeing the PHP array and the JSON side by side makes the format easy to remember. This builder only prints the body; it sends nothing, and it is not Shopware code.

PHP Building a search request body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Every PHP filter class has a JSON type (equals, equalsAny, contains, range, not, multi), and an empty associations entry ({}) means "load this association with default settings". See The Admin API and Integrations.

A naming linter

Many early failures are naming slips. This stand-in checks the rules that people forget: a plugin's composer.json has the right type and class entry, and a migration class name carries the same timestamp as its getCreationTimestamp() return value.

PHP Linting plugin names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The rules are real conventions of Shopware plugins; the linter itself is a stand-in written for this page.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command makes Shopware notice a plugin that you just copied into the plugins folder?

    plugin:refresh scans the plugin directory and updates the list. Install and activate come after it.
  2. 2. Which tag registers an entity definition with the DAL?

    The tag, with the entity attribute, makes the DAL create the repository for it.
  3. 3. In a Criteria, how do you express "A or B"?

    Separate filters are combined with AND. A MultiFilter with CONNECTION_OR groups alternatives.
  4. 4. Why should scheduled tasks be tested with a worker running?

    The scheduler puts a message on the queue. Without a consumer nothing handles it.

Summary

  • Know the lifecycle commands: plugin:refresh, plugin:install --activate, plugin:update, cache:clear, database:migrate.
  • Plugin code lives in src, with config, routes, views, snippets and frontend sources under src/Resources.
  • Tags connect your classes to the framework: subscribers, definitions, tasks, handlers, commands and flow actions.
  • Criteria combines filters with AND; use MultiFilter for OR and NotFilter for negation, and add only the associations you read.
  • Most "it does not work" moments are cache, registration, migration/definition mismatch or a missing worker.

Go back to the start of the track at What Is Shopware 6? whenever you want to refresh the big picture.