omnisense/omnibridge

Installation

Requirements

Nothing else is required: no framework, no ORM, no extension that composer.json declares. Two optional needs:

• Schema\Database\MySqlSchema::read() takes a \PDO connected to MySQL (ext-pdo, ext-pdo_mysql in the application).
• Schema\CamelCaseNaming calls mb_strtolower(), mb_substr() and mb_strtoupper().

composer require omnisense/omnibridge:1.x-dev

The branch 1.x is published as 1.x-dev (extra.branch-alias). The package replaces omniscient/omnibridge, its former name.

Plain PHP

The registry needs no host: set the services by hand. A complete script, with an Urls of its own:

<?php

require 'vendor/autoload.php';

use Omnibridge\Contract\Urls;
use Omnibridge\Exception\MissingContractException;
use Omnibridge\Runtime;

final class PlainUrls implements Urls
{
    public function path(string $name, array $parameters = []): string
    {
        return '/'.$name.($parameters ? '/'.implode('/', $parameters) : '');
    }

    public function url(string $name, array $parameters = []): string
    {
        return 'https://example.org'.$this->path($name, $parameters);
    }

    public function asset(string $path): string
    {
        return '/build/'.ltrim($path, '/');
    }
}

Runtime::alias(Urls::class, 'Legacy\Contract\Urls');
Runtime::set(Urls::class, new PlainUrls());

echo Runtime::urls()->path('article', ['slug' => 'le-fuji']), "\n";
echo Runtime::get('Legacy\Contract\Urls')->url('article', ['slug' => 'le-fuji']), "\n";
echo get_class(Runtime::clock()), "\n";
var_dump(Runtime::find(\Omnibridge\Contract\Access::class));

try {
    Runtime::translations();
} catch (MissingContractException $e) {
    echo $e->getMessage(), "\n";
}

Its output, run in the package's harness image (PHP 8.2.34, 2026-10-27):

/article/le-fuji
https://example.org/article/le-fuji
Omnibridge\SystemClock
NULL
No Omnibridge\Contract\Translations in the runtime: the host fills it at boot (its omnibridge bridge, omnisense/omnibase's bundle under Symfony), or Omnibridge\Runtime::set() / setContainer() before it is asked.

• The former name Legacy\Contract\Urls is the same interface (class_alias): asked by it, the registry answers the service set under the new name.
• No clock was given: the machine's (SystemClock).
• find() answers null for a contract nobody filled; translations() (like every accessor but clock()) throws.

A container works the same way: any PSR-11 container whose ids are the interfaces' names.

Runtime::setContainer($container);   // $container->has(Urls::class), ->get(Urls::class)...

Under a framework

The application does not fill the registry itself: its bridge does, at boot.

Each bridge's manual has its own installation page. A host bridge requires this package; this package requires none of them.

Contracts

Nine interfaces under Omnibridge\Contract\. Each says what an application asks of its host, never how the host answers: a bridge implements it over its framework's services (which bridge answers which). Every one of them was Base\Contract\<Name> in omnisense/omnibase before; those former names were removed at omnibase 4's final pass (Former names).

The application reaches a contract through the registry (Runtime::urls()..., The registry) or, inside a framework, by autowiring the interface: both bridges bind every adapter under its interface's name.

Urls

Addresses, as an application asks for them: a route by its name, as a path or whole, and a public file of the build.

A route that does not exist is the host router's error (Symfony's RouteNotFoundException, Laravel's RouteNotFoundException or InvalidArgumentException): the contract adds none of its own. Answered by Omnibridge\Symfony\RouterUrls and Omnibridge\Laravel\RouterUrls; a Twig page asks the same object through omnibridge/twig's path(), url() and asset().

Translations

The application's texts: a message in the page's language, from its catalogues (ICU messages: {0} and {name} placeholders, plurals), and whether the catalogues hold a key at all.

exists() is for code that tries several keys in turn (an entity's name in a namespace, then in its parent's). Formerly two interfaces: Omnibridge\Twig\Contract\Translations (with trans() alone) and Base\Contract\Translations (with exists()), both removed since; now one, so one object answers a page and the application's code alike. Answered by Omnibridge\Symfony\TranslatorTranslations and Omnibridge\Laravel\CatalogueTranslations (which reads ICU catalogues with symfony/translation).

Locales

The languages of the site, language and country joined by a dash (fr-FR, en-GB). A bridge whose host names them otherwise (Laravel's fr) gives them in this form. Named in the plural so as not to shadow PHP's \Locale where it is imported.

Answered by Omnibridge\Laravel\Contract\AppLocales; under Symfony by omnisense/omnibase's Base\Bridge\Symfony\LocalizerLocales (omnibridge/symfony binds none: an application's languages are its own).

Access

What the visitor may do: an attribute (a role, ROLE_ADMIN, or a permission a policy answers, edit on a subject) granted or not, and who the visitor is.

Symfony's authorization checker and token storage (Omnibridge\Symfony\Contract\SecurityAccess), Laravel's gate and guard (Omnibridge\Laravel\Contract\GateAccess) answer the same two questions.

Sessions

The visitor's session, as the application ends it.

omnisense/omnibase's User::logout() asks it first, and kicks the user out of its sessions elsewhere when it answers false. Symfony's token storage (SecuritySessions), Laravel's guard logout() (GuardSessions).

Tokens

The token a form carries for an intent, against cross-site requests: what a page's POST (or a script's request) sends back and its action checks.

