omnibridge/composer API reference

Acme\Child\Stub

GreeterStub class

final class GreeterStub extends AbstractStub GreeterStub.php:14

Stubs of App\Greeter\X for every plain class Acme\Greeter\X, unless the application defines App\Greeter\X in src/Greeter/: what an IDE needs when a package aliases its classes under the application's namespace at run time (omnibase does it for Base\ and App\). Run by omnibridge/composer only.

GreeterStub::getName()

public function getName(): string

Acme\Greeter

Greeter class

final class Greeter Greeter.php:10

Says hello.

Greeter::__construct()

public function __construct(string $greeting = 'Hello')

Greeter::greet()

public function greet(string $name): string

Salutation class

class Salutation Salutation.php:6

A word to greet with.

public readonly string $word

Salutation::__construct()

public function __construct(public readonly string $word = 'Hello')

App

LoudGreeter class

class LoudGreeter extends Greeter LoudGreeter.php:8

Loaded only once Greeter is no longer final (bin/demo.php checks).

LoudGreeter::greet()

public function greet(string $name): string

Omnibridge\Composer

Engine class

final class Engine Engine.php:25

The engine inside Composer: the installed packages read from Composer's local repository, the reconciler and the stub generator run on them.

const STATE_DIR = 'composer/omnibridge'

Engine::__construct()

public function __construct(readonly Composer $composer, readonly IOInterface $io)

Engine::vendorDir()

public function vendorDir(): string

Engine::projectDir()

public function projectDir(): string

Engine::stateDir()

public function stateDir(): string

Engine::php()

public function php(): string

The PHP version the project installs for: config.platform.php, else the running PHP.

Engine::packages()

public function packages(): array

Returns

the installed packages and the root

Engine::reconciler()

public function reconciler(): Reconciler

Engine::patch()

public function patch(bool $write = true): Report

Engine::stubs()

public function stubs(bool $write = true): StubReport

Engine::restoreAll()

public function restoreAll(): array

Engine::runWith()

public static function runWith(?Package $package, callable $run): mixed

Runs $run with the declaring package's classes autoloadable (its psr-4, psr-0 and classmap; never its "files", which would run its code inside Composer). The loader comes after Composer's own and is removed after.

Plugin class

final class Plugin implements PluginInterface, EventSubscriberInterface, Capable Plugin.php:21

The Composer plugin: patches after install and update (every package is on disk then), stubs after the autoloader is dumped, everything written back as published when the plugin itself is uninstalled. It knows no package: what it does comes from the packages' extra.omnibridge.

Plugin::getSubscribedEvents()

public static function getSubscribedEvents(): array

Plugin::activate()

public function activate(Composer $composer, IOInterface $io): void

Plugin::deactivate()

public function deactivate(Composer $composer, IOInterface $io): void

Plugin::uninstall()

public function uninstall(Composer $composer, IOInterface $io): void

Plugin::getCapabilities()

public function getCapabilities(): array

Plugin::onPostInstall()

public function onPostInstall(): void

Plugin::onPostAutoloadDump()

public function onPostAutoloadDump(): void

Plugin::print()

public static function print(Report $report, IOInterface $io): void

The lines Composer prints after an install or an update.

Omnibridge\Composer\Command

CommandProvider class

final class CommandProvider implements CommandProviderCapability CommandProvider.php:7

CommandProvider::getCommands()

public function getCommands(): array

PatchesCommand class

final class PatchesCommand extends BaseCommand PatchesCommand.php:20

composer omnibridge:patches the declared patches: applied, skipped (and why), failed composer omnibridge:patches --diff what the applied ones changed, as a unified diff composer omnibridge:patches --check for CI: fails when a patch no longer finds its target or vendor/ differs from the record composer omnibridge:patches --apply applies them now (what install and update do)

StubsCommand class

final class StubsCommand extends BaseCommand StubsCommand.php:15

composer omnibridge:stubs regenerates the stubs (what dump-autoload does) composer omnibridge:stubs --check for CI: fails when the stubs on disk are not what the providers generate

