Download the PHP package cordis-php/cordis without Composer

Cordis PHP

Cordis PHP is a strictly typed PHP 8.2+ runtime for building applications from reversible plugins and YAML composition. It takes the durable parts of Cordis:

• plugin instances own a scope and clean up in reverse order;
• services can appear, disappear, and be replaced while consumers restart;
• a loader reconciles a YAML entry tree instead of treating configuration as a one-time bootstrap script;
• patches compose a base configuration with deployment or user layers; and
• expressions are structured data, never executable PHP.

It is deliberately synchronous. PHP processes usually own the event loop at a higher layer, so a plugin's lifecycle is deterministic and can be embedded in CLI, worker, web, or framework hosts without imposing an async runtime.

Install

Minimal composition

Plugins implement CordisPhp\Contract\Plugin. They receive a child Context, can provide services, subscribe to events, and return an optional cleanup closure. Every registration is automatically tied to the plugin's scope.

YAML grammar

Each entry has an id and either a plugin name or a group of child entries. config and disabled are the only expression-capable fields.

The safe expression vocabulary is small and explicit:

• { $expr: { env: NAME, default: value } }
• { $expr: { service: service-name } }
• { $expr: { coalesce: [value-or-expression, ...] } }
• { $expr: { concat: [value-or-expression, ...] } }

No YAML value is evaluated as PHP. A !expr YAML tag is also accepted and uses the same structured payload.

The runtime envelope is closed and has a CI/editor-friendly YAML Schema: YAML composition guide and schema. Plugin config remains opaque to that envelope schema and is validated by its registered plugin.

Layering and reload

YamlRuntimeLoader::reload($patches) reads and validates a complete document, applies id-targeted patches, and reconciles the live plugin tree. A patch can replace a row's fields or append entries to the root or a group:

reloadIfChanged() is the host-friendly hot-reload primitive: a CLI watcher, RoadRunner worker, or framework development server decides when to call it. Lifecycle changes settle synchronously, and provider services are unpublished before provider cleanup runs so dependents stop first. Long-lived hosts must still call reload at a quiescent safe point: Cordis cannot invalidate a service reference already held by application code that is still executing.

Quality gates

The Pest suite covers lifetimes, service replacement, dependency pending and restart, event modes, YAML validation, expression safety, patches, groups, health snapshots, isolation, interception, and live reconciliation. Pull requests run the suite on PHP 8.2 through 8.5, with Symfony YAML 7 and Symfony YAML 8 on the PHP versions supported by each line.

Releases

The package is published through Packagist from the public GitHub repository. Release versions are owned by ops/version/current.yaml, and v<version> tags drive the checked GitHub Release workflow. Contributors preparing a release can inspect the complete procedure with:

Packagist derives Composer versions from the VCS tags, so the Composer manifest intentionally does not duplicate the release version.

Repository operations

The repository carries a versioned, self-describing operations catalogue under ops/. It keeps local developer and agent workflows explicit without replacing Composer's PHP tooling:

Each capability declares its command surface, required tools, path ownership, and any agent skill. The control validator checks those contracts, and the repository-wide check and test lanes are derived from the manifests rather than maintained as a second hand-written list.

Operator and agent skills

The solution-facing skill catalogue maps real Cordis use cases to focused procedures for design, agent harnesses, plugin development, YAML configuration, refactoring, operations, troubleshooting, and verification. They are repository-local durable instructions for operators and coding agents; they complement the repository-maintenance skills stored inside ops/.

Runnable examples

The examples directory contains nine self-checking CLI programs. They show scoped cleanup, dynamic dependency restart, YAML reloads, event pipelines, runtime observability, service isolation, configuration validation, deployment-owned service swaps, and local service interception using only this library's public API.

Run all of them with: