Magento-Modul-Boilerplate-Generatoren im Entwickleralltag

1. Warum Boilerplate-Generatoren die Modulqualität heben

Ein neues Magento-Modul braucht mindestens registration.php, module.xml, einen Vendor-Namespace und meist schon beim Start eine erste Klasse mit korrektem PHPDoc. Wer das jedes Mal von Hand tippt, macht früher oder später kleine Fehler: eine vergessene setup_version, ein falscher Modulname im Vergleich zum Ordnernamen, eine fehlende Abhängigkeitsdeklaration. Ein Boilerplate-Generator eliminiert diese Fehlerklasse vollständig, weil die Struktur immer aus derselben, geprüften Vorlage entsteht.

Der zweite Vorteil eines Boilerplate-Generators ist Konsistenz über das gesamte Team hinweg. Wenn jeder Entwickler seine eigene Vorstellung von Ordnerstruktur, Namespace-Konvention und PHPDoc-Ausführlichkeit mitbringt, entsteht mit der Zeit ein uneinheitliches Codebase-Bild. Ein zentral gepflegter Generator zwingt implizit alle Beteiligten auf dieselben Konventionen, ohne dass jedes Mal ein Style-Guide-Dokument konsultiert werden muss.

Dieser Artikel zeigt die verschiedenen Stufen von Boilerplate-Generatoren für Magento-2-Module: vom offiziellen CLI-Tool über eigene Composer-Templates bis zu PhpStorm Live Templates für einzelne Klassen wie Repositories und Plugins.

2. registration.php und module.xml: der Minimal-Boilerplate

Bevor ein Generator sinnvoll bewertet werden kann, muss klar sein, was der minimale, korrekte Boilerplate für ein Magento-Modul überhaupt enthält. registration.php registriert den Modulnamen und Pfad über ComponentRegistrar::register(), module.xml deklariert die setup_version und Abhängigkeiten zu anderen Modulen. Beide Dateien müssen exakt zueinander passen, sonst schlägt bin/magento module:enable mit einer schwer lesbaren Fehlermeldung fehl.

Ein häufiger Anfängerfehler beim manuellen Aufbau: Der Modulname in registration.php weicht vom Namen in module.xml ab, weil beim Kopieren einer bestehenden Datei eine Stelle übersehen wurde. Ein Boilerplate-Generator, der beide Dateien aus einer einzigen Eingabe (Vendor- und Modulname) ableitet, kann diese Diskrepanz strukturell gar nicht erst entstehen lassen.

<?php
// app/code/Vendor/Module/registration.php
// Minimal boilerplate — must match module.xml exactly
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

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

3. create-magento-module und Kommandozeilen-Generatoren

Das Community-Tool create-magento-module (Paket magento-hackathon/magento2-module-generator oder neuere Varianten) erzeugt genau diesen Minimal-Boilerplate per Kommandozeile in Sekunden, inklusive korrektem Verzeichnisbaum für etc, Model und Setup. Für ein Team, das regelmäßig neue Module anlegt, spart dieses eine Kommando gegenüber dem manuellen Anlegen bereits mehrere Minuten pro Modul und eliminiert die typischen Tippfehler beim Modulnamen.

Wichtig für den produktiven Einsatz: Das generierte Skelett sollte immer noch einmal manuell durchgegangen werden, insbesondere die generierte composer.json, denn nicht jeder Boilerplate-Generator setzt automatisch die richtigen PHP-Versionsbeschränkungen oder Magento-Abhängigkeiten für das aktuelle Projekt. Ein Generator ist ein Ausgangspunkt, keine Blackbox, die blind übernommen werden sollte.

#!/usr/bin/env bash
# Generate a new module skeleton with create-magento-module
set -euo pipefail

bin/composer require --dev magento-hackathon/magento2-module-generator

bin/cli createMagentoModule \
  Vendor Module \
  --add-blocks \
  --add-helpers \
  --add-model \
  --module-dir=app/code

# Always review the generated composer.json and module.xml manually
cat app/code/Vendor/Module/etc/module.xml

4. Eigene Skelett-Generatoren mit Composer-Templates

Generische Tools decken den Standardfall ab, aber jedes Team hat eigene Konventionen: eine feste PHPDoc-Vorlage, verpflichtende ViewModel-Struktur statt Block-Klassen, ein Standard-system.xml-Grundgerüst für Konfiguration. Ein eigener Boilerplate-Generator, gebaut mit composer create-project und einem eigenen Skelett-Repository, kodifiziert genau diese Team-Konventionen und ist oft langfristig wertvoller als ein generisches Community-Tool.

