PluginManifest

Reads and validates a plugin's milpa.json manifest file. This is the primary source of plugin metadata when milpa.json exists. Falls through to #[PluginMetadata] attributes when milpa.json is absent (handled by Plugins::getMetadata()).

public static function fromPath(string $manifestPath): self

Create a manifest from a milpa.json file path.

Parameters

public static function fromArray(array $data): self

Create a manifest from an array (useful for scaffolding and testing).

Parameters

public static function generateFromMetadata(array $metadata, string $namespace, string $entrypoint, array $warnings = []): array

Generate a milpa.json manifest from existing #[PluginMetadata] attributes. The capability entries decide the emitted shape — the generator NEVER invents metadata: - every entry a structured record → the canonical `capabilities` block (milpa-plugin.schema.json), each record validated through core's capability value objects plus the generation-time provider check (`service` present, autoloadable, implementing the declared interface); - every entry a bare FQCN string → the legacy `contracts` block exactly as before, plus a warning in `$warnings` teaching how to reach canonical; - a mix of both shapes → hard failure: one plugin migrates atomically.

Parameters

Returns

The manifest data ready to be saved as JSON

Throws

\InvalidArgumentException On mixed entry shapes, malformed records, or providers that do not resolve

public function validate(): void

Validate the manifest. Throws on invalid data.

Throws

\InvalidArgumentException If required fields are missing or invalid

public function toMetadataArray(): array

Convert to the metadata-array shape (`Plugins::$plugins`) that some consumers still read instead of the typed accessors below. The capability lists carry the RAW declarations of whichever shape the manifest speaks — canonical `capabilities.*` records or legacy `contracts.*` bare FQCNs (see {@see rawCapabilityRecords()}) — because this array feeds the host boot path, whose ingestion ({@see \Milpa\Attributes\PluginMetadata} -> AttributeLoader) accepts both shapes. Reading only `contracts.*` here would blind the boot to every canonical manifest (the Cosecha T2-Major finding).

public function getName(): string

Vendor/package name (e.g., "acme/mail-plugin").

public function getDisplayName(): string

Human-readable display name (e.g., "Mail Plugin").

public function getDescription(): string

Short human-readable summary of what the plugin does.

public function getVersion(): Milpa\ValueObjects\SemanticVersion

public function getType(): string

Plugin type: Web, CLI, Mixed, Service.

public function getNamespace(): string

PHP namespace (e.g., "Acme\Plugins\ExamplePlugin").

public function getEntrypoint(): string

Main plugin file relative to plugin directory (e.g., "ExamplePlugin.php").

public function getProvides(): array

The interfaces/services this plugin provides to the capability system.

public function getRequires(): array

The interfaces/services this plugin cannot boot without.

public function getSuggests(): array

The interfaces/services this plugin can use if available but does not strictly need.

public function getProvidedCapabilities(): array

Typed `provides` capability records (D7 wiring seam). Reads the canonical `capabilities.provides` key, falling back to legacy `contracts.provides`, and accepts both record arrays and legacy bare-FQCN strings.

public function getRequiredCapabilities(): array

Typed `requires` capability records (D7 wiring seam).

public function getSuggestedCapabilities(): array

Typed `suggests` capability records (D7 wiring seam).

public function getComposerDependencies(): array

Composer packages this plugin depends on, beyond the framework itself.

public function getPluginDependencies(): array

Other Milpa plugins this plugin depends on.

public function getMinMilpaVersion(): ?string

The minimum Milpa framework version this plugin requires, or null if unconstrained.

public function getPhpVersion(): ?string

The PHP version constraint this plugin requires (e.g. ">=8.2"), or null if unconstrained.

public function getEnvVars(): array

Environment variable names the plugin expects to be set.

public function getMigrationsDirectory(): ?string

Migrations directory name relative to plugin root (e.g., "Migrations").

public function getAuthors(): array

The plugin's declared authors.

public function getRawData(): array

public function toJson(): string

Serialize the manifest data to JSON string for writing to disk.