Das Modul-Manifest (module.json)

Jedes Modul braucht eine module.json in seinem Wurzelverzeichnis. Diese Datei ist der Steckbrief des Moduls: Sie sagt dem ModuleManager, wer das Modul ist, welche Klasse es bootet und wovon es abhängt. Ohne sie wird das Verzeichnis bei der Entdeckung schlicht übergangen.

Vollständiges Schema

{
    "name": "My Module",
    "version": "1.0.0",
    "namespace": "Schneespur\\Module\\MyModule",
    "service_provider": "Schneespur\\Module\\MyModule\\MyModuleServiceProvider",
    "description": "Short description of what this module does.",
    "min_schneespur_version": "1.0.0",
    "requires_permissions": [],
    "default_enabled": false,
    "requires": {},
    "conflicts": []
}

Feld-Referenz

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Lesbarer Modulname. Erscheint in der Admin-Oberfläche.
version	string	ja	Semantische Version (z. B. 1.2.3)
namespace	string	ja	PHP-Namespace fürs PSR-4-Autoloading. Muss zur Verzeichnisstruktur unter src/ passen.
service_provider	string	ja	Voll qualifizierter Klassenname des ServiceProviders
description	string	empfohlen	Kurzbeschreibung. Erscheint in der Modul-Verwaltung.
min_schneespur_version	string	empfohlen	minimale kompatible Schneespur-/Wintertrace-Version
requires_permissions	string[]	optional	Core-Berechtigungen, die das Modul braucht
default_enabled	boolean	optional	Wird vom Core nicht gelesen. Siehe den Hinweis unten
requires	object	optional	Abhängigkeits-Map: {"other-module": "^1.0.0"}
conflicts	string[]	optional	Modul-Slugs, die nicht gleichzeitig aktiv sein dürfen

default_enabled hat keine Wirkung. Kein Code-Pfad liest das Feld aus. Beide Wege, auf denen eine Zeile in der Tabelle modules entsteht — die Installation über den Admin-Bereich und der Installationszweig von ModulesSync —, schreiben enabled = true, unabhängig vom Manifest. Und seit 1.2.0 entscheidet allein diese Zeile darüber, ob ein Modul bootet; die Einzelheiten stehen unter Lebenszyklus.

Das Feld auf false zu setzen und zu erwarten, dass das Modul schlafend installiert wird, tut also nicht, was man sich davon verspricht. Es bleibt im Schema, weil vorhandene Manifeste es mitführen — behandeln Sie es als Absichtserklärung, nicht als Verhalten.

Beispiel aus dem Referenzmodul

{
    "name": "Example Module",
    "version": "1.0.0",
    "namespace": "Schneespur\\Module\\Example",
    "service_provider": "Schneespur\\Module\\Example\\ExampleServiceProvider",
    "description": "Reference module demonstrating all extension points.",
    "min_schneespur_version": "1.0.0",
    "requires_permissions": [],
    "default_enabled": false,
    "requires": {},
    "conflicts": []
}

Namenskonventionen

• Modul-Slug: der Verzeichnisname unter modules/. Kleinschreibung mit Bindestrichen: my-module, telegram-notifications
• Namespace: Schneespur\Module\{PascalCaseName} — z. B. Schneespur\Module\TelegramNotifications
• ServiceProvider-Klasse: {PascalCaseName}ServiceProvider — z. B. TelegramNotificationsServiceProvider

Diese drei hängen zusammen: Der Slug ist der Verzeichnisname, der Namespace bestimmt den Autoloader-Pfad, und die ServiceProvider-Klasse ist der Einstiegspunkt aus dem Manifest. Wenn eines nicht zur Verzeichnisstruktur passt, findet der Autoloader die Klasse nicht.

Lokalisierte Namen und Beschreibungen

Für mehrsprachige Installationen dürfen name und description Objekte statt Strings sein:

{
    "name": {
        "de": "Telegram-Benachrichtigungen",
        "en": "Telegram Notifications"
    },
    "description": {
        "de": "Sendet Einsatz-Benachrichtigungen über Telegram.",
        "en": "Sends job notifications via Telegram."
    }
}

Die Methode pickLocalized() des Module-Modells löst dann auf die aktuelle App-Locale auf und fällt auf Englisch zurück, wenn die gewünschte Sprache fehlt.

Versions-Constraints in requires

Muster	Beispiel	trifft auf
*	"*"	jede Version
>=X.Y.Z	">=2.0.0"	2.0.0, 2.1.0, 3.0.0, …
^X.Y.Z	"^1.2.0"	1.2.0, 1.3.0, 1.99.0 (nicht 2.0.0)
~X.Y.Z	"~1.2.0"	1.2.0, 1.2.1, 1.2.99 (nicht 1.3.0)

Diese Constraints prüft der DependencyValidator vor dem Aktivieren — siehe Modul-Lebenszyklus.