Die HTTP QUERY Methode in Shopware 6

1. Was RFC 10008 tatsächlich festlegt

Sicher, idempotent, cachefähig, mit Body

QUERY liegt bewusst zwischen GET und POST. Laut RFC "veranlasst" eine QUERY-Anfrage "das Ziel, den enthaltenen Inhalt sicher und idempotent zu verarbeiten". Praktisch bedeutet das:

• Sicher: eine QUERY-Anfrage darf den Serverzustand nicht verändern. Gleiche Garantie wie bei GET
• Idempotent: zweimal senden hat denselben Effekt wie einmal. Nach einem Timeout gefahrlos wiederholbar
• Cachefähig: ein Cache darf die Antwort speichern und wiederverwenden, der RFC verlangt aber, dass der Cache-Key den Request-Inhalt einbezieht, nicht nur die URI, da zwei QUERY-Anfragen an denselben Pfad völlig unterschiedliche Bodies tragen können
• Body-fähig: anders als GET hat eine QUERY-Anfrage einen definierten, strukturierten Body, meist JSON, genau richtig für verschachtelte Filter-/Sortier-/Aggregations-Payloads, die einen Query-String nicht überleben würden

Wie Symfony 7.4 es umsetzt

Symfony hat native QUERY-Unterstützung mit Version 7.4 eingeführt. Das wird tatsächlich in symfony/http-foundation ausgeliefert:

public function isMethodSafe(): bool
{
    return \in_array($this->getMethod(), ['GET', 'HEAD', 'OPTIONS', 'TRACE', 'QUERY'], true);
}

public function isMethodIdempotent(): bool
{
    return \in_array($this->getMethod(), ['HEAD', 'GET', 'PUT', 'DELETE', 'TRACE', 'OPTIONS', 'PURGE', 'QUERY'], true);
}

public function isMethodCacheable(): bool
{
    return \in_array($this->getMethod(), ['GET', 'HEAD', 'QUERY'], true);
}

Symfony behandelt QUERY beim Parsen der Anfrage auch wie PUT, DELETE und PATCH: der Body wird dekodiert und landet in derselben Parameter-Bag wie bei POST, nicht in der Query-String-Bag. Und in HttpKernel\HttpCache\Store hasht der eingebaute Reverse-Proxy-Cache-Simulator den Request-Body bereits in den Cache-Key für QUERY ein, genau wie es der RFC verlangt:

protected function generateCacheKey(Request $request): string
{
    $key = $request->getUri();

    if ('QUERY' === $request->getMethod()) {
        // add null byte to separate the URI from the body and avoid boundary collisions
        // which could lead to cache poisoning
        $key .= "\0".$request->getContent();
    }

    return 'md'.hash('sha256', $key);
}

2. Shopware 6.7.12+ liefert bereits Symfony 7.4 aus

Das wird oft falsch angenommen: dass QUERY einen Shim über Shopware braucht. Ein Blick in das tatsächliche composer.json im shopware/core-Tag v6.7.12.2 zeigt: die Framework-Schicht ist schon da.

"symfony/http-foundation": "~7.4.0",
"symfony/http-kernel": "~7.4.12",
"symfony/routing": "~7.4.12",

Das heißt: Request::METHOD_QUERY, die Safe-/Idempotent-/Cacheable-Flags und das QUERY-fähige Body-Parsing von oben sind in einer Standard-Shopware-6.7.12+-Installation bereits vorhanden. Auf Framework-Ebene ist nichts zu patchen. Symfony unterstützt es bereits. Offen ist nur, ob Shopwares eigener Code es auch nutzt.

3. Wo Shopwares Store API den alten GET/POST-Split noch zeigt

Shopwares Core-Route /store-api/search ist ein reales, lebendes Beispiel für genau die Spannung, die RFC 10008 auflösen soll. Hier die tatsächliche ProductSearchRoute.php aus dem Tag 6.7.12.2:

<?php declare(strict_types=1);

namespace Shopware\Core\Content\Product\SalesChannel\Search;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ProductSearchRoute extends AbstractProductSearchRoute
{
    #[Route(
        path: '/store-api/search',
        name: 'store-api.search',
        methods: [Request::METHOD_POST, Request::METHOD_GET],
        defaults: [
            PlatformRequest::ATTRIBUTE_ENTITY => ProductDefinition::ENTITY_NAME,
            PlatformRequest::ATTRIBUTE_HTTP_CACHE => true,
        ]
    )]
    public function load(Request $request, SalesChannelContext $context, Criteria $criteria): ProductSearchRouteResponse
    {
        // ...
    }
}

