Search by

evolvephp / module

josiahking

Application module SDK and lifecycle support for EvolvePHP 2.

dev-main 2026-10-28 16:20 UTC

This package is auto-updated.

Last update: 2026-11-16 13:37:12 UTC


README

Application module SDK and lifecycle support for EvolvePHP 2.

Descriptor Foundation

The package provides the public experimental Evolve\Module\ModuleDescriptor in-memory immutable descriptor and Evolve\Module\ModuleCompatibilityValidator.

ModuleDescriptor reuses Evolve\Contracts\Component\ComponentIdentifier, preserves the exact accepted human-readable name, always reports the hard-coded Module type through ComponentType::Module, exposes descriptor schema version 1, and declares an EvolvePHP major as a positive integer. Structural descriptor validity is separate from framework compatibility: positive non-2 majors are valid descriptor metadata, while ModuleCompatibilityValidator performs explicit EvolvePHP major compatibility validation for the currently supported major 2.

ModuleDescriptor exposes graphDeclaration(), returning an immutable Evolve\Contracts\Component\ComponentGraphDeclaration built during descriptor construction. Existing three-argument descriptor construction remains valid and creates an empty graph declaration. A caller may also supply ComponentGraphRelations to declare required or optional dependencies, declarative conflicts, required capabilities with ExactlyOne or OneOrMore cardinality and provided capability identifiers.

The graph declaration is declaration vocabulary only. Relation ordering is canonical and deterministic, but declaration order has no startup-order semantics. It does not resolve dependencies, activate optional dependencies, resolve conflicts, select capability providers, detect cycles, discover components, register components, order boot or introduce component versions, version constraints or SemVer graph decisions. Dependency resolution and graph validation are handled by Core graph resolution.

These APIs are PUBLIC EXPERIMENTAL and pre-beta. Descriptor discovery, descriptor loading and descriptor serialization remain deferred.

Entry Point

The package provides the public experimental Evolve\Module\Module entry-point interface. Module extends Evolve\Contracts\Component\ComponentEntryPoint and introduces no Module-specific lifecycle methods.

An enabled module entry point participates in the shared component sequence: register() contributes service definitions through ServiceDefinitionRegistrar, Core freezes the service-definition graph, boot() receives an application-lifecycle-only ComponentBootContext, ready() runs after all enabled components boot, and shutdown() releases application-lifetime resources in reverse successful boot order. Deferred failure cleanup registered during boot() is only for that module's boot failure; successful modules still clean up through normal shutdown.

Explicit Definition

The package provides the public experimental Evolve\Module\ModuleDefinition. It wraps an already-created ModuleDescriptor and an explicit module entry-point class name.

ModuleDefinition preserves the descriptor's identifier, type and exact graph declaration object. Its validate() method runs the existing ModuleCompatibilityValidator and checks that the configured entry-point class exists and implements Evolve\Module\Module. Entry-point instances are created only when Core prepares an explicitly enabled definition for lifecycle execution.

Discovery, descriptor loading, Composer extra metadata, automatic package scanning, module self-enablement, descriptor serialization and version-constraint evaluation remain deferred.

Explicit Composer consumer evidence

The repository-owned skeleton validator creates an isolated Composer application, generates an application-owned module, and installs a separately namespaced library module from an offline path repository. The application loads each module's PHP definition file explicitly and supplies those definitions to Core's ComponentBootstrapper. Only identifiers listed in evolve.components.enabled enter the Kernel lifecycle. This is local integration evidence, not a claim that the package is publicly published.

The library module's class is loaded from the generated application's vendor tree. Registration, boot, ready, shutdown, disabled state, dependency ordering, and failure cleanup are checked with observable effects. A module may provide a namespaced message source and migration definitions through explicit application composition. Locale comes from each execution context. Migration planning is read-only; application code chooses when to execute a pending action. No module scanning, automatic enablement, or boot-time migration execution is provided.

Package

evolvephp/module

Requirements

PHP ^8.4

Dependencies

evolvephp/contracts

Publication Status

EvolvePHP 2 is pre-release. This package is not yet independently published, and the current canonical source is the EvolvePHP monorepo:

https://github.com/josiahking/evolvephp

Installation

Independent Composer installation guidance will be added when package publication begins.

Licence

BSD-3-Clause. See LICENSE.md.