Für eigene GraphQL-Queries reicht kein isoliertes File - es braucht ein reguläres Magento-2-Modul mit Registrierung, module.xml und Abhängigkeitsdeklaration. Dieses Kapitel legt das Grundgerüst für ein Warm-up-Modul Mironsoft\GraphqlDemo an, das Block 2 und 3 begleitet - Block 4 startet danach mit einem eigenen, durchgehenden Projekt (dem Veranstaltungen-Modul Mironsoft\Event).

Modul-Grundgerüst

app/code/Mironsoft/GraphqlDemo/
├── registration.php
└── etc/
    ├── module.xml
    └── schema.graphqls

<?php

declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Mironsoft_GraphqlDemo',
    __DIR__
);

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Mironsoft_GraphqlDemo">
        <sequence>
            <module name="Magento_GraphQl"/>
            <module name="Magento_CatalogGraphQl"/>
        </sequence>
    </module>
</config>

Die <sequence> ist kein Zufall: Magento_GraphQl liefert die Basis-Typen (Query, Mutation) sowie die @resolver-Direktive selbst - ohne diese Abhängigkeit lädt Magento das eigene Schema unter Umständen, bevor die Basistypen existieren. Magento_CatalogGraphQl ist hier zusätzlich eingetragen, weil Block 3 den Produkttyp erweitert - wer nur eigene, unabhängige Typen deklariert, kommt auch ohne diese zweite Abhängigkeit aus.

schema.graphqls leer anlegen

Die Datei selbst darf zunächst leer bleiben oder nur einen Kommentar enthalten - wichtig ist an dieser Stelle nur, dass Magento sie überhaupt einliest. Ein kompletter Neustart des Schema-Caches ist nach jeder Änderung an schema.graphqls Pflicht, da das zusammengeführte Schema gecacht wird:

bin/magento module:enable Mironsoft_GraphqlDemo
bin/magento setup:upgrade
bin/cache-clean config

Den Cache-Workflow verinnerlichen

Dieser Ablauf begleitet die komplette restliche Serie, deshalb hier einmal explizit: schema.graphqls-Änderungen brauchen keinen setup:di:compile-Lauf (es handelt sich nicht um generierten PHP-Code), aber immer einen Cache-Clean. In der Entwicklungsumgebung mit aktiviertem Hyvä-Watcher genügt bin/cache-clean config; bei hartnäckigen Fällen hilft bin/magento cache:flush als Holzhammer.

Mit dem Modul-Grundgerüst steht die Basis. Kapitel 5 füllt schema.graphqls erstmals mit echtem Inhalt: einer ersten eigenen Query samt Resolver.