omnibridge/symfony

Installation

Requirements

• PHP 8.2 or later.
• Symfony 6, 7 or 8: the components listed in The framework packages, which Composer installs with the package.
• symfony/asset (suggested): RouterUrls::asset() goes through the application's asset packages; without it, the path is answered as it is.
• symfony/clock (6.2 or later) for a PSR-20 clock in the registry; without it Runtime::clock() is omnibridge's SystemClock.

The optional families: omnisense/omniauth (with omniauth/otp, omniauth/webauthn, omniauth/google for TOTP, passkeys and Google), omnisense/omnimap (with omnimap/google, omnimap/openstreetmap), omnisense/omnidrive, omnibridge/static. Each is wired only when its classes exist.

On an omnisense/omnibase site

composer require omnisense/omnibase omnibridge/symfony

Nothing to register: omnibase's BaseBundle imports this package's config/services.php, runs ContractsPass with omnibase's own contracts added (locator base.contracts), registers the omniauth extension (OmniauthExtension::register()) and seeds Omnibridge\Runtime itself. Do not add OmnibridgeBundle to config/bundles.php there.

In a Symfony application without omnibase

composer require omnibridge/symfony

There is no Flex recipe: add the bundle by hand.

// config/bundles.php
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    // ...
    Omnibridge\Symfony\OmnibridgeBundle::class => ['all' => true],
];

OmnibridgeBundle (an AbstractBundle) has no configuration of its own (no omnibridge: key):

The bundle order does not matter for the contracts: the pass runs at compile time, after every bundle has loaded. For the Twig functions, TwigBundle must be registered (it is required).

A run of the package's test kernel (tests/Fixtures/TestKernel: FrameworkBundle, SecurityBundle, TwigBundle, OmnibridgeBundle), booted with and without SecurityBundle in the package's image (PHP 8.4, Symfony 8.1.9, 2026-10-27):

<?php

require 'vendor/autoload.php';

use Omnibridge\Contract\Access;
use Omnibridge\Contract\Tokens;
use Omnibridge\Runtime;
use Omnibridge\Symfony\DependencyInjection\ContractsPass;
use Omnibridge\Symfony\Tests\Fixtures\TestKernel;

foreach ([true, false] as $security) {
    $kernel = new TestKernel('test', true, $security);
    $kernel->boot();
    $locator = $kernel->getContainer()->get(ContractsPass::SERVICE);
    echo $security ? "With SecurityBundle\n" : "Without SecurityBundle\n";
    echo '  locator: ', implode(', ', array_map(static fn ($id) => substr($id, strrpos($id, '\\') + 1), array_keys($locator->getProvidedServices()))), "\n";
    echo '  path: ', Runtime::urls()->path('page', ['slug' => 'le-fuji']), "\n";
    echo '  environment: ', Runtime::environment()->name(), ', debug ', var_export(Runtime::environment()->isDebug(), true), "\n";
    echo '  Access: ', Runtime::has(Access::class) ? get_class(Runtime::access()) : 'none', "\n";
    echo '  Tokens: ', Runtime::has(Tokens::class) ? get_class(Runtime::tokens()) : 'none', "\n";
    echo '  clock: ', get_class(Runtime::clock()), "\n";
    $kernel->shutdown();
    echo '  after shutdown, container: ', null === Runtime::getContainer() ? 'none' : 'kept', "\n";
}

With SecurityBundle
  locator: Urls, Environment, Translations, Access, Sessions, Tokens, ClockInterface, EventDispatcherInterface
  path: /page/le-fuji
  environment: test, debug true
  Access: Omnibridge\Symfony\Contract\SecurityAccess
  Tokens: Omnibridge\Symfony\Contract\CsrfTokens
  clock: Symfony\Component\Clock\Clock
  after shutdown, container: none
Without SecurityBundle
  locator: Urls, Environment, Translations, ClockInterface, EventDispatcherInterface
  path: /page/le-fuji
  environment: test, debug true
  Access: none
  Tokens: none
  clock: Symfony\Component\Clock\Clock
  after shutdown, container: none

Without SecurityBundle (and with csrf_protection: false), SecurityAccess, SecuritySessions and CsrfTokens are removed at compile time: the registry has no Access, Sessions nor Tokens, and Runtime::access() would throw MissingContractException. Locales, Files and Routes are never in this locator: bind them yourself (Contracts).

In a service

Every contract is an alias of its adapter, so a service autowires it:

