breadcrumb-the-shire/docs/reference-module-manifest-contract.md

Module Manifest Contract (V1.2)

Letzte Aktualisierung: 2026-03-25

Ziel

Verbindlicher Contract für modules/*/module.php, damit Module zur Runtime deterministisch geladen und validiert werden.

Status

Dieses Dokument ist die kanonische (normative) Quelle für Manifest-, Runtime- und Guard-Regeln des Modul-Systems. /docs/reference-extension-readiness.md referenziert diesen Contract und dupliziert keine Felddefinitionen.

JSON-Schema-Enforcement

Zusatz zur Laufzeitvalidierung:

• JSON-Schema-Datei: /.agents/contracts/module-manifest.schema.json
• Laufzeit-Check bei Modul-Laden: ModuleManifestSchemaValidator
• CLI-Check: php bin/console module:validate <module-id|--all>

Ein Manifest muss sowohl:

1. das JSON-Schema erfuellen als auch
2. die Laufzeit-Contracts (Klassen/Interfaces/Namespace) bestehen.

Namespace-Konvention

Alle PHP-Klassen eines Moduls müssen den Namespace MintyPHP\Module\<Name>\* verwenden. Core-Namespaces (MintyPHP\Service\*, MintyPHP\Repository\*, MintyPHP\Support\*) sind für Modul-Code verboten.

Verzeichnis-Layout:

modules/<id>/lib/Module/<Name>/
  Service/              # BookmarkService, Factory, etc.
  Repository/           # Repository + Interfaces
  Providers/            # SessionProvider, LayoutProvider, SearchProvider
  Support/              # Modul-spezifische Utilities
  <Name>ContainerRegistrar.php
  <Name>AuthorizationPolicy.php

Der ModuleAutoloader mappt MintyPHP\* → modules/<id>/lib/ per PSR-4. Enforcement: ModuleStructureContractTest::testModuleClassesUseModuleNamespace.

Aktivierung (APP_ENABLED_MODULES)

• nicht gesetzt: config/modules.php gilt.
• gesetzt und leer (APP_ENABLED_MODULES=''): keine Module.
• gesetzt mit Liste (APP_ENABLED_MODULES='a,b'): exakt diese Module.

i18n_path Contract

Module mit eigenen Übersetzungsdateien deklarieren den relativen Pfad zum i18n-Verzeichnis:

'i18n_path' => 'i18n',

Der ModuleAutoloader registriert daraus den absoluten Pfad modules/<id>/i18n/ als zusätzliche Übersetzungsquelle.

permissions Contract

permissions ist eine Objektliste:

'permissions' => [
    [
        'key' => 'module.permission',
        'description' => 'Human readable text',
        'active' => true,      // optional, default true
        'is_system' => true,   // optional, default true
    ],
],

• key und description sind Pflichtfelder.
• Runtime-Sync erfolgt über php bin/console module:sync.
• module:sync führt diesen Sync automatisch aus.

scheduler_jobs Contract

scheduler_jobs ist eine Objektliste mit vollem Default-Contract:

'scheduler_jobs' => [
    [
        'job_key' => 'module.job',
        'handler' => App\\Scheduler\\MyJobHandler::class,
        'label' => 'Job label',
        'description' => 'Job description',
        'default_enabled' => true,
        'default_timezone' => 'Europe/Berlin',
        'default_schedule_type' => 'daily', // hourly|daily|weekly
        'default_schedule_interval' => 1,
        'default_schedule_time' => '02:00', // required for daily/weekly
        'default_schedule_weekdays_csv' => null, // weekly: e.g. '1,3,5'
        'default_catchup_once' => true,
        'allowed_schedule_types' => ['daily', 'weekly'],
    ],
],

• Manifest ist Source of Truth für Job-Metadaten und Defaults.
• Handler werden zur Laufzeit container-resolvable für execute(...) geladen.

ui_slots Contract (V1.2)

Neue generische Slot-Typen:

• topbar.right_item: { key, template, permission?, order }
• layout.body_end_template: { key, template, permission?, order }
• layout.head_style: { key, path, permission?, order }
• runtime.component: { key, script, export?, selector?, scope?, config_path?, default_config?, phase?, permission?, order }

runtime.component.phase ist early|default|late (Default: late).

Abgrenzung CSS:

• layout.head_style = global auf allen Seiten.
• asset_groups = seiten-/kontextbezogen über style_groups.

Guard-Regeln

• Route-Kollisionen sind fail-fast:
  • Modul vs Modul auf target und path.
  • Modul vs Core auf path beim Router-Boot.
• Layout-Provider duerfen reservierte Core-Keys nicht überschreiben (moduleSlots, csrfKey, currentTenant, ...).
• Layout-Provider-Top-Level-Keys müssen namespaced sein (<module_id>.<key>).

Runtime-Fingerprint

web/index.php validiert bei jedem Request, dass der Runtime-Stand zur aktuellen Modul-Konfiguration passt.

• php bin/console module:build schreibt nach jedem Build storage/runtime/.module-fingerprint (sortierte Modul-IDs, kommasepariert).
• web/index.php vergleicht den Fingerprint mit der erwarteten Modul-Liste.
• Bei Mismatch: RuntimeException mit Hinweis auf php bin/console module:sync.
• Kein Auto-Build im Request-Pfad — Build ist ausschliesslich CLI-Aufgabe.

Methoden: ModuleRuntimePageBuilder::expectedFingerprint(), readFingerprint(), writeFingerprint().

API-Channel-Isolation

API-Requests (api/-Prefix) überspringen den gesamten Web-Session-Flow:

• Kein Session::start(), kein Cookie-Setting, kein CSRF-Token
• Kein Remember-Me, kein Session-Timeout, kein Tenant-UI-Refresh
• API-Auth erfolgt über ApiBootstrap.php (Bearer-Token)
• AccessControl listet api/ als always-public

Standard-Runbook

php bin/console module:sync führt in fester Reihenfolge aus:

1. module:migrate
2. module:permissions-sync
3. module:build
4. module:assets-sync

Der Output enthaelt eine deterministische Step-Summary (migrate, permissions-sync, build, assets-sync) inklusive vendor_warnings_ignored=<n>. First-party Warnings/Notices/Deprecations gelten als Fehler (fail-fast).