Omnibridge\Composer\Inventory

Package class

final class Package Package.php:9

An installed package as the engine sees it: where it is, which version, what it declares. The root package is one of them (its path is the project).

const ROOT = '__root__'

public readonly string $name

public readonly string $version

normalized (8.1.6.0, dev-main, 4.9999999.9999999.9999999-dev)

public readonly string $prettyVersion

public readonly string $path

public readonly array $extra

public readonly array $autoload

public readonly bool $root

Package::__construct()

public function __construct(public readonly string $name, public readonly string $version, public readonly string $prettyVersion, public readonly string $path, public readonly array $extra = [], public readonly array $autoload = [], public readonly bool $root = false)

$version

normalized (8.1.6.0, dev-main, 4.9999999.9999999.9999999-dev)

Package::declares()

public function declares(string $key): array

extra.omnibridge.<key>, a list.

Package::isLinked()

public function isLinked(): bool

Installed as a symbolic link (a path repository): a patch would change its source tree, not a copy.

Omnibridge\Composer\Patch

Diff class

final class Diff Diff.php:10

A unified diff of two versions of a file, for omnibridge:patches --diff.

The lines both share at the start and at the end are set aside first, so the longest-common-subsequence table only spans the patched region.

Diff::unified()

public static function unified(string $before, string $after, string $label, int $context = 3): string

InvalidDeclaration class

final class InvalidDeclaration extends InvalidArgumentException InvalidDeclaration.php:6

A declaration in extra.omnibridge that the engine cannot read.

Outcome class

final class Outcome Outcome.php:6

What became of one declared patch.

const APPLIED = 'applied'

const SKIPPED_ABSENT = 'skipped: package not installed'

const SKIPPED_VERSION = 'skipped: version'

const SKIPPED_PHP = 'skipped: php'

const SKIPPED_LINKED = 'skipped: linked package'

const SKIPPED_OPTIONAL = 'skipped: optional, target not found'

const FAILED = 'failed'

public readonly string $key

public readonly string $status

public readonly string $reason

public readonly ?Patch $patch

Outcome::__construct()

public function __construct(public readonly string $key, public readonly string $status, public readonly string $reason = '', public readonly ?Patch $patch = null)

Outcome::failed()

public function failed(): bool

Outcome::line()

public function line(): string

One line: the patch, its status, why.

Patch class

final class Patch Patch.php:25

A patch as a package (or the root) declares it in extra.omnibridge.patches.

{ "id": "process-timeout-from-env", "package": "symfony/process", "versions": "^6.0 || ^7.0 || ^8.0", "php": ">=8.2", "file": "Process.php", "why": "...", "upstream": "https://github.com/...", "optional": false, "do": [{"default": "null", "of": "Symfony\\Component\\Process\\Process::__construct($timeout)"}] }

"do" is one operation or a list of them (the vocabulary: docs/patches.md); "class" names a PatchInterface instead, for what the vocabulary cannot say.

public readonly string $id

public readonly string $declaredBy

public readonly string $package

public readonly string $file

public readonly string $why

public readonly array $operations

public readonly ?string $class

public readonly ?string $versions

public readonly ?string $php

public readonly ?string $upstream

public readonly bool $optional

Patch::__construct()

public function __construct(public readonly string $id, public readonly string $declaredBy, public readonly string $package, public readonly string $file, public readonly string $why, public readonly array $operations = [], public readonly ?string $class = null, public readonly ?string $versions = null, public readonly ?string $php = null, public readonly ?string $upstream = null, public readonly bool $optional = false)

Patch::key()

public function key(): string

The patch's name in listings and in the record: <declaring package>:<id>.

Patch::fromArray()

public static function fromArray(array $declaration, string $declaredBy): self

Patch::describe()

public function describe(): array

What the patch does, one line per operation.

PatchInterface interface

interface PatchInterface PatchInterface.php:14

A patch the vocabulary cannot say, declared with "class" instead of "do".

apply() is a function of the file's published content: it gets the file as released (never an already patched one) and returns it changed. It throws TargetNotFound when it cannot find what it changes; returning the code unchanged counts as not found. The engine records, restores and checks it like any declared patch.