use Omnibridge\Contract\Urls;

final class Mailer
{
    public function __construct(private readonly Urls $urls) {}

    public function link(string $slug): string
    {
        return $this->urls->url('article', ['slug' => $slug]);
    }
}

The aliases are private, as Symfony's default: a service gets them by injection, not by $container->get(). Omnibridge\Runtime reaches them through the public locator.

Contracts

The adapters of omnisense/omnibridge's contracts over Symfony's services, defined in config/services.php (OmnibridgeBundle::SERVICES). What each contract means is in the core's manual (Contracts); this page says how Symfony answers.

The services

An application rebinds a contract by aliasing its interface again (services.yaml: Omnibridge\Contract\Urls: '@App\MyUrls'): the locator takes whatever service the name leads to.

The adapters

RouterUrls

path() is the router's generate() with ABSOLUTE_PATH, url() with ABSOLUTE_URL - the same strings Twig's path() and url() print. asset() is Packages::getUrl(), the path unchanged when symfony/asset is not installed. Beyond the contract, generate(string $name, array $parameters = [], int $referenceType = UrlGeneratorInterface::ABSOLUTE_PATH) gives any of the router's reference types (a relative path, a network path): omnibase's Base\Contract\Link::to() asks it. An unknown route is the router's RouteNotFoundException. On an omnibase site the router argument is omnibase's advanced_router.

TranslatorTranslations

trans() is the translator's trans() with the same four arguments - what Twig's |trans answers. exists():

1. the translator's own transExists($id, $domain, $locale) when it has one (omnibase's translator: the locale's catalogue and its fallbacks);
2. otherwise, when the translator is a TranslatorBagInterface (Symfony's is), its catalogue of the locale: getCatalogue($locale)->has($id, $domain ?? 'messages'), which includes the fallback catalogues. An id written @domain.key is read as the key key of the domain domain;
3. otherwise false.

KernelEnvironment

The three kernel parameters, read once at compile time. secret() is kernel.secret (framework.secret), marked #[\SensitiveParameter] in the constructor so a stack trace does not print it.

SecurityAccess

isGranted() is the authorization checker's (the role hierarchy, the application's voters, the access decision strategy); getUser() the token storage's token's user, null without a token.

SecuritySessions