Der Aufbau ist überschaubar: Ein privates Composer-Paket mit Platzhaltern in Dateinamen und Dateiinhalt (etwa __VENDOR__ und __MODULE__), das nach dem Kopieren per Skript durch die tatsächlichen Werte ersetzt wird. Dieser Ansatz erlaubt es, direkt ein vollständiges ViewModel, eine Repository-Schnittstelle und die geforderte system.xml-Struktur ins Skelett aufzunehmen, statt sie bei jedem neuen Modul erneut von Hand zu ergänzen.

{
  "name": "mironsoft/module-skeleton-template",
  "description": "Internal boilerplate generator template for new Magento modules",
  "type": "magento2-module",
  "require": {
    "php": "~8.4.0"
  },
  "extra": {
    "skeleton-placeholders": {
      "__VENDOR__": "Vendor name, PascalCase",
      "__MODULE__": "Module name, PascalCase",
      "__VENDOR_LOWER__": "Vendor name, lowercase for config paths"
    },
    "skeleton-includes": [
      "etc/module.xml",
      "etc/di.xml",
      "etc/adminhtml/system.xml",
      "etc/adminhtml/acl.xml",
      "ViewModel/__MODULE__ViewModel.php",
      "registration.php"
    ]
  }
}

5. PhpStorm Live Templates für Magento-Boilerplate

Während Composer-basierte Generatoren ganze Module erzeugen, sind PhpStorm Live Templates das richtige Werkzeug für wiederkehrende Boilerplate-Bausteine innerhalb eines bestehenden Moduls: eine neue Plugin-Klasse, ein Repository-Interface, ein Data-Patch. Ein Live Template mit Variablen für Klassennamen und Namespace erzeugt in Sekunden ein vollständiges PHPDoc-Grundgerüst nach den Projektstandards, inklusive Constructor Property Promotion und typisierten Parametern.

Der Vorteil gegenüber einem externen Boilerplate-Generator: Live Templates arbeiten direkt im Editor, ohne Kontextwechsel zur Kommandozeile, und lassen sich exportieren und im gesamten Team teilen. Für Magento-Teams lohnt sich ein gemeinsames Live-Template-Set für die häufigsten Bausteine, Plugin, Observer, Repository, Data-Patch, das als Datei im Projekt-Repository versioniert und bei Bedarf importiert wird.

6. Automatisierte Interface- und Repository-Generierung

Repository-Pattern-Implementierungen in Magento folgen einem sehr wiederkehrenden Muster: ein Interface mit CRUD-Methoden, eine konkrete Implementierung, eine Suchergebnis-Schnittstelle und die zugehörige di.xml-Verdrahtung. Genau diese Wiederholung macht Repositories zum idealen Kandidaten für einen fokussierten Boilerplate-Generator, der aus einem Entitätsnamen automatisch alle vier Dateien konsistent erzeugt.

Ein selbst gebautes PHP-Skript, das ein Template mit Platzhaltern befüllt und die passende preference-Verdrahtung in di.xml ergänzt, spart bei jedem neuen Entitätstyp mehrere manuell fehleranfällige Schritte. Wichtig dabei: Der generierte Code muss weiterhin durch PHPStan und Coding Standard laufen, ein Boilerplate-Generator ersetzt nicht die Qualitätssicherung, sondern reduziert nur den manuellen Schreibaufwand.

<?php
declare(strict_types=1);

namespace Vendor\Module\Api;

use Vendor\Module\Api\Data\__ENTITY__InterfaceFactory;

/**
 * Generated repository interface skeleton for __ENTITY__.
 * Replace __ENTITY__ with the actual entity name during generation.
 */
interface __ENTITY__RepositoryInterface
{
    /**
     * Loads an entity by its identifier.
     *
     * @param int $id Entity identifier
     * @return \Vendor\Module\Api\Data\__ENTITY__Interface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function getById(int $id): \Vendor\Module\Api\Data\__ENTITY__Interface;

    /**
     * Persists an entity.
     *
     * @param \Vendor\Module\Api\Data\__ENTITY__Interface $entity Entity to save
     * @return \Vendor\Module\Api\Data\__ENTITY__Interface
     */
    public function save(\Vendor\Module\Api\Data\__ENTITY__Interface $entity): \Vendor\Module\Api\Data\__ENTITY__Interface;