Betrachtet man das methods-Array zusammen mit dem Default ATTRIBUTE_HTTP_CACHE => true, ist die Absicht klar. GET wurde dieser Route gezielt hinzugefügt, um sie über Shopwares Reverse-Proxy cachefähig zu machen, denn CacheResponseSubscriber (mehr dazu in Abschnitt 5) markiert nur GET-Antworten als cache-berechtigt. POST bleibt im Array, weil eine Suche mit mehreren Filtern, einem Aggregationsblock und individueller Sortierung nicht zuverlässig in einen Query-String passt, und manche Proxies und CDNs lange URLs kürzen oder ablehnen.

Mit anderen Worten: Shopware fährt bereits denselben GET-für-Cache-POST-für-Payload-Workaround, den RFC 10008 ablösen soll. Core hat QUERY nur noch nicht übernommen.

Warum QUERY zur eigenen Route hinzuzufügen weniger Aufwand ist als gedacht

Shopwares Criteria-Auflösung fragt nicht "ist das POST?" Sie fragt "ist das GET, oder nicht?" Diese Unterscheidung ist entscheidend. Hier der tatsächliche Zweig in RequestCriteriaBuilder::handleRequest():

public function handleRequest(Request $request, Criteria $criteria, EntityDefinition $definition, Context $context): Criteria
{
    if ($request->isMethod(Request::METHOD_GET)) {
        // ...liest aus $request->query
        $criteria = $this->fromArray($request->query->all(), $criteria, $definition, $context);
    } else {
        // alles, was nicht GET ist, landet hier, auch QUERY
        $criteria = $this->fromArray($request->request->all(), $criteria, $definition, $context);
    }

    return $criteria;
}

Der else-Zweig liest aus $request->request, derselben Parameter-Bag, die Symfony 7.4 für QUERY-Bodies befüllt (siehe Abschnitt 1). Eine QUERY-Anfrage landet automatisch in diesem else-Zweig, weil sie kein GET ist. Kein Sonderfall nötig. RequestParamHelper::get(), das mehrere Multi-Methoden-Store-API-Routen zum Auslesen einzelner Parameter nutzen, hat dieselbe Form: erst $request->query prüfen, dann auf $request->request zurückfallen. Beide funktionieren bereits ohne Änderung mit QUERY.

4. QUERY zu einer Store-API-Route im Plugin hinzufügen

Eine Core-Route lässt sich nicht nachträglich um eine Methode erweitern, Dekoratoren ersetzen Service-Verhalten, nicht die Routing-Attribute der konkreten Klasse. Deshalb entsteht hier eine neue, dekorierbare Custom-Route nach Shopwares Standard-Abstract-Class-Pattern, dasselbe Muster, das auch bei der Plugin-Entwicklung zum Einsatz kommt, von Anfang an mit QUERY-Unterstützung. Es ist ein Produktsuch-Endpunkt, der sowohl POST (für Clients, die noch kein QUERY senden können) als auch QUERY (für Clients, die es können) akzeptiert.

Die abstrakte Klasse

<?php declare(strict_types=1);

namespace Elixent\QueryDemo\Core\Content\Product\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

abstract class AbstractProductQueryRoute
{
    abstract public function getDecorated(): AbstractProductQueryRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ProductQueryRouteResponse;
}

Die konkrete Route

<?php declare(strict_types=1);

namespace Elixent\QueryDemo\Core\Content\Product\SalesChannel;

use Shopware\Core\Content\Product\Aggregate\ProductVisibility\ProductVisibilityDefinition;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Content\Product\SalesChannel\ProductAvailableFilter;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\Framework\Routing\StoreApiRouteScope;
use Shopware\Core\PlatformRequest;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ProductQueryRoute extends AbstractProductQueryRoute
{
    public function __construct(
        private readonly EntityRepository $productRepository
    ) {
    }

    public function getDecorated(): AbstractProductQueryRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(
        path: '/store-api/product/query',
        name: 'store-api.product.query',
        methods: [Request::METHOD_POST, Request::METHOD_QUERY],
        defaults: [PlatformRequest::ATTRIBUTE_ENTITY => ProductDefinition::ENTITY_NAME]
    )]
    public function load(Criteria $criteria, SalesChannelContext $context): ProductQueryRouteResponse
    {
        $criteria->addFilter(
            new ProductAvailableFilter($context->getSalesChannelId(), ProductVisibilityDefinition::VISIBILITY_ALL)
        );

        $result = $this->productRepository->search($criteria, $context->getContext());

        return new ProductQueryRouteResponse($result);
    }
}