signOut($user) answers false when no token is stored or when its user is not the very object given (!==). Otherwise it empties the token storage and expires the REMEMBERME cookie twice with PHP's setcookie(): once with no path nor domain, once on / and the domain the constructor's closure answers (omnibase gives its router's domain; empty without a closure). The cookies are sent with the response's headers, outside Symfony's Response.

CsrfTokens

csrf($intent) is the token manager's getToken($intent)->getValue() - what Twig's csrf_token() prints; isValid($intent, $token) is isTokenValid(new CsrfToken($intent, $token)), false for a null or empty token without asking.

ContractsPass

Omnibridge\Symfony\DependencyInjection\ContractsPass builds the locator the registry reads. Not final: an application's bundle runs it with its own list.

new ContractsPass(
    contracts: ContractsPass::CONTRACTS,   // the names the locator answers
    services: [],                          // a contract => the service id it is bound to, when not its own name
    former: [],                            // a former name => the contract it is listed as (the same service)
    id: ContractsPass::SERVICE,            // the locator's id, 'omnibridge.contracts'
);

What process() does:

1. Each service tagged omnibridge.adapter whose constructor needs a service that does not exist (a Reference that must be valid, in its arguments or in an inline definition among them) is removed, with every alias that leads to it, through other aliases too. So SecurityAccess goes without SecurityBundle, CsrfTokens without framework.csrf_protection.
2. Each contract of the list whose id (its own name, or the one services gives) exists in the container is put in the locator. Routes, Locales and Files are in the list but bound by nobody here: they appear when the application (or omnibase) binds them. The clock appears when symfony/clock aliases Psr\Clock\ClockInterface (FrameworkBundle does when the component is installed); the dispatcher when Psr\EventDispatcher\EventDispatcherInterface is aliased (FrameworkBundle does).
3. Each former name is added to the locator with its contract's service.
4. The locator is registered public, tagged container.service_locator: nothing is constructed before a contract is asked.

omnibase's BaseBundle runs it with omnibase's list (its Nouns, Media, Pictures, Texts, the parameters, the mailer added) and the id base.contracts.

Binding what is not bound here

Locales, Files and Routes depend on how an application names its languages, its storages and its routes. Without omnibase, bind them yourself; the locator picks them up by their names:

// src/Bridge/RequestLocales.php
namespace App\Bridge;

use Omnibridge\Contract\Locales;
use Symfony\Component\HttpFoundation\RequestStack;

final class RequestLocales implements Locales
{
    public function __construct(private readonly RequestStack $requests) {}

    public function getLocale(): string
    {
        return str_replace('_', '-', $this->requests->getCurrentRequest()?->getLocale() ?? 'fr-FR');
    }

    public function getDefaultLocale(): string { return 'fr-FR'; }

    public function getAvailableLocales(): array { return ['fr-FR', 'en-GB']; }
}

# config/services.yaml
services:
    App\Bridge\RequestLocales: ~
    Omnibridge\Contract\Locales: '@App\Bridge\RequestLocales'

The Twig functions

Omnibridge\Twig\AccessExtension (omnibridge/twig) is registered with the contracts it finds:

TwigBundle registers twig-bridge's extensions first, so these two functions replace twig-bridge's is_granted and csrf_token of the same names, answered by the same Symfony services: a template behaves as it did, and asks the same code it asks under Laravel. path(), url(), asset() and |trans stay twig-bridge's: omnibridge/twig's ContractExtension is not registered under Symfony. The map functions are registered with omnimap (Maps).

FileLinks

Omnibridge\Symfony\FileLinks makes the links of the error pages and the profiler open the file on the developer's machine when the site runs in a container: APP_PATH (the project's path on the host, which a site's Makefile writes in .env.local) against kernel.project_dir (its path in the container), with Symfony's own means - FileLinkFormatter reads a mapping after the format, vscode://file/%f:%l&/srv/app/>/Users/me/site/.

FrameworkBundle's framework.ide defaults, in debug, to %env(default::SYMFONY_IDE)%: export() called before the kernel boots maps every link Symfony makes, including ErrorHandler's renderer for an error before the container is built. omnibase's BaseBundle calls FileLinks::export() in its constructor. OmnibridgeBundle calls neither method and registers no decoration: without omnibase, call export() early (in public/index.php and bin/console, after the autoloader), or decorate the formatter:

# config/services.yaml (dev)
services:
    app.file_link_formatter:
        class: Symfony\Component\ErrorHandler\ErrorRenderer\FileLinkFormatter
        decorates: debug.file_link_formatter
        factory: ['Omnibridge\Symfony\FileLinks', 'formatter']
        arguments: ['@.inner', '%env(default::SYMFONY_IDE)%', '%kernel.project_dir%', '%env(default::APP_PATH)%', '@request_stack']

Run in the package's image (a dev kernel with FrameworkBundle, TwigBundle and OmnibridgeBundle, kernel.project_dir /srv/app, APP_PATH=/Users/me/site, 2026-10-27), the decorated formatter and format():

$kernel->getContainer()->get('app.file_link_formatter')->format('/srv/app/src/Kernel.php', 12);
FileLinks::format(null, '/srv/app', '/Users/me/site');
FileLinks::format('phpstorm', '/srv/app', '/Users/me/site');
FileLinks::format('vscode://file/%f[%b:/Users/me/other]:%l', '/srv/app', null);

vscode://file//Users/me/site/src/Kernel.php:12
vscode://file/%f:%l&/srv/app/>/Users/me/site/
phpstorm://open?file=%f&line=%l&/srv/app/>/Users/me/site/
vscode://file/%f:%l&/srv/app/>/Users/me/other/

Signing in (omniauth)

Where omnisense/omniauth is installed (it is only suggested), OmnibridgeBundle registers omniauth's extension (Auth\DependencyInjection\OmniauthExtension; an omnibase site's BaseBundle calls OmniauthExtension::register() too). With no config/packages/omniauth.yaml, nothing is wired. With one, every way of signing in goes through omniauth's conductor and one Symfony authenticator.

This page is the reference of the Symfony side: the configuration tree, the services, the routes, what the authenticator does with each request. What each method does (a password, a sign-in link, an e-mailed code, backup codes, TOTP, passkeys, identity providers), its stores and events are omniauth's own manual: omniauth's Symfony page and its method pages.

Setting it up