    /**
     * Deletes an entity by its identifier.
     *
     * @param int $id Entity identifier
     * @return bool
     */
    public function deleteById(int $id): bool;
}

7. Boilerplate für Tests: PHPUnit-Skelette generieren

Ein oft übersehener Anwendungsfall für Boilerplate-Generatoren ist die Testklasse selbst. Für jede neue Repository- oder Plugin-Klasse braucht es idealerweise sofort eine PHPUnit-Testklasse mit korrektem Namespace, Mock-Setup für die Konstruktor-Abhängigkeiten und mindestens einem Grundgerüst-Testfall. Wird dieses Skelett manuell für jede Klasse neu geschrieben, sinkt die Wahrscheinlichkeit, dass überhaupt ein Test entsteht, spürbar.

Ein einfacher Ansatz: Ein Skript, das die Konstruktor-Signatur der Zielklasse per Reflection ausliest und daraus automatisch die passenden Mock-Deklarationen im generierten Testskelett erzeugt. Das reduziert die Einstiegshürde für Testabdeckung erheblich, weil der Entwickler nicht bei null anfängt, sondern nur noch die eigentliche Testlogik ergänzen muss, statt Boilerplate für Mocks von Hand zu tippen.

#!/usr/bin/env bash
# generate-test-skeleton.sh — reflect a class and scaffold a matching PHPUnit test
set -euo pipefail

CLASS_FQN="$1"
TEST_DIR="Test/Unit"

bin/cli reflectionToTestSkeleton \
  --class="$CLASS_FQN" \
  --output-dir="$TEST_DIR" \
  --mock-constructor-args

echo "[OK] Test skeleton generated for $CLASS_FQN in $TEST_DIR"

8. Fallstricke: Generatoren mit veralteten Patterns

Nicht jeder Boilerplate-Generator hält Schritt mit aktuellen Magento-Best-Practices. Ältere Community-Tools erzeugen teilweise noch InstallSchema.php-Skelette statt deklaratives Schema, oder generieren Block-Klassen als Standard, obwohl ViewModels seit Magento 2.2 der empfohlene Weg für reine Präsentationslogik sind. Wer einen Generator ungeprüft übernimmt, importiert damit auch veraltete Patterns direkt in neue Module.

Deshalb gehört die regelmäßige Überprüfung der Generator-Templates selbst in den Wartungsplan eines Teams. Ein Boilerplate-Generator, der einmal eingerichtet und danach nie wieder angefasst wird, driftet mit der Zeit von den aktuellen Magento-Empfehlungen ab. Ein einfacher Check: Jedes Quartal ein neues Testmodul generieren und dessen Code manuell gegen die aktuelle PHPStan-Konfiguration und Coding-Standard-Version prüfen.

9. Generator-Werkzeuge im Vergleich

Die folgende Tabelle vergleicht die verschiedenen Stufen von Boilerplate-Generatoren für Magento-2-Module nach Aufwand und Kontrolle.

Viele Teams kombinieren mehrere Ebenen: create-magento-module oder ein eigenes Composer-Template für die Grundstruktur, PhpStorm Live Templates für den täglichen Feinschliff einzelner Klassen. Diese Kombination deckt sowohl den seltenen Fall, ein neues Modul, als auch den häufigen Fall, eine neue Klasse in einem bestehenden Modul, mit passendem Boilerplate ab.

10. Zusammenfassung

Boilerplate-Generatoren für Magento-2-Module lösen zwei Probleme gleichzeitig: Sie sparen Zeit beim Anlegen neuer Struktur und sie erzwingen Konsistenz über das gesamte Team. Vom offiziellen CLI-Tool create-magento-module über eigene Composer-Templates bis zu PhpStorm Live Templates für einzelne Klassen deckt jede Stufe einen anderen Anwendungsfall ab, vom kompletten neuen Modul bis zur einzelnen Repository-Klasse.

Der wichtigste Punkt bei der Einführung eines Boilerplate-Generators ist die regelmäßige Pflege der Templates selbst. Ein Generator, der veraltete Patterns wie InstallScripts oder Block-Klassen statt ViewModels produziert, schadet mehr, als er hilft, weil er diese Muster automatisch in jedes neue Modul überträgt. Wer Generatoren als lebendes Werkzeug behandelt und regelmäßig gegen aktuelle Best Practices prüft, gewinnt spürbar Entwicklungsgeschwindigkeit.

11. FAQ: Magento-Modul-Boilerplate-Generatoren