PatchInterface::apply()

public function apply(string $code, Target $target): string

Reconciler class

final class Reconciler Reconciler.php:19

Brings vendor/ to the state the declarations describe, knowing no package.

Every file a patch touches is computed from its published content - the original the record kept, or the file itself when Composer has just written it - with every applicable patch applied in order. A file that no patch applies to any more (its declaring package left, its "versions" or "php" stopped matching) is written back as published. So applying twice changes nothing, and the record says, file by file, what vendor/ holds.

Reconciler::__construct()

public function __construct(readonly string $vendorDir, readonly string $stateDir, ?callable $instantiate = null)

$vendorDir

the project's vendor directory, absolute

$stateDir

where the record lives (vendor/composer/omnibridge)

$instantiate

builds a "class" patch (the engine loads it from its declaring package)

Reconciler::run()

public function run(array $packages, string $php, bool $write = true): Report

$packages

the installed packages, the root among them

$php

the PHP version the project installs for (config.platform.php, else the running one)

$write

false: compute and compare only (listing, --check)

Reconciler::restoreAll()

public function restoreAll(): array

Every recorded file written back as published, the record removed: what the engine does when it is uninstalled.

Returns

the files restored

Reconciler::recordedChanges()

public function recordedChanges(): array

The published and the current content of each recorded file, for --diff.

Record class

final class Record Record.php:13

What the engine applied, in vendor/composer/omnibridge/: patches.json - for each patched file its package and version, the patches applied in order, the SHA-256 of the file as published (before) and as patched (after) - and originals/<package>/<file>, the published file, which a restore writes back. No date, no random id: two installs of the same lock write the same record, which is what omnibridge:patches --check compares in CI.

const FILE = 'patches.json'

Record::__construct()

public function __construct(readonly string $directory)

Record::hash()

public static function hash(string $content): string

Record::files()

public function files(): array

Record::get()

public function get(string $key): ?array

Record::set()

public function set(string $key, string $package, string $version, string $file, string $path, string $original, string $patched, array $patches): void

Record::remove()

public function remove(string $key): void

Record::original()

public function original(string $key): ?string

The published content of a recorded file, null when missing or not the one recorded.

Record::save()

public function save(): void

Report class

final class Report Report.php:6

What a reconciliation found and did.

public array $outcomes = []

public array $patched = []

public array $restored = []

public array $replaced = []

public array $problems = []

Report::failures()

public function failures(): array

Report::applied()

public function applied(): array

Report::isClean()

public function isClean(): bool

Report::failureMessage()

public function failureMessage(): string

Target class

final class Target Target.php:6

The file a patch changes, and the package it belongs to.

public readonly string $package

public readonly string $version

public readonly string $file

public readonly string $path

public readonly string $patch

Target::__construct()

public function __construct(public readonly string $package, public readonly string $version, public readonly string $file, public readonly string $path, public readonly string $patch)

Target::isPhp()

public function isPhp(string $code): bool

