PluginConfigHandler

PluginConfigHandler reads a plugins.{xml,php,yaml,yml} file — the correct, documented way to register plugins — a flat, ordered enable/disable list of plugin classes — and appends the enabled ones to the plugins config key that PluginManager::bootFromConfig() already reads.

A 'plugins' => [...] entry written directly into settings.* happens to work too, since it shares the same key, but that’s an incidental consequence of the storage, not a supported interface — don’t document or rely on it. Per-plugin options are NOT part of this schema; they stay in settings.*, contributed by the plugin itself via PluginRegistrar::configDefault().

Multiple plugin config files can contribute (the app’s own %core.config_dir%/plugins.xml plus any module’s %core.module_dir%/<name>/Config/plugins.xml). Each compiled artifact returns just the classes it declares; PluginConfigHandler::apply() reads the plugins key’s current value and appends only classes not already present, so declared order across files is preserved and the first occurrence of a class (across all contributing files, applied in bootstrap order) wins if the same class is listed more than once.

An enabled written as a %env(...)% placeholder cannot be decided while the file is being compiled, so such an entry survives compilation as a {class, enabled} pair and EnvPlaceholder turns the placeholder into the bool when the artifact is loaded. That is what lets a deployment turn a plugin on by setting a variable and restarting, with the same compiled cache.

Canonical schema: list<array{class: string, enabled: bool|string}>, in document order, where a string enabled is an unresolved placeholder.

Synopsis

class PluginConfigHandler extends XmlConfigHandler implements IArrayConfigHandler, IDeclarationConfigHandler, IPositionAwareConfigHandler, ISchemaAwareConfigHandler


Extends	`XmlConfigHandler`
Implements	`IArrayConfigHandler`, `IDeclarationConfigHandler`, `IPositionAwareConfigHandler`, `ISchemaAwareConfigHandler`
Since	`1.0.0`
Source	`Config/PluginConfigHandler.php`

Constants

Constant	Value	Description
`XML_NAMESPACE`	`'http://quiote.dev/quiote/config/parts/plugins/1.1'`

Methods

Method	Description
`apply(mixed $declaration, string $sourceRef): void`	Append the declared plugin classes to the `plugins` config key.
`execute(XmlConfigDomDocument $document): mixed`	Execute this configuration handler.
[`executeArray(list<array{class: string, enabled?: (bool	string)}> $config, ?string $sourceRef = null): list<string
[`merge(list $declared, array<int	string, mixed> $existing): list`](#merge)
`schema(): Rule`	“enabled” is not required: hand-authored PHP/YAML may omit it, defaulting to true, matching the XSD’s own default.
[`toCanonicalArray(XmlConfigDomDocument $document): list<array{class: string, enabled: (bool	string)}>`](#tocanonicalarray)
[`toCanonicalArrayWithPositions(XmlConfigDomDocument $document, ElementPositionIndex $positions): array{data: list<array{class: string, enabled: (bool	string)}>, positions: array<string, array{file: string, line: int}>}`](#tocanonicalarraywithpositions)

apply()

public function apply(mixed $declaration, string $sourceRef): void

Append the declared plugin classes to the plugins config key.

The classes and deferred entries, in declared order, that PluginConfigHandler::executeArray() compiles.

Parameter	Type	Description
`$declaration`	`mixed`	The classes and deferred entries, in declared order, that `PluginConfigHandler::executeArray()` compiles.
`$sourceRef`	`string`

execute()

public function execute(XmlConfigDomDocument $document): mixed

Execute this configuration handler.

The document to parse.

Parameter	Type	Description
`$document`	`XmlConfigDomDocument`	The document to parse.

Returns mixed — The declaration to be cached.

Throws	When
`ParseException`	If a requested configuration file is improperly formatted.

executeArray()

public function executeArray(list<array{class: string, enabled?: (bool | string)}> $config, ?string $sourceRef = null): list<string|array{class: string, enabled: string}>

Compiles the canonical array down to what the artifact holds: a class name per enabled plugin, and a {class, enabled} pair for one whose enabled is a %env(...)% placeholder, which nothing can decide yet.

Hand-authored PHP/YAML sources may omit enabled (defaults to true), matching the XSD’s own default.

Parameter	Type	Description
`$config`	`list`<`array{class: string, enabled?: (bool	string)}“>`
`$sourceRef`	?``string

Returns list``<``string``|``array{class: string, enabled: string}``>

merge()

public static function merge(list<string> $declared, array<int|string, mixed> $existing): list<mixed>

Merge declared plugin classes into the classes already registered, appending only what is not there yet.

The current plugins config value.

Parameter	Type	Description
`$declared`	list``<``string``>	Class names to append, in declared order.
`$existing`	`array`<`int“	`string`, `mixed`>`

Returns list``<``mixed``> — The merged list.

schema()

public function schema(): Rule

“enabled” is not required: hand-authored PHP/YAML may omit it, defaulting to true, matching the XSD’s own default.

It is a bool or the string form of a %env(...)% placeholder that is not resolved yet.

Returns Rule

toCanonicalArray()

public function toCanonicalArray(XmlConfigDomDocument $document): list<array{class: string, enabled: (bool | string)}>

Parameter	Type	Description
`$document`	`XmlConfigDomDocument`

Returns list``<``array{class: string, enabled: (bool | string)}``>

toCanonicalArrayWithPositions()

public function toCanonicalArrayWithPositions(XmlConfigDomDocument $document, ElementPositionIndex $positions): array{data: list<array{class: string, enabled: (bool | string)}>, positions: array<string, array{file: string, line: int}>}

Parameter	Type	Description
`$document`	`XmlConfigDomDocument`
`$positions`	`ElementPositionIndex`

Returns array{data: list<array{class: string, enabled: (bool | string)}>, positions: array<string, array{file: string, line: int}>}

Inherited methods

These come from an ancestor and are documented where they are declared.

Method	Declared in	Description
`appendParameter()`	`ParameterHolder`	Append a parameter.
`appendParameterByRef()`	`ParameterHolder`	Append a parameter by reference.
`clearParameters()`	`ParameterHolder`	Clear all parameters associated with this request.
`getFlatParameterNames()`	`ParameterHolder`	Retrieve an array of flattened parameter names.
`getParameter()`	`ParameterHolder`	Retrieve a parameter.
`getParameterNames()`	`ParameterHolder`	Retrieve an array of parameter names.
`getParameters()`	`ParameterHolder`	Retrieve an array of parameters.
`hasParameter()`	`ParameterHolder`	Indicates whether or not a parameter exists.
`initialize()`	`XmlConfigHandler`	Initialize this ConfigHandler.
`literalize()`	`BaseConfigHandler`	Literalize a string value.
`removeParameter()`	`ParameterHolder`	Remove a parameter.
`replaceConstants()`	`BaseConfigHandler`	Replace configuration directive identifiers in a string.
`replacePath()`	`BaseConfigHandler`	Replace a relative filesystem path with an absolute one.
`reset()`	`ParameterHolder`	Removes every parameter held, leaving the holder empty for reuse.
`setParameter()`	`ParameterHolder`	Set a parameter.
`setParameterByRef()`	`ParameterHolder`	Set a parameter by reference.
`setParameters()`	`ParameterHolder`	Set an array of parameters.
`setParametersByRef()`	`ParameterHolder`	Set an array of parameters by reference.