# config/packages/security.yaml
security:
    firewalls:
        main:
            custom_authenticators: [Omnibridge\Symfony\Auth\OmniauthAuthenticator]
            entry_point: Omnibridge\Symfony\Auth\OmniauthAuthenticator   # optional: start() sends to login_route
            remember_me: { secret: '%kernel.secret%' }                   # Security's own, used when omniauth says "remember"
            logout: { path: security_logout }
    access_control:
        - { path: ^/login/2fa, roles: IS_AUTHENTICATED_2FA_IN_PROGRESS }

# config/routes/omniauth.yaml
omniauth: { resource: ., type: omniauth }

# config/packages/omniauth.yaml - each key turns its method on
omniauth:
    password: { routes: [security_login] }
    link: { route: security_loginWithToken }      # 15 minutes, once, hashed
    email_code: ~
    backup_codes: ~
    trusted_device: ~                              # scheb/2fa's cookie and tokens
    totp: { secret_key: '%env(OMNIAUTH_TOTP_KEY)%' }   # omniauth/otp; the secrets sealed at rest (sodium)
    passkey: { rp_id: '%env(RELYING_PARTY_ID)%' }  # omniauth/webauthn
    oauth: { providers: { google: { client_id: '...', client_secret: '...' } } }   # omniauth/google (the mechanics: omniauth's Omniauth\OAuth\)