Whether the file is PHP (its edits can be marked with a // comment).

TargetNotFound class

final class TargetNotFound extends RuntimeException TargetNotFound.php:10

A patch did not find what it changes in its target: the target's code moved on (or already does what the patch did). Strict: the command fails with the patch's id and why, unless the patch says it is optional.

Omnibridge\Composer\Patch\Operation

DefaultValue class

final class DefaultValue extends Operation DefaultValue.php:17

{"default": "<PHP expression>", "of": "Class::method($parameter)" | "function($parameter)"} (or a list in "of"): the parameter's default value replaced by the expression, written as PHP ("null", "60", "'fr'"). A parameter without a default, or whose default already reads so, is not found.

public readonly string $value

public readonly array $parameters

DefaultValue::__construct()

public function __construct(public readonly string $value, public readonly array $parameters)

DefaultValue::apply()

public function apply(string $code, Target $target): string

DefaultValue::describe()

public function describe(): string

Erase class

final class Erase extends Operation Erase.php:13

{"erase": "<anchor>"}: every line that contains the anchor ("count" to say how many). In a PHP file the line is kept as a comment after the patch's marker, so that what was there stays readable ("mark": false removes it outright); elsewhere it is removed.

public readonly string $anchor

public readonly ?int $expected

public readonly bool $mark

Erase::__construct()

public function __construct(public readonly string $anchor, public readonly ?int $expected = null, public readonly bool $mark = true)

Erase::apply()

public function apply(string $code, Target $target): string

Erase::describe()

public function describe(): string

Insert class

final class Insert extends Operation Insert.php:16

{"prepend": "<lines>", "before": "<anchor>"} and {"append": "<lines>", "after": "<anchor>"}: the lines inserted before (after) every line that contains the anchor ("count" to say how many there must be), at the anchor's indentation unless they bring their own. In a PHP file the inserted lines follow a marker comment naming the patch ("mark": false leaves it out).

public readonly string $text

public readonly string $anchor

public readonly bool $before

public readonly ?int $expected

public readonly bool $mark

Insert::__construct()

public function __construct(public readonly string $text, public readonly string $anchor, public readonly bool $before, public readonly ?int $expected = null, public readonly bool $mark = true)

Insert::apply()

public function apply(string $code, Target $target): string

Insert::describe()

public function describe(): string

Lines trait

trait Lines Lines.php:8

The line-based edits (prepend, append, erase): finding lines, marking them.

Operation class

abstract class Operation Operation.php:15

One edit of the vocabulary. apply() returns the code changed, or throws TargetNotFound - also when the edit would change nothing: a patch whose target already reads as patched has become useless, and saying so is how a maintainer learns to drop it or narrow its "versions".

const VERBS = ['replace' => Replace::class, 'prepend' => Insert::class, 'append' => Insert::class, 'erase' => Erase::class, 'unfinal' => Unfinal::class, 'visibility' => Vi…

The verbs, in the order the docs list them.

Operation::apply()

abstract public function apply(string $code, Target $target): string

Throws

TargetNotFound

Operation::describe()

abstract public function describe(): string

One line for the listing: what the edit does.

Operation::fromArray()

public static function fromArray(array $declaration): self

PhpSource class

final class PhpSource PhpSource.php:21

A PHP file read by nikic/php-parser to locate what an edit changes - a class, a member, a parameter's default - by its name rather than by its spelling. The edit itself is a splice at the node's offsets: the rest of the file keeps its bytes (no pretty-printing).

public readonly string $code

PhpSource::__construct()

public function __construct(public readonly string $code, Target $target)

PhpSource::findClass()

public function findClass(string $class): ?Node\Stmt\ClassLike

PhpSource::findFunction()

public function findFunction(string $function): ?Node\Stmt\Function_

PhpSource::tokens()

public function tokens(): array

PhpSource::token()

public function token(int $from, int $to, array $ids): ?int

The index of the first token from $from to $to (inclusive) whose id is one of $ids, or null.

PhpSource::afterAttributes()

public function afterAttributes(Node $node): int

The first token of a declaration after its attributes (#[...]) and the blanks that follow them.

PhpSource::splice()

public static function splice(string $code, array $edits): string

$edits applied to $code: [start offset, end offset (exclusive), text], from the last to the first so that offsets stay valid.

Replace class

final class Replace extends Operation Replace.php:12

{"replace": "<text>", "with": "<text>", "count": n}: every occurrence of the exact text (whitespace included); "count", when given, is how many there must be. Unmarked: the text may sit inside an expression.

public readonly string $search

public readonly string $replacement

public readonly ?int $expected

Replace::__construct()

public function __construct(public readonly string $search, public readonly string $replacement, public readonly ?int $expected = null)

Replace::apply()

public function apply(string $code, Target $target): string

Replace::describe()

public function describe(): string

ReturnType class

final class ReturnType extends Operation ReturnType.php:15

{"returns": "<type>", "of": "Class::method()" | "function()"} (or a list in "of"): the declared return type replaced, written as PHP ("void", "?string", "static"). A method without a declared return type, or whose type already reads so, is not found.

public readonly string $type

public readonly array $functions

ReturnType::__construct()

public function __construct(public readonly string $type, public readonly array $functions)

ReturnType::apply()

public function apply(string $code, Target $target): string

ReturnType::describe()

public function describe(): string

Unfinal class

final class Unfinal extends Operation Unfinal.php:14

{"unfinal": "Vendor\\Package\\Class"} (or a list): the class's final keyword and the @final line of its docblock removed - the one that Symfony's DebugClassLoader reads. A class that is neither is not found.

public readonly array $classes

Unfinal::__construct()

public function __construct(public readonly array $classes)

Unfinal::apply()

public function apply(string $code, Target $target): string

Unfinal::describe()

public function describe(): string

Visibility class

final class Visibility extends Operation Visibility.php:20

{"visibility": "protected", "of": "Class::$property" | "Class::method()" | "Class::CONSTANT" | "Class::*"} (or a list in "of"): the member's visibility keyword changed - a promoted constructor parameter counts as a property. "Class::*" changes every private member of the class. A member that already has that visibility is not found.

public readonly string $visibility

public readonly array $members

Visibility::__construct()

public function __construct(public readonly string $visibility, public readonly array $members)

Visibility::apply()

public function apply(string $code, Target $target): string

Visibility::describe()

public function describe(): string

Omnibridge\Composer\Stub

AbstractStub class

abstract class AbstractStub implements StubInterface AbstractStub.php:23

The generic generator: mirrors the classes of a source namespace under a target namespace, one stub per class -

namespace App\Entity; if (!class_exists('\App\Entity\User')) { class User extends \Base\Entity\User } }

• for a package that, at run time, makes each Target\X an alias of Source\X unless the application defines Target\X itself (omnibase's Base\ and App\). The stub tells an IDE what the alias gives; the guard keeps it harmless should anything ever include it.

A class gets a stub when it is a plain class (not abstract, final or readonly; not an interface, a trait or an enum) and the application has no file of the same relative path in getApplicationDirectory().

AbstractStub::generate()

public function generate(StubContext $context): iterable

AbstractStub::declaration()

public static function declaration(string $code): ?array

The first class-like declaration of a file: its namespace, name, kind and modifiers, from PHP's tokenizer.

StubContext class

final class StubContext StubContext.php:6

Where a stub provider runs: the project, its vendor directory, the declaring package.

public readonly string $projectDir

public readonly string $vendorDir

public readonly string $packageDir

public readonly string $packageName

StubContext::__construct()

public function __construct(public readonly string $projectDir, public readonly string $vendorDir, public readonly string $packageDir, public readonly string $packageName)

StubGenerator class

final class StubGenerator StubGenerator.php:11

Runs the declared stub providers into one directory the engine owns (vendor/composer/omnibridge/stubs): each provider's files under its name, a file written only when its content changes, what no provider returns any more removed.

StubGenerator::__construct()

public function __construct(readonly string $outputDir)

StubGenerator::run()

public function run(array $providers, bool $write = true): StubReport

$write

false: compare only (--check)

StubInterface interface

interface StubInterface StubInterface.php:16

A stub provider, declared by a package in extra.omnibridge.stubs (its class name, autoloaded from that package). The engine runs it on post-autoload-dump and writes what it returns under vendor/composer/omnibridge/stubs/<name>/ - a directory no autoloader reads: stubs are for an IDE and static analysis, never definitions at run time.

generate() must be deterministic: the same installed tree gives the same files, byte for byte (no date, no absolute path), so that composer omnibridge:stubs --check can compare.

StubInterface::getName()

public function getName(): string

The subdirectory of the stubs, unique among the providers (Entity, Repository...).

StubInterface::generate()

public function generate(StubContext $context): iterable

Returns

path relative to the provider's directory => file content

StubReport class

final class StubReport StubReport.php:6

What a stub run generated, wrote and removed.

public array $counts = []

public array $written = []

public array $removed = []

public array $problems = []

StubReport::summary()

public function summary(): string