Das ist die gesamte Änderung gegenüber einer normalen POST-only-Store-API-Route: ein zusätzlicher Eintrag, Request::METHOD_QUERY, im methods-Array. Das Argument Criteria $criteria wird über CriteriaValueResolver und RequestCriteriaBuilder aufgelöst, genau wie in Abschnitt 3 gezeigt, unabhängig davon, welche der beiden Methoden der Client verwendet hat.

Testen

Das -X-Flag von curl sendet jede beliebige Methode, auch unbekannte, spezielles Tooling ist nicht nötig:

# Gleiche Route, POST-Fallback
curl https://ihr-shop.test/store-api/product/query \
  -X POST \
  -H "Content-Type: application/json" \
  -H "sw-access-key: IHR_SALES_CHANNEL_ACCESS_KEY" \
  -d '{"limit": 10, "filter": [{"type": "range", "field": "price", "parameters": {"lte": 50}}]}'

# Die tatsächliche QUERY-Methode
curl https://ihr-shop.test/store-api/product/query \
  -X QUERY \
  -H "Content-Type: application/json" \
  -H "sw-access-key: IHR_SALES_CHANNEL_ACCESS_KEY" \
  -d '{"limit": 10, "filter": [{"type": "range", "field": "price", "parameters": {"lte": 50}}]}'

Beide liefern eine identische Antwort, weil beide im else-Zweig von RequestCriteriaBuilder landen. Wird das aus JavaScript aufgerufen, behandelt fetch() es wie jede andere Methode auch:

const response = await fetch('/store-api/product/query', {
    method: 'QUERY',
    headers: {
        'Content-Type': 'application/json',
        'sw-access-key': accessKey,
    },
    body: JSON.stringify({ limit: 10 }),
});

5. Was noch nicht funktioniert: Shopwares HTTP-Cache

Symfonys HttpCache-Komponente kann bereits einen body-bewussten Cache-Key für QUERY bilden (Abschnitt 1). Das ist Symfonys Reverse-Proxy-Simulator, nicht die Schicht, die tatsächlich entscheidet, ob Shopware eine Antwort überhaupt als cachefähig markiert. Diese Entscheidung fällt in CacheResponseSubscriber, und die ist weiterhin fest auf GET verdrahtet:

if (!$request->isMethod(Request::METHOD_GET)) {
    $this->noCache($request, $response, $area);

    return;
}

Jede Antwort auf eine Nicht-GET-Anfrage, ob POST oder QUERY, bekommt hier unbedingt noCache(), noch bevor Shopwares eigene Cache-Policy-Logik überhaupt läuft. Eine QUERY-Route funktioniert korrekt. Sie ist nur nie für Shopwares Reverse-Proxy-Cache berechtigt, egal wie sicher oder idempotent die Anfrage ist.

Zwei ehrliche Optionen, bis Core nachzieht:

• Stattdessen am Edge cachen. Muss die Antwort heute wirklich gecacht werden, konfigurieren Sie CDN oder Reverse-Proxy (Varnish, Fastly, Cloudflare) so, dass für QUERY-Anfragen an diese spezifische Route der Request-Body in den eigenen Cache-Key einfließt, unabhängig von Shopwares interner Cache-Schicht.
• Auf Core warten. Da Shopware bereits die Symfony-Version ausliefert, die QUERY unterstützt, und die eigene /store-api/search-Route genau die Motivation dafür zeigt, ist native Unterstützung in CacheResponseSubscriber eine naheliegende, risikoarme Ergänzung für ein künftiges Release. Verfolgen Sie den Shopware-Changelog, statt gegen eine interne Klasse anzukämpfen.

6. Erst den Webserver prüfen, bevor Shopware verdächtigt wird

Kommt eine QUERY-Anfrage mit 405 zurück oder wird sie schon vor PHP-FPM verworfen, liegt die Ursache oft außerhalb von Shopware. Nginx-Konfigurationen enthalten häufig eine Methoden-Allowlist als Härtungsmaßnahme, etwa so:

# Ein verbreiteter Nginx-Härtungs-Snippet, der QUERY-Anfragen stillschweigend killt
if ($request_method !~ ^(GET|HEAD|POST|PUT|DELETE|OPTIONS)$) {
    return 444;
}

Diese Regel ist älter als RFC 10008, sie soll unbekannte Methoden als Schutzmaßnahme ablehnen, und QUERY ist einer Konfiguration von vor Juni 2026 schlicht unbekannt. Sind Plugin-Route und Symfony-Version geprüft, aber Anfragen scheitern trotzdem vor der Anwendung, prüfen Sie die Nginx- (oder Apache-, oder Caddy-)Konfiguration sowie WAF-/CDN-Regeln davor auf eine Methoden-Allowlist, die QUERY explizit ergänzt werden muss.