totp.secret_key (base64 of 32 bytes, from the vault or the environment, never in the repository; the same on every host of one database - the Laravel twin's config/omniauth.php reads the same variable) seals the TOTP secrets at rest: omniauth/otp's SealedTotpSecrets over a SodiumSecretBox decorates the totp_secrets store, so the method and any page that reads or writes the store (omnibase's enrolment and its QR code) go through it. Unset, the secrets are kept as the store has them. A secret kept in clear before is read as it is until the application rewrites its rows (omnibase sites: a migration).

A provider's return address is, unless it sets one, the path of its check route: omniauth puts it on the host of each trip's request (the providers are built once per worker; an absolute address made here would stay on the first request's host). Each provider package's factory (Omniauth\OAuth\Provider\ProviderFactory, tag omniauth.oauth_provider_factory) makes its own kind; omniauth/google's is registered when it is installed.

The stores (Omniauth\Contract\Accounts... the passkeys, the sender) are the application's, by their contracts' names or those omniauth.yaml's stores names; omniauth's events go to Symfony's dispatcher (listen to Omniauth\Event\SignedIn...). The accounts must be Symfony users (UserInterface): the authenticator refuses any other with a LogicException.

The configuration tree

Dumped with Symfony's reference dumper (bin/console config:dump-reference omniauth) on a kernel of FrameworkBundle, SecurityBundle, TwigBundle and OmnibridgeBundle, in the package's image (PHP 8.4, Symfony 8.1.9, 2026-10-27):

# Default configuration for extension with alias: "omniauth"
omniauth:

    # Keys the e-mailed codes' hashes and the trusted devices' tokens (scheb/2fa signed them with kernel.secret)
    secret:               '%kernel.secret%'

    # The sign-in page: where a refused or abandoned attempt goes back to
    login_route:          security_login
    stores:
        accounts:             Omniauth\Contract\Accounts
        passwords:            Omniauth\Contract\Passwords
        link_tokens:          Omniauth\Contract\LinkTokens
        email_codes:          Omniauth\Contract\EmailCodes
        backup_codes:         Omniauth\Contract\BackupCodes
        trusted_version:      Omniauth\Contract\TrustedVersion
        totp_secrets:         Omniauth\Contract\TotpSecrets
        identities:           Omniauth\Contract\Identities
        passkeys:             Omniauth\WebAuthn\Contract\Passkeys
        sender:               Omniauth\Contract\Sender
    password:
        enabled:              true

        # The routes a sign-in form posts to
        routes:

            # Default:
            - security_login

        # The form's name, its fields read under it; null: at the top of the request
        form:                 null
        identifier:           _username
        password:             _password
        remember:             _remember_me
        target_path_parameter: _target_path
        default_target_path:  /

        # The class whose hasher security.yaml sets (password_hashers): the same hasher checks the passwords
        user_class:           null
        csrf:
            enabled:              true
            field:                _csrf_token
            intent:               authenticate
    link:
        enabled:              false
        lifetime:             900

        # The route of the link's page, which signs in when it carries a token
        route:                null
        parameter:            token
    email_code:
        enabled:              false
        digits:               6
        lifetime:             600
    backup_codes:
        enabled:              false
        count:                8
    trusted_device:
        enabled:              false
        lifetime:             2592000
        cookie:               trusted_device

        # The tokens' "fwl" claim; null: the firewall of the request
        firewall:             null
    totp:
        enabled:              false
        leeway:               0
        period:               30
        digits:               6
        issuer:               null
        server_name:          null

        # The key the secrets are sealed with at rest (omniauth/otp's SodiumSecretBox): base64 of 32 bytes, from the vault or the environment - '%env(OMNIAUTH_TOTP_KEY)%' -, never written in the repository; the same on every host of the database. Unset: the secrets are kept as the store has them
        secret_key:           null
    passkey:
        enabled:              false
        rp_id:                null
        rp_name:              null
        origins:              []
        timeout:              null

        # Security's remember-me after a passkey (the JSON posted may say otherwise: "remember")
        remember:             true
        options_path:         /login/passkey/options
        options_route:        passkey_login_options
        path:                 /login/passkey
        route:                passkey_login
    oauth:
        enabled:              false

        # Link an account by an address its provider vouches for: true, false, or a service (omniauth's EmailLinking); null: never one with a second factor
        link_by_email:        null

        # Where an identity no account is linked to goes (its PendingIdentity in the session); null: the sign-in page
        sign_up_route:        null
        providers:

            # Prototype
            name:
                client_id:            ''
                client_secret:        ''

                # An absolute address, or a path each trip's host completes; null: the path of check_route
                redirect_uri:         null
                scopes:               []
                hosted_domain:        null
                type:                 null

                # A service that is the provider (omniauth's Provider), in place of the settings above
                service:              null
                start_path:           null
                start_route:          null
                check_path:           null
                check_route:          null
    second_factor:
        after:

            # Defaults:
            - password
            - link
            - oauth
        form_path:            /login/2fa
        form_route:           2fa_login
        check_path:           /login/2fa/check
        check_route:          2fa_login_check
        template:             security/login_2fa.html.twig
        code:                 _auth_code
        trusted:              _trusted
        csrf:
            enabled:              true
            field:                _csrf_token
            intent:               two_factor
    throttle:
        enabled:              true

        # A PSR-6 pool (Symfony's cache pools are): the tries counted, and the TOTP steps used
        pool:                 cache.app

        # Tries per window in seconds, by scope (omniauth's CacheThrottle::LIMITS by default): { password: [5, 60] }
        limits:

            # Prototype
            scope:                []

    # The message of a failure, or of "failure:reason" ("%reason%" replaced), as the page translates it
    messages:

        # Prototype
        failure:              ~

A key written, even empty (email_code: ~), turns its method on (canBeEnabled()); password and the two csrf blocks and throttle are on unless enabled: false (canBeDisabled()).

Top level

Methods

A method whose package is missing stops the compilation: omniauth.yaml turns "totp" on, which needs omniauth/otp: composer require omniauth/otp. (the same for passkey, oauth).

oauth.providers.<name>

Other keys are kept (ignoreExtraKeys(false)) and handed to the factory.

second_factor

throttle

The services

The routes

omniauth: { resource: ., type: omniauth } loads (AuthRouteLoader):

The names and addresses are those scheb/2fa, web-auth/webauthn-symfony-bundle and hwi/oauth-bundle had, so the pages and scripts that name them do not change. The password form's route and the link's route are the application's.

The authenticator

OmniauthAuthenticator (AbstractAuthenticator, AuthenticationEntryPointInterface, not final) knows a sign-in request by its route (the router has run before the firewall):

A method not turned on is never supported. Then Omniauth::verify(), and:

start() (the entry point) redirects to login_route.

The messages (OmniauthAuthenticator::MESSAGES, overridden by messages), Symfony's security catalogue's keys so a page translates them as it did:

A key failure:reason (refused:locked) wins over failure; %reason% in a message is replaced by the reason. An unknown failure falls back on bad-credentials's message.

The session keys: omnibridge.auth.factor (OmniauthAuthenticator::CHOSEN, the second factor chosen), omnibridge.auth.second_factor_error (SECOND_FACTOR_ERROR), omnibridge.auth.pending_identity (PENDING_IDENTITY), and Security's _security.last_username, _security.last_error.

Between two factors

• PendingToken: a TokenInterface (not an AbstractToken, as scheb/2fa's TwoFactorToken), no role, the offered factors (offered()), serialised in the session like any token.
• PendingVoter: grants IS_AUTHENTICATED_2FA_IN_PROGRESS to a PendingToken and to nobody else (it abstains otherwise), so an access_control line written for scheb/2fa still opens the page.
• PendingTrustResolver: isFullFledged() is false for a PendingToken, so IS_AUTHENTICATED_FULLY is refused to it.
• SecondFactorGate: on kernel.request (priority 7, after the firewall) and kernel.exception (priority 2, before the firewall's exception listener, for an AccessDeniedException anywhere in the chain), a visitor holding a PendingToken is redirected to second_factor.form_route - except on the second factor's own routes, a page access_control opens to PUBLIC_ACCESS or whose attributes the token is granted, and the firewall's sign-out path.

The second factor's page

CeremonyController::secondFactor() renders second_factor.template with the variables scheb/2fa's form controller gave, so a template written for scheb/2fa renders unchanged:

?preferProvider=email (or any offered factor) chooses the factor. The e-mailed code is sent when its page is first shown, and again once it expired. Without a PendingToken or an attempt, the page abandons the attempt and redirects to login_route. The answer is Cache-Control: no-store. Without TwigBundle it throws LogicException ("The second factor's page is a Twig template: install symfony/twig-bundle.").

passkeyOptions() answers the passkey's request options as web-auth/webauthn-symfony-bundle did ({"status": "ok", "errorMessage": "", ...options}, or failed and 400); oauthStart() redirects to the provider's authorization address (404 when no provider is served or the name is unknown, back to login_route on another failure); check() sends a stray GET of a check address back to its page.

Maps (omnimap)

Where omnisense/omnimap is installed (suggested), OmnibridgeBundle registers omnimap's extension (Map\DependencyInjection\OmnimapExtension, alias omnimap), and config/packages/omnimap.yaml wires it: its providers (omnimap/google, omnimap/openstreetmap, registered when installed) over the application's http_client, a PSR-16 view of a cache pool and a PSR-18 client for geocoder-php; the map cache over a storage of the application's (an omnidrive drive, or any Omnimap\Snapshot\Storage); omnibridge/twig's MapExtension (omnimap(view), omnimap_export(), omnimap_suppress()); the cache's routes and their controller. With no omnimap.yaml, nothing is wired.

What a map, a view, a snapshot and a provider are is omnimap's own manual (omnimap's Symfony page, its cache); this page is the reference of the Symfony side.

Setting it up

# config/routes/omnimap.yaml
omnimap: { resource: ., type: omnimap }

# config/packages/omnimap.yaml
omnimap:
    provider: openstreetmap            # the page's map: a key of providers
    secret: '%env(MAP_SECRET)%'        # signs the pictures' names
    providers:
        openstreetmap: { user_agent: 'MySite/1.0 (+https://example.org)' }
        google: { api_key: '%env(GOOGLE_MAPS_CLIENT_KEY)%', secret: '%env(GOOGLE_MAPS_SECRET)%' }
    cache:
        drive: local.uploads           # an omnidrive drive (Omnidrive\Drives); or storage: an Omnimap\Snapshot\Storage service
        public_directory: '%kernel.project_dir%/public'   # tiles served are written there too
    routes:
        tile: { path: '/omnimap/{signature}/{id}.webp', name: omnimap_tile }

cache.drive needs omnisense/omnidrive (its Omnidrive\Drives is bound by this package, Storages).

The configuration tree

Dumped with bin/console config:dump-reference omnimap on the same kernel as omniauth's (PHP 8.4, Symfony 8.1.9, 2026-10-27):

# Default configuration for extension with alias: "omnimap"
omnimap:

    # The provider of the page's map: a key of "providers".
    provider:             ~ # Required

    # The provider that geocodes (Omnimap\GeocoderInterface): a key of "providers"; the page's provider by default.
    geocoder:             null

    # Signs the pictures' names (URL-safe base64; Google's URL signing secret fits).
    secret:               ''
    providers:

        # Prototype
        name:                 ~

    # A visitor never gets the live map: the picture kept, or an empty frame.
    cache_only:           true

    # Who may capture and delete pictures, and sees the live map while there is none.
    control:              ROLE_ADMIN
    cache:

        # The omnidrive drive the cache is kept on (Omnidrive\Drives: a storage's name, "local.uploads"); or storage.
        drive:                null

        # A service implementing Omnimap\Snapshot\Storage, when the cache is on no omnidrive drive.
        storage:              null
        directory:            omnimap
        pattern:              '{signature}/image-{id}'
        format:               png # One of "png"; "jpeg"; "jpg"; "webp"
        tilesize:             512

        # Whether the server makes a missing picture itself: auto (when the provider makes images), true, false.
        make:                 auto
        size:                 1512x938
        scale:                1

        # The PSR-6 pool keeping fetched tiles and geocoders' answers.
        pool:                 cache.app

        # The HTTP lifetime of a tile served by the route.
        max_age:              86400

        # Where a tile served is also written (the web server then serves it without PHP): the public folder.
        public_directory:     null

        # The largest side of a tile served, in pixels (none: as kept).
        public_size:          null
    html:
        class:                omnimap-snapshot
        suffix:               _snapshot
        missing:              ''
    routes:
        tile:
            path:                 '/omnimap/{signature}/{id}.webp'
            name:                 omnimap_tile
        metadata:
            path:                 '/omnimap/{signature}'
            name:                 omnimap_metadata
        export:
            path:                 '/omnimap/{signature}/export'
            name:                 omnimap_export
        suppress:
            path:                 '/omnimap/{signature}/suppress'
            name:                 omnimap_suppress

The services

A provider of another package is wired by its factory, tagged as the registry collects them:

# config/services.yaml - another provider's factory
services:
    App\Map\AcmeFactory:
        arguments: ['@http_client']
        tags: [omnimap.provider_factory]

The Twig functions

Omnibridge\Twig\MapExtension (omnibridge/twig), given the MapPrinter, the Urls, Access and Tokens contracts, control and the routes' names:

{{ omnimap(view) }}
{{ omnimap_export(view, {class: 'item', text: 'Capture'}) }}
{{ omnimap_suppress(view, {text: 'Delete'}) }}

The routes and the controller

omnimap: { resource: ., type: omnimap } loads (MapRouteLoader, the tile first because its path may lie under the metadata's), signature matching [A-Za-z0-9_-]{1,128}:

SnapshotController:

• tile: the tile's bytes from the store (404 "No such map tile." when none or the signature is invalid). When the route's path ends in .webp and the store keeps another format, converted to WebP at quality 75 and fitted within public_size - with GD when it was built with WebP, else Imagick, else served as kept. Written also under public_directory at the route's path. Public, max-age of max_age, must-revalidate, an ETag (MD5 of the bytes), 304 when the request's matches.
• metadata: the picture's metadata as JSON, {"status": "BAD"} when none.
• export: for whoever Access grants control (403 "Only whoever may change the map." otherwise, and when no Access is bound), with a valid _token of intent omnimap-export when Tokens is bound (403 "Invalid token."); image (a data: URL; 400 "No picture was sent." when empty), tilesize (else cache.tilesize); the picture saved, the public tiles of that signature deleted, its metadata answered. An invalid picture is a 400 with omnimap's message.
• suppress: the same guard with intent omnimap-suppress; the picture deleted with its public tiles; {"status": "OK"}.

The public tiles are deleted only inside public_directory and in a folder whose path holds the signature.

Storages and static export

Storages: omnidrive

Where omnisense/omnidrive is installed (suggested), Omnidrive\Drives is the application's storages as omnidrive's drives: an Omnidrive\Flysystem\OperatorDrives over the services tagged flysystem.storage, by their storage attribute - the storages of league/flysystem-bundle's configuration (or omnibase's local ones without the bundle). Nothing is configured a second time: config/packages/flysystem.yaml names them, the code reads and writes them through Drive.

# config/packages/flysystem.yaml (league/flysystem-bundle)
flysystem:
    storages:
        local.uploads:
            adapter: local
            options: { directory: '%kernel.project_dir%/public/uploads' }

use Omnidrive\Drives;

final class Avatars
{
    public function __construct(private readonly Drives $drives) {}

    public function store(int $id, string $bytes): void
    {
        $this->drives->get('local.uploads')->write('avatars/'.$id.'.png', $bytes);
    }
}

The drive is a FlysystemDrive over the very operator: a file written through the drive is in the host's storage (DrivesTest). What a drive does (addresses, visibility, errors) is omnidrive's manual. The map cache's cache.drive names one of these drives (Maps).

Static export: omnibridge/static

Where omnibridge/static is installed, config/services.php registers the console command omnibridge:static:build (Omnibridge\Symfony\Static\BuildCommand, tag console.command): omnibridge/static's own command line (Console\Cli), handed what this host offers the site's file.

bin/console omnibridge:static:build static.php --out=var/static [--verify] [--strict]

What the command hands Cli::build() as the host's offer:

The exit code is Cli::build()'s (its report, its checks and its codes are omnibridge/static's manual); an InvalidArgumentException it throws (a site file that is not one) is printed as an error and the command exits with Command::INVALID (2).

Run on lesringostars (2026-10-24, the working copy loaded by hand, neither package installed there yet): the same report as the plain command line, but for the dev 404 page (Symfony's exception page, its trace).

Errors

At compile time

At run time

Testing

Testing an application

Under a KernelTestCase or a WebTestCase, booting the kernel fills the registry (OmnibridgeBundle::boot() or omnibase's BaseBundle), and a new kernel replaces the previous one's services: nothing to reset between tests. A test that sets a contract by hand (Runtime::set()) takes it back after (Runtime::set($contract, null) or Runtime::reset()), or the next tests see it.

The sign-in is tested as a visitor does it, with Symfony's browser: post the form, follow the redirection to the second factor's page, post the code. The package's AuthTest does exactly that, with an in-memory accounts store, omniauth's RecordingSender (the e-mails kept) and FakeProvider (an identity provider simulated): copy its kernel (tests/Fixtures/AuthKernel.php) for an application's own.

The package's suite

docker compose run --rm test   # composer update, then PHPUnit
docker compose run --rm bare   # without the suggested families

compose.yml's two services use the image omnibridge-symfony:php8.4 (docker/Dockerfile: PHP 8.4-cli, Composer 2, intl, zip, and GD with JPEG and WebP for omnimap's pictures), the package mounted at /package (bare: read-only at /source), a named volume composer-cache. bare (docker/bare.sh) copies the package, removes omnisense/omniauth and its methods, omnisense/omnimap and its providers, omnisense/omnidrive and league/flysystem-memory, checks that none of their classes loads, and runs the group without-omniauth. With the checkout's vendor/ installed, the suite runs without network:

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

The kernels (tests/Fixtures): TestKernel (FrameworkBundle, SecurityBundle with an in-memory user, TwigBundle, OmnibridgeBundle; without SecurityBundle on demand; a Flysystem memory storage tagged memory.uploads), AuthKernel (one firewall signing in through omniauth alone, every method on, the accounts in memory, TOTP secrets sealed with a test key), MapKernel (omnimap on OpenStreetMap, its tiles answered by the test, the cache on a local storage).

Verified, and not

What the tests prove

Run on 2026-10-27 in the package's image omnibridge-symfony:php8.4 (PHP 8.4, Symfony 8.1.9), the checkout's own vendor/, no network: 38 tests, 246 assertions, green. What each class checks is in Testing. The bare run (without the suggested families) needs Composer's network and was not run that day; the commit f643d67 states it green.

The examples of this manual run in the same image on 2026-10-27, their output pasted: the test kernel booted with and without SecurityBundle (Installation), the FileLinks decoration and formats (Contracts), and the two configuration trees, dumped with config:dump-reference (omniauth, omnimap). For the dump, symfony/yaml (not installed in this package's vendor) was loaded from omnibridge/laravel's vendor, the same version (8.1.9).

Verified elsewhere, as the commits and the README state

• The contracts and omniauth's sign-in on lesringostars (Symfony), with its parity suite against the Laravel twin.
• The map tiles on lesringostars: WebP converted with Imagick where GD has no WebP (commit 6cdce16), at quality 75 (3fa1968).
• omnibridge:static:build on lesringostars (2026-10-24, the working copy loaded by hand): the same report as the plain command line but for the dev 404 page (commit 67129db).
• omniauth's provider factories through a service locator, after a compiled container (debug off) dropped an inlined tagged iterator (lesringostars' prod_demo_test kernel, Symfony 8.1.5).

What is not verified

• Symfony 6 and 7: composer.json admits them, the suite runs on Symfony 8.1 only.
• A real identity provider: Google is simulated (FakeProvider) and configured by GoogleFactory in the tests; no sign-in against Google's servers in this package.
• A real passkey authenticator: the tests use omniauth/webauthn's in-memory passkeys.
• omnimap providers other than OpenStreetMap through this wiring: Google is registered, not exercised; MapLibre is registered and resolved as a renderer (MapTest::testTheServices), its page not drawn.
• FileLinks::formatter() as a decoration in an application: tested by FileLinksTest and run here, registered by no configuration of this package or omnibase.