Symfony's CSRF token manager has one token per intent (CsrfTokens); Laravel's session token is one for every intent (SessionTokens). A token made by one host is checked by that host only: a page rendered by Symfony posts to Symfony.

Files

The stored files as the application sees them: where a file is served from and where PHP can read it, by its path in a storage. Nothing of how it is stored (Flysystem, a disk, a bucket).

A storage is named as the application's configuration names it (local.uploads, s3.private...), null for the default one; each bridge maps those names to its host's storages.

Answered by Omnibridge\Laravel\Contract\DiskFiles (Laravel's disks); under Symfony by omnisense/omnibase's Base\Bridge\Symfony\FlysystemFiles.

Routes

What the routes are beyond their addresses (Urls makes those).

Icons are a route's metadata where the host keeps some (omnibase's #[Iconize] under Symfony); a host without answers null. Answered by Omnibridge\Laravel\Contract\RouterRoutes; under Symfony by omnisense/omnibase's Base\Bridge\Symfony\RouterRoutes.

Environment

What the application runs as.

Symfony's kernel.environment, kernel.debug and kernel.secret (KernelEnvironment); Laravel's APP_ENV, app.debug and app.key (AppEnvironment).

The clock and the events

No contract of their own: the PSR interfaces are already generic.

• Psr\Clock\ClockInterface, asked by Runtime::clock(). A host gives its own (symfony/clock's, which a test can freeze; omnibridge/laravel's DateClock over Laravel's dates). When none was given, the registry answers Omnibridge\SystemClock, whose now() is new \DateTimeImmutable() - the machine's time in PHP's default time zone.
• Psr\EventDispatcher\EventDispatcherInterface, asked by Runtime::events(): Symfony's event_dispatcher, omnibridge/laravel's DispatcherEvents over Laravel's dispatcher. There is no fallback: asked and not given, it throws MissingContractException.

Writing an adapter

A host that has no bridge yet implements the interfaces it can answer and fills the registry (The registry). An adapter:

• answers for the current request or command, not for the one it was built in: a long-running worker builds it once (read the request, the locale, the user when called, not in the constructor);
• throws its framework's own exception for what the framework refuses (an unknown route); the contract adds none;
• gives locales as xx-XX, whatever its host's own form.

An application that runs on two hosts asserts the same answers on both: lesringostars' parity suite renders the same pages through both bridges and compares them.

The registry

Omnibridge\Runtime is the registry through which an application's framework-free code reaches the contracts its host answers: an entity's getter, a value object, a screen's builder asks Runtime::urls(), ::access()... instead of a framework's services. Every method is static; the state is the class's own (private static properties), shared by any class that extends it.

Filling the registry

A host fills it once, at boot, in one of two ways - or both.

With a container

Runtime::setContainer(?Psr\Container\ContainerInterface $container): void
Runtime::getContainer(): ?Psr\Container\ContainerInterface

A PSR-11 container whose ids are the contracts' interface names. Under Symfony it is a service locator (omnibridge.contracts, made by omnibridge/symfony's ContractsPass; base.contracts on an omnisense/omnibase site); under Laravel the application itself, whose bindings are named by the interfaces (omnibridge/laravel's OmnibridgeServiceProvider).

• Each contract is resolved from the container the first time it is asked, then kept.
• A different container (another kernel booted, a test's new application) forgets every service resolved from the previous one. Setting the same container again keeps them.
• setContainer(null) detaches the container: omnibridge/symfony's bundle does it at shutdown, when the registry still holds its locator.

One service at a time

Runtime::set(string $contract, ?object $service): void

A service given by hand wins over the container's. It must implement the contract, or MissingContractException is thrown at once ("The runtime's X is a Y, which does not implement it."). set($contract, null) takes it back, and forgets what the container gave for it too, so the next call resolves again.

Asking the registry

The order of the lookup: the service set by hand, then the one already resolved, then the container, asked by the contract's own name, then by the name asked, then by each former name (the first id the container has() is used). A service the container gives that does not implement the contract throws MissingContractException::notAn().

Any interface name can be asked: get() is not limited to the nine contracts. A family keeps its own contracts in the same registry (omnibase's Base\Contract\Nouns...).

The accessors

Typed shortcuts for get():

The SystemClock fallback is kept as resolved: a container set afterwards (a different one) forgets it, and the host's clock is asked again.

Resetting

Runtime::reset(): void

Everything forgotten: no container, nothing set, nothing resolved. The former names stay: they are declarations made when the autoloader loaded, not state. A test's tearDown() calls it (Testing).

Former names

Runtime::alias(string $contract, string $former): void
Runtime::formerNames(string $contract): list<string>

alias() keeps a contract (or any class of a family) reachable under a former name:

1. class_alias($contract, $former) - an alternate name, not a subclass: one interface, one reflection name. Skipped when a class or interface of that name is already loaded.
2. The registry told: a service bound in the container under the former name only is found when the new name is asked, and MissingContractException lists the former names.

The package that owned the name declares it, when Composer's autoloader loads (its autoload.files), never on demand: PHP autoloads nothing for a parameter's type or an instanceof, so a lazy alias would leave a type hint of the former name unknown. Declaring the same pair twice is harmless.

A name is always resolved to its own: Runtime::get('Base\Contract\Urls') and Runtime::get(Urls::class) answer the same object, set under either name.

A family's own registry

Runtime is not final. An application family adds its own contracts' accessors in a class of its own over the same state:

namespace Acme\Contract;

use Omnibridge\Runtime as Registry;

final class Runtime extends Registry
{
    public static function invoices(): Invoices
    {
        return self::get(Invoices::class);
    }
}

Acme\Contract\Runtime::urls() and Omnibridge\Runtime::urls() answer the same service; a service set through either class is seen by both (the core's tests check it with a fixture FamilyRuntime). omnisense/omnibase's Base\Contract\Runtime is such a class: its parameters(), nouns(), media(), pictures(), texts() and mailer().

Where to ask it, and where not

• Ask it in code that cannot be given its dependencies: an entity, a value object, a static helper, a Twig page's data built outside a controller.
• In a service a framework builds, prefer a constructor argument typed by the contract: both bridges bind each adapter under its interface's name, and the test needs no registry.
• Ask at the moment of use, not in a constructor or a static initialiser: a long-running worker (FrankenPHP, Octane) may replace the container between two requests.

The schema

Omnibridge\Schema describes the structure of an application's data once, outside any ORM: the entities - each class, its table, its fields and relations, its inheritance - and the tables they make, with their columns, keys, indexes and foreign keys. Three steps:

1. Declarations (Schema\Declaration\*): what the entity classes declare, read from their attributes without instantiating them, or kept as data.
2. The builder (Schema\Builder): the declarations completed the way Doctrine completes its metadata, an application's rules applied, then the tables Doctrine's SchemaTool would create.
3. The description (Schema\Description): plain, readonly data - entities and tables - that a persistence bridge maps, a JSON file keeps, and Schema\Database\MySqlSchema compares with a database.

omnibridge/doctrine is the Doctrine side: its DeclarationDriver gives Doctrine its metadata from the same declarations, its MetadataDescription reads an entity manager's metadata back into a Description, and its tests compare the two.

A complete example

Two entities, a many-to-one and a many-to-many relation, described with no ORM installed (the Doctrine\ORM\Mapping attribute classes need not exist):

<?php

namespace App\Entity {
    use Doctrine\ORM\Mapping as ORM;

    #[ORM\Entity]
    class Thread
    {
        #[ORM\Id, ORM\GeneratedValue, ORM\Column]
        public ?int $id = null;

        #[ORM\Column(unique: true)]
        public string $slug;

        #[ORM\Column(nullable: true)]
        public ?\DateTimeImmutable $publishedAt = null;

        #[ORM\ManyToOne]
        public ?Thread\Tag $mainTag = null;

        #[ORM\ManyToMany(targetEntity: Thread\Tag::class)]
        public iterable $tags = [];
    }
}

namespace App\Entity\Thread {
    use Doctrine\ORM\Mapping as ORM;

    #[ORM\Entity]
    class Tag
    {
        #[ORM\Id, ORM\GeneratedValue, ORM\Column]
        public ?int $id = null;

        #[ORM\Column(length: 64)]
        public string $name;
    }
}

namespace {
    require 'vendor/autoload.php';

    use Omnibridge\Schema\Builder;

    $description = (new Builder())->build([App\Entity\Thread::class, App\Entity\Thread\Tag::class]);

    foreach ($description->tables as $table) {
        echo $table->name, ' (', implode(', ', $table->primaryKey), ")\n";
        foreach ($table->columns as $column) {
            echo '  ', $column->name, ' ', $column->type, $column->length ? '('.$column->length.')' : '', $column->nullable ? ' null' : ' not null', $column->autoincrement ? ' auto_increment' : '', "\n";
        }
        foreach ($table->indexes as $index) {
            echo '  index ', $index->name, $index->unique ? ' unique' : '', ' (', implode(', ', $index->columns), ")\n";
        }
        foreach ($table->foreignKeys as $key) {
            echo '  foreign key ', $key->name, ' (', implode(', ', $key->columns), ') -> ', $key->table, ' (', implode(', ', $key->referencedColumns), ')', $key->onDelete ? ' on delete '.$key->onDelete : '', "\n";
        }
    }

    $tags = $description->entity(App\Entity\Thread::class)->relation('tags');
    echo $tags->kind, ' ', $tags->target, ' join table ', $tags->joinTable->name, "\n";
    echo json_encode($description->table('thread')->column('slug')->toArray()), "\n";
}

Its output (the package's harness image, PHP 8.2.34, 2026-10-27):

thread (id)
  id integer not null auto_increment
  slug string(255) not null
  publishedAt datetime_immutable null
  mainTag_id integer null
  index IDX_31204C83941A39FD (mainTag_id)
  index UNIQ_31204C83989D9B62 unique (slug)
  foreign key FK_31204C83941A39FD (mainTag_id) -> threadTag (id)
threadTag (id)
  id integer not null auto_increment
  name string(64) not null
thread_tags (thread_id, threadTag_id)
  thread_id integer not null
  threadTag_id integer not null
  index IDX_EB0D88A83DC29580 (threadTag_id)
  index IDX_EB0D88A8E2904019 (thread_id)
  foreign key FK_EB0D88A83DC29580 (threadTag_id) -> threadTag (id) on delete CASCADE
  foreign key FK_EB0D88A8E2904019 (thread_id) -> thread (id) on delete CASCADE
many_to_many App\Entity\Thread\Tag join table thread_tags
{"name":"slug","type":"string","length":255}

What the builder completed: the column types from the properties' types (int integer, string string of 255, ?\DateTimeImmutable datetime_immutable), the table names by the camel case naming (App\Entity\Thread\Tag is threadTag), the many-to-one's target from the property's type and its join column mainTag_id, the join table thread_tags with a column toward each side (on delete cascade), the auto-increment of an AUTO generated identifier, the unique index of the unique column, the index behind each foreign key, and every generated name as DBAL generates it. The plain form of a column leaves out what its constructor would give anyway (nullable: false).

Declarations

Reading the attributes: AttributeReader

use Omnibridge\Schema\Declaration\AttributeReader;

$declaration = (new AttributeReader())->read(App\Entity\Thread::class);   // ?ClassDeclaration

read(string|\ReflectionClass $class): ?ClassDeclaration reads a class by reflection: each attribute's name and arguments (ReflectionAttribute::getArguments()), never newInstance(), so the attribute classes need not exist and doctrine/orm need not be installed.

• Only the attributes of the vocabulary are read (Doctrine\ORM\Mapping\* with a name listed in Vocabulary::PARAMETERS); every other attribute is ignored.
• The properties are read in the order reflection lists them, inherited ones included, each with the class that declares it; a property without a mapping attribute is left out. Of the methods, only public ones that carry a mapping attribute (the lifecycle callbacks).
• A positional argument is named after the parameter it fills (#[ORM\Column('slug')] is name: 'slug'); a nested attribute written as an object (new ORM\JoinColumn(...) inside a JoinTable) becomes an Attribute of its initialised properties, those equal to their default left out. That object is instantiated by PHP when the arguments are read: its class must exist.
• A constant written as an argument (UtcDateTimeImmutableType::NAME) is evaluated by PHP, so its class must load.
• A class that is neither Entity, MappedSuperclass nor Embeddable reads null. Each class is read once per reader.

What a declaration holds

Each has toArray() and fromArray(): the plain form, where a nested attribute is {"@attribute": {"name": ..., "arguments": ...}} and empty lists are left out.

Keeping declarations as data: DeclarationSet

use Omnibridge\Schema\Declaration\AttributeReader;
use Omnibridge\Schema\Declaration\DeclarationSet;

$set = DeclarationSet::of(new AttributeReader(), $entityClasses);
file_put_contents('declarations.json', json_encode($set->toArray()));

$again = DeclarationSet::fromArray(json_decode(file_get_contents('declarations.json'), true));
$builder = new Omnibridge\Schema\Builder($again);

DeclarationSet implements Declarations over a list of ClassDeclarations: of() gathers the declarations of classes from another source (the classes it does not map left out), read() answers by class name, all() lists them by class, toArray()/fromArray() are the plain form. A set can come from a file written once, or from another vocabulary turned into this one.

The builder still reflects on the classes themselves (their parents, their properties' types): a DeclarationSet replaces the attributes, not the classes.

The Declarations interface

interface Declarations
{
    public function read(string|\ReflectionClass $class): ?ClassDeclaration;
}

Where the builder and omnibridge/doctrine's DeclarationDriver get the declarations from. AttributeReader and DeclarationSet are the two implementations here.

The vocabulary

Vocabulary holds the mapping attributes as data, kept equal to doctrine/orm 3's constructors (omnibridge/doctrine's VocabularyTest compares them parameter by parameter):

The attributes it knows: AssociationOverride, AssociationOverrides, AttributeOverride, AttributeOverrides, Cache, ChangeTrackingPolicy, Column, CustomIdGenerator, DiscriminatorColumn, DiscriminatorMap, Embeddable, Embedded, Entity, EntityListeners, GeneratedValue, HasLifecycleCallbacks, Id, Index, InheritanceType, InverseJoinColumn, JoinColumn, JoinColumns, JoinTable, ManyToMany, ManyToOne, MappedSuperclass, OneToMany, OneToOne, OrderBy, the eight lifecycle attributes, SequenceGenerator, Table, UniqueConstraint, Version. All are read into declarations; the builder uses a subset of them.

The builder

use Omnibridge\Schema\Builder;
use Omnibridge\Schema\CamelCaseNaming;
use Omnibridge\Schema\Declaration\AttributeReader;

$builder = new Builder(
    declarations: new AttributeReader(),   // or a DeclarationSet
    naming: new CamelCaseNaming(),         // how the unnamed is named
    rules: [],                             // list<Builder\Rule>, the application's conventions
    autoGenerator: 'identity',             // what GeneratedValue(strategy: 'AUTO') becomes
);
$description = $builder->build($classNames);

What the builder reads

Following Doctrine's ClassMetadataFactory and attribute driver, for each class, its mapped parents first:

• The parent's state: inheritance type, discriminator column and map, generator, every field and relation (marked inherited from an entity parent, declared in the class that declares it), identifier, subclasses. A single-table child takes its root's table name, indexes, unique constraints and options; a mapped superclass's indexes are copied into its children.
• The class: MappedSuperclass, Embeddable; Table (name, backquotes stripped, and options); each Index and UniqueConstraint written on the class (columns or fields, flags, options, by name or by position); InheritanceType, DiscriminatorColumn (default dtype, string, 255) and DiscriminatorMap.
• Each property not inherited: a Column is a field (type, length, precision, scale, unique, nullable, index, options, enumType, name with backquotes stripped; Id and its position; GeneratedValue's strategy); else a OneToOne, OneToMany, ManyToOne or ManyToMany is a relation (targetEntity, mappedBy, inversedBy, indexBy, OrderBy, JoinColumns, JoinTable and InverseJoinColumns, Id).
• Completion (Draft::mapField(), mapRelation()):
  • a field's type from its property's type when it names none: \DateInterval dateinterval, \DateTime datetime, \DateTimeImmutable datetime_immutable, array json, bool boolean, float float, int integer, string string; a backed enumeration its backing type, with enumType set (a pure enumeration is a LogicException); otherwise string;
  • a column name from the naming; a duplicate column (or one named as the discriminator) is a LogicException;
  • a to-one relation's target from its property's type when it names none; a target without a namespace is taken in the class's namespace; a relation without target is a LogicException;
  • the owning side: no mappedBy, and never a one-to-many;
  • an owning to-one's join columns: one by default, <property>_id toward id, nullable unless the relation is part of the identifier, unique for a one-to-one outside a single-table hierarchy;
  • an owning many-to-many's join table: its name from the naming, its join columns toward each side (<table>_id, not null, on delete CASCADE when the join table names none; a relation of a class to itself names them <table>_source and <table>_target);
  • the identifier in Id position order.
• The generator: a child of an entity keeps its root's; an AUTO root's becomes autoGenerator.
• The default discriminator map, for a root of a hierarchy that declares none: the class and each of its subclasses among the classes given, each under its short name in lower case.

Then the tables, following SchemaTool over DBAL: one table per class of a joined hierarchy (a child's identifier its primary key and a foreign key to the root's table, on delete CASCADE, not auto-increment), one table for a single-table hierarchy (the children's columns nullable, the discriminator in it), the discriminator column in the root's table, a join table per owning many-to-many (its primary key both sides' columns), a join column per owning to-one of its referenced column's type, a unique index per unique column, an index per index: true column, the declared indexes and unique constraints (a unique constraint replacing a plain index of the same columns), an index behind each foreign key that no index of the same columns already backs (and dropped when a later index fulfils it), an index the primary key spans dropped. A string column without a length is 255 long. A default option is kept when it is a scalar (a backed enumeration's value).

Not described, so a description differs from Doctrine's tables when they are used: Embedded properties (no column for them; Naming::embeddedFieldToColumnName() is there but the builder never asks it), AttributeOverrides and AssociationOverrides, the indexes and uniqueConstraints arguments of #[Table] (write #[Index] and #[UniqueConstraint] on the class), Table's schema, SequenceGenerator and CustomIdGenerator's classes, and the collations, charsets and comments of columns. omnibase's entities use none of them.

Rules

interface Rule
{
    public function before(Draft $class, ClassDeclaration $declaration, Builder $builder): void;
    public function declared(Draft $class, ClassDeclaration $declaration, Builder $builder): void;
    public function loaded(Draft $class, ClassDeclaration $declaration, Builder $builder): void;
}

An application's own convention over what its classes declare - what an ORM's listeners add to its metadata. Applied to each class, every rule in order, at the three moments an ORM gives its listeners:

A rule changes the draft through its public properties and mapField(), mapRelation(), setDiscriminatorMap(), addSubClass(), setIdentifier(); $builder->draft() gives another class (a translation's parent), $builder->classes() the whole set. omnisense/omnibase's rules (its translations' relations, its discriminator entries, its vaults' unique keys, its order columns) are rules of this kind.

use Omnibridge\Schema\Builder;
use Omnibridge\Schema\Builder\Draft;
use Omnibridge\Schema\Builder\Rule;
use Omnibridge\Schema\Declaration\ClassDeclaration;

/** Every entity gets a nullable `locale` column, unless it maps one. */
final class LocaleRule implements Rule
{
    public function before(Draft $class, ClassDeclaration $declaration, Builder $builder): void {}

    public function declared(Draft $class, ClassDeclaration $declaration, Builder $builder): void
    {
        if (!$class->isMappedSuperclass && !$class->hasField('locale')) {
            $class->mapField(['fieldName' => 'locale', 'type' => 'string', 'length' => 5, 'nullable' => true]);
        }
    }

    public function loaded(Draft $class, ClassDeclaration $declaration, Builder $builder): void {}
}

Given to the example's builder (new Builder(rules: [new LocaleRule()])), it adds locale string(5) null to thread and to threadTag (run in the harness image, 2026-10-27).

The draft

Builder\Draft is a class while it is built, its mappings in plain arrays:

Methods: naming(), isInheritanceTypeNone(), isInheritanceTypeSingleTable(), isInheritanceTypeJoined(), isRootEntity(), hasField(), hasAssociation(), mapField(array), mapRelation(array), setDiscriminatorMap(array), addSubClass(string) (only a real subclass), setIdentifier(array $identifier, array $positions).

The description

Every class of the description is final, readonly, and carries toArray() and fromArray() (the Exports trait: each property by its name, a value equal to its constructor's default left out, an enumeration by its value or name). Description adds toJson() (pretty printed, slashes and Unicode unescaped, zero fractions kept, a final new line) and fromJson(); both throw \JsonException on invalid JSON.

Description

Entity

field(string) and relation(string) throw \OutOfBoundsException for a property that is none.

Field

Relation

isToOne(): bool is true for one-to-one and many-to-one.

JoinColumn: name, referencedColumn (default id), nullable (default true), unique (false), onDelete (?string). JoinTable: name, joinColumns (toward the owner), inverseJoinColumns (toward the target).

Inheritance

type (Inheritance::SINGLE_TABLE single_table or JOINED joined), column (a Column: the discriminator), map (value => class, sorted by value), value (this class's value).

Table, Column, Index, ForeignKey

Naming

interface Naming
{
    public function classToTableName(string $className): string;
    public function propertyToColumnName(string $propertyName, string $className): string;
    public function embeddedFieldToColumnName(string $propertyName, string $embeddedColumnName, string $className, string $embeddedClassName): string;
    public function referenceColumnName(): string;
    public function joinColumnName(string $propertyName, string $className): string;
    public function joinTableName(string $sourceEntity, string $targetEntity, string $propertyName): string;
    public function joinKeyColumnName(string $entityName, ?string $referencedColumnName): string;
    public function generatedName(string $table, array $columns, string $prefix): string;
}

The questions Doctrine's naming strategy asks, plus generatedName() (an index, unique index or foreign key nobody named; prefix idx, uniq or fk). omnibridge/doctrine's NamingStrategy answers Doctrine with a Naming, so one class says how a class becomes a table.

CamelCaseNaming

The omni family's names. Not final; constructed with the namespaces a table name leaves out (default ['App\\', 'Base\\']).

Constants: TABLE_NAME_SIZE and IDENTIFIER_SIZE (64, MySQL's limit), TABLE_I18N_SUFFIX (Intl). A table name longer than 64 characters is a \LengthException ("Table name will be truncated for ...").

Comparing with a database: MySqlSchema

Schema\Database\MySqlSchema reads a MySQL database's schema from information_schema (through PDO, read-only, no ORM) and lists every difference with a description - an independent check that the description is the database: nothing of the persistence that made the tables is asked.

use Omnibridge\Schema\Database\MySqlSchema;

$pdo = new \PDO('mysql:host=database;dbname=app', 'app', $password);
$schema = MySqlSchema::read(
    $pdo,
    database: null,                                  // DATABASE() when null
    ignore: ['doctrine_migration_versions'],         // tables the description does not hold
    types: ['thread_state' => MySqlSchema::enumeration(...)],   // an application's own types
);
foreach ($schema->differences($description) as $difference) {
    echo $difference, "\n";      // "thread.slug: type "varchar(255)" / "varchar(191)""
}

What differences() compares, and the lines it writes:

• tables on one side only: <table>: a table of the description, not of the database, or the reverse;
• the column lists: <table>: columns [missing] missing, [more] more;
• each column's SQL type, nullable, default (a boolean as 1/0) and auto-increment: <table>.<column>: <what> <expected> / <actual>;
• the primary key; each index by name (columns, unique, flags) and each foreign key by name (columns, table, referenced columns, on delete, on update): missing, more, or <expected> / <actual>.

Collations, character sets and comments are not compared. The portable types and their SQL types:

A run with no database, on a schema given as data (the harness image, 2026-10-27):

<?php

require 'vendor/autoload.php';

use Omnibridge\Schema\Column;
use Omnibridge\Schema\Database\MySqlSchema;
use Omnibridge\Schema\Description;
use Omnibridge\Schema\Table;

$description = new Description([], [
    'page' => new Table('page', [
        'id' => new Column('id', 'integer', autoincrement: true),
        'title' => new Column('title', 'string', length: 120),
        'state' => new Column('state', 'page_state', values: ['draft', 'published']),
    ], ['id']),
]);

$database = MySqlSchema::of([
    'page' => [
        'columns' => [
            'id' => ['type' => 'int(11)', 'nullable' => false, 'default' => null, 'autoincrement' => true],
            'title' => ['type' => 'varchar(255)', 'nullable' => false, 'default' => null, 'autoincrement' => false],
            'state' => ['type' => "enum('draft','published')", 'nullable' => false, 'default' => null, 'autoincrement' => false],
        ],
        'primaryKey' => ['id'],
        'indexes' => [],
        'foreignKeys' => [],
    ],
    'doctrine_migration_versions' => ['columns' => [], 'primaryKey' => [], 'indexes' => [], 'foreignKeys' => []],
], ['page_state' => MySqlSchema::enumeration(...)]);

print_r($database->differences($description));

Array
(
    [0] => doctrine_migration_versions: a table of the database, not of the description
    [1] => page.title: type "varchar(120)" / "varchar(255)"
)

int(11) matched int (the display width), the enum matched the application's type.

Errors

The package has one exception class of its own. The schema throws PHP's SPL exceptions, each with a message that names what is wrong.

MissingContractException

Omnibridge\Exception\MissingContractException, final, extends \LogicException. Formerly Base\Exception\MissingContractException, an alias removed at omnibase 4's final pass. Two factories:

It is a LogicException on purpose: a missing contract is a wiring mistake (a bridge not installed, a package of SecurityBundle missing, a test that forgot Runtime::set()), not a condition to recover from at run time. Code that can do without a contract asks Runtime::find() (null) or Runtime::has() first, never catches the exception.

Under Symfony a contract whose framework service is absent is removed from the locator at compile time (omnibridge/symfony's ContractsPass): with no SecurityBundle, Runtime::access() throws this exception rather than a container error.

The schema's exceptions

Testing

Testing code that asks the registry

The registry is static state: a test sets what the code under test asks, and forgets it after.

use Omnibridge\Contract\Access;
use Omnibridge\Contract\Urls;
use Omnibridge\Runtime;
use PHPUnit\Framework\TestCase;

final class ArticleLinkTest extends TestCase
{
    protected function setUp(): void
    {
        Runtime::reset();
    }

    protected function tearDown(): void
    {
        Runtime::reset();
    }

    public function testTheLinkIsTheRoutesPath(): void
    {
        $urls = $this->createMock(Urls::class);
        $urls->method('path')->with('article', ['slug' => 'le-fuji'])->willReturn('/articles/le-fuji');
        Runtime::set(Urls::class, $urls);

        self::assertSame('/articles/le-fuji', (new Article('le-fuji'))->link());
    }

    public function testAnAdministratorSeesTheEditButton(): void
    {
        Runtime::set(Access::class, new class implements Access {
            public function isGranted(mixed $attribute, mixed $subject = null): bool { return 'ROLE_ADMIN' === $attribute; }
            public function getUser(): ?object { return new \stdClass(); }
        });

        self::assertTrue((new Article('le-fuji'))->isEditable());
    }
}

• Runtime::reset() forgets the container, the services set and those resolved; the former names stay.
• A frozen clock: Runtime::set(Psr\Clock\ClockInterface::class, $clock) with any PSR-20 clock (symfony/clock's MockClock, or an anonymous class).
• A service that does not implement the contract is refused at set(), so a mock must be of the interface.
• Inside a framework's functional test (Symfony's KernelTestCase, Laravel's TestCase), the bridge fills the registry when the kernel or the application boots; a new kernel is a new container, and the registry forgets the previous one's services by itself.

Testing a description

A description is plain data: build it from the application's entities and assert on it, or keep it as a JSON file and compare.

$description = (new Omnibridge\Schema\Builder(rules: $rules))->build($classes);
self::assertSame('thread_tags', $description->entity(Thread::class)->relation('tags')->joinTable->name);
self::assertJsonStringEqualsJsonFile(__DIR__.'/schema.json', $description->toJson());

Against the real database, MySqlSchema::read($pdo, ignore: [...])->differences($description) must be [] (The schema). omnibridge/doctrine adds the comparison with Doctrine's own metadata.

The package's own suite

docker compose run --rm test

The service test of compose.yml: the image omnibridge-core:php8.2 (docker/Dockerfile: PHP 8.2-cli, the lowest this package declares, with git, unzip and Composer 2, no extension added), the package mounted at /package, a named volume composer-cache for Composer's cache; it runs composer update then vendor/bin/phpunit. On a checkout whose vendor/ is already installed, the image runs the suite with no network:

docker run --rm --network none -v "$PWD":/package:ro omnibridge-core:php8.2 vendor/bin/phpunit --do-not-cache-result

BareTest is measured on this package's own vendor: run from an application's vendor/*/tests (lesringostars does so), it says so and is skipped, while the registry's cases still run there.

Verified, and not

What the tests prove

Run on 2026-10-27 in the package's image omnibridge-core:php8.2 (PHP 8.2.34, PHPUnit 11.5.57), the checkout's own vendor/, no network: 34 tests, 245 assertions, green. What each test class checks is in Testing. In short:

• The registry: a missing contract is loud and named (with its former names), a service set by hand wins and must implement the contract, the container is asked once and forgotten when it changes, the clock falls back on the machine's, a former name is the same contract, a family's registry is the same state.
• The package stands alone: every class loads with the three PSR interfaces and nothing of a framework, an ORM, Twig or an application (BareTest).
• The schema without doctrine/orm installed: declarations read and read back, joined and single-table hierarchies, relations and their defaults, rules at their three moments, the tables as SchemaTool creates them, the naming, a MySQL schema compared (given as data).

Every example of this manual was run in the same image on 2026-10-27 and its output pasted: the plain PHP registry script (Installation), the schema of two entities and the rule (The schema), the naming examples, the MySQL comparison on data.

Verified elsewhere, as the commits state

• The builder against Doctrine on omnisense/omnibase's harness (202 classes, SchemaDescriptionTest in omnibase compares the description built without Doctrine with Doctrine's on every class the harness maps): three differences found and fixed (commit e74e67c: OrderBy directions, quoted names).
• MySqlSchema on lesringostars' database (MySQL 8.4.11): the display width of integers found and ignored since (commit 4ce7ed1); nothing else differed.
• The registry under both hosts: omnibridge/symfony's and omnibridge/laravel's suites, and lesringostars' runs of vendor/*/tests (the registry's cases pass there, BareTest skipped).

What is not verified

• MySqlSchema::read() is not run by this package's suite (no MySQL in the harness): its queries are checked on lesringostars' database only.
• The builder's behaviour for what omnibase's entities do not use: embedded classes, attribute and association overrides, sequence and custom generators, Table's indexes/uniqueConstraints arguments (The schema lists what is not described).
• A PHP without ext-mbstring: composer refuses to install the package (it requires it, for CamelCaseNaming; Installation).
• A third host (other than Symfony and Laravel): no bridge exists to try the contracts against.