DOKUMENTATION

Nexum verstehen.
Sauber integrieren.

Ein Package, ein Symfony-Bundle und klare organisatorische Grenzen für Modules, Projects, Multi-Domain-Routing und optionale Infrastruktur.

VoraussetzungenPHP 8.4+Symfony ab 7.4Composer 2

01 Überblick

Symfony bleibt das Fundament.

Nexum ist eine modulare Architektur-Erweiterung für moderne Symfony-Anwendungen ab Version 7.4. Es wird als ein Composer-Package betrieben und verbindet automatische Discovery, validierte Modules, optionale Projects sowie direkt nutzbare Infrastruktur. Diese Grenzen sind keine Microservices und werden nicht separat deployt.

Ein Package

benjaminoeffinger/nexum ist die gemeinsame Installationsgrenze.

Ein Bundle

NexumBundle ist der einzige Symfony-Integrationspunkt.

Klare Grenzen

Discovery und Validierung stoppen ungültige Abhängigkeitsgraphen beim Build.

02 Installation

In drei Schritten startklar.

Installiere Nexum in einer Symfony-Anwendung ab Version 7.4. Die Symfony-Flex-Recipe ist vorbereitet; bis zu ihrer Veröffentlichung werden ein Bundle, sichere Standardkonfiguration und ein Routenimport einmalig manuell ergänzt.

Terminal

composer require benjaminoeffinger/nexum

config/bundles.php

Nexum\NexumBundle::class => ['all' => true],

config/routes/nexum.yaml

nexum:
    resource: .
    type: nexum

config/packages/nexum.yaml

nexum:
    doctrine: { enabled: false }
    api: { enabled: false }
    security: { enabled: false }

Bis die externe Symfony-Flex-Recipe veröffentlicht ist, werden Bundle, zentrale Konfiguration und Routenimport einmalig manuell ergänzt.

03 Erstes Modul

Descriptor anlegen, Symfony weiterverwenden.

Ein Modul ist eine normale PHP-Klasse mit dem Attribut #[NexumModule]. Es gibt keinen Generatorbefehl und keine Bundle-Registrierung pro Modul.

src/Module/Billing/BillingModule.php

<?php
namespace App\Module\Billing;

use Nexum\Module\Attribute\NexumModule;

#[NexumModule(description: 'Billing domain')]
final class BillingModule
{
}

Services, Controller, Commands, Event Subscriber und Messenger Handler innerhalb des Modulordners verwenden normales Symfony-Autowiring und Autoconfiguration. Entity/, Dto/ und der Descriptor selbst werden nicht als Services registriert.

Identität

Class-Strings sind die technische Identität. Die lesbare ID wird aus dem Klassennamen abgeleitet und kann als lowercase kebab-case überschrieben werden.

Abhängigkeiten

dependencies: [UserModule::class] beschreibt den Graphen. Transitive Abhängigkeiten ergänzt Nexum automatisch.

Cache

Descriptor-, Modul- und Controllerdateien werden als Symfony-Ressourcen registriert und invalidieren im Development die zuständigen Caches.

04 Modules & Projects

Zwei Betriebsarten, ein Symfony-Container.

Application Mode

Modules ohne Projects

Alle gefundenen und nicht deaktivierten Shared Modules sind aktiv. Klassische Symfony-Controller und Routen bleiben unverändert nutzbar.

Project Mode

Hostbasierte Oberflächen

Project-Descriptoren ordnen Shared und private Modules Bereichen wie Storefront, Admin oder API zu und präfixieren deren Routen.

src/Project/Storefront/StorefrontProject.php

use App\Module\Catalog\CatalogModule;
use App\Module\User\UserModule;
use Nexum\Project\Attribute\NexumProject;

#[NexumProject(
    modules: [CatalogModule::class, UserModule::class],
)]
final class StorefrontProject
{
}

DISCOVERY

Konvention statt Modulliste

