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	Ob das Modul nach der Installation aktiv sein soll. Default: false
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 steht bewusst auf false: Ein frisch installiertes Modul soll nicht unbemerkt aktiv werden, sondern erst nach bewusster Freigabe in der Modul-Verwaltung laufen.

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.