Discovery and capability providers

Package manifests advertise syntax factories and other extension capabilities. For factory implementations, see Writing syntax extensions; for everyday usage, see Overview and loading.

Composer discovery

Bundled extensions, installed Composer packages, and the root application can advertise providers in extensions/*.extension.json or extensions/*/*.extension.json. Each file can declare a syntax factory class and several capability providers; its filename is independent of their classes. For example, extensions/Identifiers/Identifiers.extension.json:

{
  "class": "Acme\\Parsing\\Identifiers",
  "rules": ["identifier"],
  "fluents": ["identifier"]
}

Files directly in the package's extensions/ directory or one directory below it are discovered. Deeper directories and other JSON files are ignored. Filenames are processed in sorted order, and each resolved package directory is visited once. A package without matching files needs no configuration. File discovery also works when an installed package has no composer.json.

Existing declarations in composer.json remain supported:

{
  "extra": {
    "comprehend": {
      "extensions": [
        {
          "class": "Acme\\Parsing\\Identifiers",
          "rules": ["identifier"],
          "fluents": ["identifier"]
        }
      ]
    }
  }
}

Each factory provider implements SyntaxExtension, is autoloadable, and has a public constructor requiring no arguments. Supply both name lists, using [] when empty. Providers must be stateless; use explicit extend() for application configuration. Their returned rule and fluent names must exactly match the advertised names, ignoring case and order. Ordinary explicit registration still permits duplicate keys with later registrations replacing earlier ones.

Composer 2 installation data locates package roots; PHP files are not scanned. Inline Composer declarations and discovered files are merged without source priority. Identical declarations for the same provider within a package are deduplicated; inconsistent declarations fail discovery. Bundled declarations live beside their classes in the library's own extensions/ directory and are discovered even without Composer installation data. JSON is the only supported manifest format.

The index is built once per process when discovery is first needed. Syntax::names() includes advertised names without constructing providers. C::syntaxNames() still lists reserved built-in names. Bundled providers also work without Composer metadata. Restart long-running processes after changing installed packages or metadata.

Built-ins take precedence, followed by explicit vocabulary registrations, then discovered factories. Rule and fluent names are independent and case-insensitive. If two providers advertise the same name and kind, calling it raises an error identifying both packages and classes. An explicit defineRule(), defineFluent(), or extend() registration for that kind resolves the conflict locally. A conflicting fluent fails before rule-appending fallback. Identical repeated provider declarations within one package are deduplicated; inconsistent declarations fail discovery.

Unreadable files, malformed JSON, and invalid declarations fail discovery with package and manifest-path context. Files must contain a JSON object. Provider classes and registrations are validated only when needed, including reserved-name checks. Deferred provider-loading errors also identify the declaring manifest files. Both registration iterables must succeed before any factories are cached; failures publish no partial registrations. Recursive loading of a provider is rejected. Successful registrations are cached, while factories run for every authoring call. Loading never installs dependencies or performs network requests. Discovery and provider construction happen during authoring or grammar preparation, before recognition.

Capability providers

Use providers to map autoloadable classes to the PHP interfaces they advertise. Several classes may provide the same interface. Capability-only manifests can omit class, rules, and fluents:

{
  "providers": {
    "Acme\\Parsing\\FirstPass": ["Acme\\Parsing\\AnalysisPass"],
    "Acme\\Parsing\\SecondPass": ["Acme\\Parsing\\AnalysisPass"]
  }
}

Consumers request contracts through Syntax\ExtensionLoader:

use Vanderlee\Comprehend\Syntax\ExtensionLoader;

$passes = ExtensionLoader::defaults()->all(\Acme\Parsing\AnalysisPass::class);

all(interface) returns providers in declaration/discovery order, or an empty list. requireOne(interface) requires exactly one advertised provider and reports missing or ambiguous capabilities. Both methods have generic return types for static analysis. Consumers decide how and when to invoke providers; discovery never runs their operations.

Contracts must be interfaces. Names are case-insensitive, accept a leading backslash, and are deduplicated and sorted for declaration comparison. Discovery validates metadata without loading provider classes or interfaces. Interface existence and implementation are checked when a provider is needed; every interface it advertises must validate. Only advertised interfaces resolve: implemented parent interfaces are not inferred.

Provider classes require a public constructor with no required arguments and must remain stateless. The loader shares one instance per package/class across all its contracts and factory registrations. Each provider loads atomically: interface checks, construction, and declared syntax registrations must all succeed before anything is cached. Failed loads can be retried. Recursive loads fail with manifest context.

The existing class/rules/fluents fields declare the syntax factory provider and implicitly advertise SyntaxExtension. When that class also appears in providers, its capabilities are combined and use the same instance. Explicit SyntaxExtension declarations must belong to that syntax class and have both name lists. Existing factory-only manifests need no changes; additional factory classes can use separate manifests.

The bundled Optimizer advertises Builder\GraphOptimization in its providers map. Grammar preparation uses requireOne(GraphOptimization::class) when optimization is enabled; FreezeFlags::NONE bypasses that lookup. Multiple optimizer providers remain an error for freezing, even though all() supports multiple providers for other consumers. The old optimizer flag and top-level provides list are rejected; use the map. See Grammar authoring for optimizer eligibility rules.

The bundled Optimizer also implements SyntaxExtension. Its manifest advertises readWhile, readUntil, readWhileSet, readWhileRange, readRest, skipWhile, skipUntil, and skipRest as rules, with an empty fluent list. These factories append scanners when chained, just like other terminal factories. Their parsers live in Extensions\Optimizer\Parser, and explicitly authored scanners work with FreezeFlags::NONE. Factory loading and optimizer resolution share the same provider instance. See Reading and skipping runs.