Sharedsrc/Module/*
Project-privatsrc/Project/*/Module/*
Hostauflösungnexum.projects.*.hosts

Transitive Abhängigkeiten ergänzt Nexum beim Kompilieren automatisch.

Projects sind keine Mandantenisolierung.

Die Zuordnung steuert Routen und sichtbare Module, aber nicht automatisch Services, Datenbanktabellen, Tokens, Subscriber oder Handler.

config/packages/nexum.yaml

nexum:
    projects:
        storefront:
            hosts: [shop.example.com, www.example.com]
        admin:
            hosts: [admin.example.com]

Bei genau einem Project sind Hosts optional. Bei mehreren Projects benötigt jedes Project mindestens einen eindeutigen exakten Host. Der erste Eintrag ist der Canonical Host; Wildcards, Pfadpräfixe und Tenant-Subdomains werden derzeit nicht automatisch aufgelöst.

05 Konfiguration

Konventionen zuerst. Abweichungen explizit.

Die gesamte Konfiguration liegt unter nexum:. Discovery verwendet standardmäßig %kernel.project_dir%/src und ermittelt den passenden Namespace aus Composer. Nur bei mehrdeutigen PSR-4-Mappings ist ein Namespace-Override nötig.

Auszug: config/packages/nexum.yaml

nexum:
    discovery:
        root: '%kernel.project_dir%/src'
    modules:
        legacy: { enabled: false }
    doctrine: { enabled: true }
    api: { enabled: false }
    filesystem:
        enabled: true
        root: '%kernel.project_dir%/storage/files'
    messenger: { enabled: true }

Ein aktiver Graph darf kein deaktiviertes Modul benötigen. Nexum deaktiviert abhängige Module nicht stillschweigend, sondern beendet den Container-Build mit einer konkreten Meldung.

06 Integrationen

Fähigkeiten gezielt aktivieren.

Optionale Integrationen werden zentral unter nexum: konfiguriert. Exponierende Security-, MFA-, Passkey- und Management-APIs bleiben separat und ausdrücklich freizuschalten.

Module & Projects

Fachliche Module mit validierten Abhängigkeiten und optionalen, hostbasierten Project-Oberflächen.

Doctrine & Entities

UUIDv7-, Timestamp- und Soft-Delete-Basisklassen, Doctrine-Mappings und ein expliziter Entity Store.

API & Security

Deklarative REST-Ressourcen, Filter, Pagination, Bearer-Tokens, Permissions, MFA und Passkeys.

Infrastruktur

Filesystem, Mailer, Messenger, QR-Code, Logger, Health Checks und provider-neutrale Verträge.

Provider-neutrale Verträge halten externe SDKs aus dem Framework-Kern heraus. Storage-, Payment-, Search- oder Notification-Anbieter können deshalb über eigene Symfony-Adapter angebunden werden.

07 Security & Betrieb

Fähigkeit und öffentliche API bleiben getrennt.

security.enabled aktiviert Token- und Permission-Services, aber noch keine öffentlichen Tokenrouten. Security-, MFA-, Passkey- und Management-APIs benötigen jeweils einen eigenen Expositionsschalter. Im Project Mode müssen die erlaubten Projects ausdrücklich genannt werden.

Sichere Defaults

Keine API durch Installation

Auth-, MFA-, Passkey- und Management-Routen erscheinen nicht allein durch composer require.

Project Mode

Explizite Allowlist

Eine aktivierte API verlangt projects: [admin] oder bewusst projects: ['*'].

Was der Architektur-Build prüft

Fehlende oder zyklische Module-Abhängigkeiten
Doppelte IDs und falsch platzierte Descriptoren
Shared-zu-Private- und projectübergreifende Abhängigkeiten
Mehrdeutige oder mehrfach vergebene Project-Hosts

08 CLI & Diagnose

Architektur sichtbar machen.

Konsole

php bin/console nexum:about
php bin/console nexum:architecture
php bin/console debug:router
php bin/console debug:container Nexum\\Module\\ModuleRegistryInterface
php bin/console debug:container Nexum\\Project\\ProjectContextInterface
php bin/console config:dump-reference nexum

nexum:about

Versionen, Environment und Anzahl der erkannten Modules und Projects.

nexum:architecture

Kompilierter Architekturgraph mit IDs, Scopes, Dependencies und Zuordnungen.

nexum:user:create

Benutzer anlegen, wenn die User-Integration aktiviert ist.

Bereit für das erste Modul?

Installiere Nexum, lege einen Descriptor an und prüfe den kompilierten Architekturgraphen.

Zur Benutzung