omnisense/omnibase Base documentation

Getting started

Requirements

Installation

composer install
php bin/console doctrine:migrations:migrate
npm install && npm run dev

Conventions

The Base\ namespace mirrors App\: a class in Base\Entity\User is aliased so the application can override it at App\Entity\User without the bundle knowing. This is deliberate and load-bearing — do not rename it.

Scaffolding a site

A new omnibase site starts as a copy of Apfelschule (~/Sites/apfelschule), the reference application: Symfony 8, PHP 8.4, Docker, omniscient/omnibase 3.x with omnibase/admin, omnibase/marketplace and the omnibase/* bundles of its trade. This page is the exact list: what is copied and then adapted, and what is no longer copied because a package provides it.

What a new site copies

The project's frame (copied as is, then names and ports changed)

Never copied: .env.local and .htpasswd. Both are git-ignored and belong to one deployment: .env.local holds the other site's secrets (its Stripe and mail keys, its database password) and would point the new site at them; .htpasswd holds the other site's beta credentials. A copy made with cp -R or rsync takes them along with the rest: copy from git ls-files (or git archive HEAD | tar -x -C ../newsite), or exclude the two by name. The new site writes its own - .env.local by hand, .htpasswd with make htpasswd (the proxy mounts ./.htpasswd: without the file Docker creates a directory of that name, and the protected hosts cannot check a password).

symfony.lock comes with composer.json

symfony.lock is Flex's record of the recipes already applied, one entry per package. Without it Flex takes every package of the first composer install for a new one and plays every recipe again: it rewrites config/bundles.php, drops its default config/packages/*.yaml, config/routes/*.yaml, .env blocks, src/Kernel.php, public/index.php and bin/console over the files just copied from Apfelschule - the site then boots on Symfony's defaults instead of omnibase's configuration (or does not boot: two Doctrine configurations, a second security firewall).

So the copy takes symfony.lock (it is tracked: git ls-files and git archive include it). After the first install, git status must show no change under config/; a package added later is a composer require, whose recipe adds its entry to the lock - commit it with the rest.

A copy made without it is repaired before the first install: take Apfelschule's symfony.lock, remove the entries of the packages the new site does not require (or leave them: an entry without its package is ignored). If the recipes already ran, git checkout -- config/ .env src/Kernel.php public/index.php bin/console on a copy that was committed first, else copy those paths again.

Fonts: @fontsource 5.3 and its exports

The sites install their fonts from @fontsource/<font> (^5.2 in package.json) and import the files they use in assets/styles/app-async.scss:

@import "@fontsource/andika/latin-400.css";      // <subset>-<weight>[-italic].css
@import "@fontsource/andika/latin-700.css";

From 5.3.0 a fontsource package declares an exports map, and the bundler (webpack's resolver, which sass-loader and css-loader use) refuses every path the map does not list. What it lists, and so what still resolves by package name: the package itself (@fontsource/andika: index.css), the stylesheets at its root (/latin-400.css, /400.css, /latin.css...), the font files (/files/andika-latin-400-normal.woff2), and /scss (the metadata, from Sass only).

What no longer resolves by package name - "Package path ./scss/mixins is not exported from package …/@fontsource/andika" - is anything else inside the package, the Sass mixins first:

@use "@fontsource/andika/scss/mixins" as andika;                          // 5.3: refused
@use "../../node_modules/@fontsource/andika/scss/mixins.scss" as andika;  // by relative path: resolves

A relative path through node_modules is not a package request: the exports map does not apply to it, and it resolves whatever the version. Use it for the paths the map leaves out; keep the package name for the stylesheets above, which it lists. (Checked on 5.3.0 with webpack's enhanced-resolve 5.26, sass-loader 16 and css-loader 7 - the versions the sites build with.)

Docker networks: a subnet per site

Each site has two networks (extranet, intranet), and Docker gives each a subnet of its default address pools. With many sites up at once the pools run out and up fails on "could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network" (or "all predefined address pools have been fully subnetted"). A site therefore fixes its two subnets in docker-compose.override.yml, numbered after its ports so that no two sites share one:

# docker-compose.override.yml
networks:
  extranet:
    ipam:
      config:
        - subnet: ${NETWORK_EXTRANET_SUBNET:-10.110.126.0/24}   # HTTP port 8126: 126 and 127
  intranet:
    ipam:
      config:
        - subnet: ${NETWORK_INTRANET_SUBNET:-10.110.127.0/24}

NETWORK_EXTRANET_SUBNET and NETWORK_INTRANET_SUBNET (.env.local) move them on a host where those ranges are taken. A subnet changes only when its network is recreated: make down, then make up. See also Stopping a site.

Configuration (copied, then trimmed to the site's bundles)

config/bundles.php, config/services.yaml (its app.site.* parameters), config/routes.yaml (one import per bundle's client controllers), config/routes_paths.yaml (the localized paths), config/routes/* (base_admin.yaml is what routes the back office, its system pages included), and config/packages/*: base.yaml, admin.yaml, doctrine.yaml, security.yaml, framework.yaml, cache.yaml (its cache.redis pool), marketplace.yaml and omnitrade.yaml for a shop, consent.yaml, one file per bundle, and the rest as they are.

The site's own code (copied as a model, rewritten)

A shop's User is its merchant

omnibase/marketplace's products, stores and orders are related to "whoever sells", Base\Marketplace\Model\MerchantInterface, which Doctrine binds to a class of the application. A site that installs the marketplace declares both; without them Doctrine cannot map those entities (the target entity Base\Marketplace\Model\MerchantInterface is not found) and no migration can be generated:

// src/Entity/User.php
use Base\Marketplace\Model\MerchantInterface;

class User extends \Base\Entity\User implements MerchantInterface
{
    #[ORM\Column(length: 255, nullable: true)]
    protected ?string $companyName = null;

    public function getCompanyName(): ?string { return $this->companyName; }   // the interface's one method
}

# config/packages/doctrine.yaml
doctrine:
    orm:
        resolve_target_entities:
            Base\Marketplace\Model\MerchantInterface: App\Entity\User

A shop with a merchant class of its own (App\Entity\User\Merchant, a subclass of User) names that class instead. A site without the marketplace needs neither.

Glitch Art's signature: mirror: true on the left

The footer's credit is @Base/partials/_credits.html.twig, black or white only (Front end). Its detail line opens towards the inside of the page: by default on the left of the signature, for a signature set on the right of its footer. A site that sets the signature on the left passes mirror: true, or the detail opens outwards, over the page's margin:

{% include '@Base/partials/_credits.html.twig' with {mirror: true} %}                  {# signature on the left #}
{% include '@Base/partials/_credits.html.twig' with {color: 'white', outline: true} %}  {# on the right, on a photo #}

Secrets {#secrets}

bin/console secrets:set, secrets:generate-keys and secrets:remove write under config/secrets/<env>/. The web container cannot: it mounts the project read-only (.:/srv/app:ro; only var/, vendor/ and public/ are writable), and the command fails on "Unable to create the secrets directory (/srv/app/config/secrets/dev)" - a make shortcut that runs in <app>-web-1 fails the same way.

Run them where the project is writable: the one-shot composer service of docker-compose.setup.yml, which mounts .:/srv/app:rw and reads the same .env and .env.local:

# the key pair of an environment (once per environment; see Sealed fields)
docker compose -f docker-compose.yml -f docker-compose.setup.yml run --rm --entrypoint "" composer \
    php bin/console secrets:generate-keys

# a secret, read from standard input so that it stays out of the shell's history
printf %s "$STRIPE_SECRET" | docker compose -f docker-compose.yml -f docker-compose.setup.yml run --rm -T --entrypoint "" composer \
    php bin/console secrets:set STRIPE_API_KEY -

# production's: with the public key alone, on any machine
docker compose -f docker-compose.yml -f docker-compose.setup.yml run --rm --entrypoint "" composer \
    php bin/console secrets:set STRIPE_API_KEY --env=prod

(--entrypoint "" skips the service's own entrypoint, which runs a whole composer install. On a machine with PHP, php bin/console secrets:set … from the project's directory does the same.)

Then: commit config/secrets/<env>/ except prod.decrypt.private.php (git-ignored: check .gitignore has a line for config/secrets/prod*/prod*.decrypt.private.php), and clear the cache of the running site (docker exec <app>-web-1 php bin/console cache:clear): the secrets are read when the container is compiled. Reading them works in the web container: make secrets (secrets:list --reveal).

The same key pair seals the fields marked #[Vault] - the API keys typed in the back office - and without it they are refused, not stored in clear: see Sealed fields.

The demonstration: what a site adds {#demo}

APP_ENV=demo runs the site as a demonstration (The demo environment): production's behaviour, a database of its own (<database>_demo), the demonstration account named in the banner of every page, one button for each role on the sign-in page, a back office that opens with a secret, a reset every night. Everything is in omniscient/omnibase; a site adds these lines.

.env.demo (committed: defaults only, as .env.prod; no secret):

HTTPS=on
HTTP_REDUCTION=true
HTTP_DOMAIN='["demo.example.org", "localhost"]'
HTTP_SUBDOMAIN='["", "www"]'
HTTP_MACHINE='[""]'
HTTP_BASEDIR=/
HTTP_PORT='[80,8126]'
HTTPS_PORT='[443,8643]'
USE_SYS_TMPDIR=false
# DEMO_SUPERADMIN_PASSWORD and DEMO_ADMIN_PASSWORD are NOT here: the passwords
# of the super-administrator and of the back office's accounts (ROLE_ADMIN) in
# the demonstration are secrets of the server (.env.demo.local, git-ignored,
# or real variables). Unset, those accounts cannot sign in.

A real variable beats every .env* file, and the containers get .env as real variables: .env.demo cannot change what .env defines. What differs in demo is said under when@demo.

config/bundles.php - the fixtures are loaded in demo:

Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle::class => ['dev' => true, 'test' => true, 'demo' => true],

(doctrine/doctrine-fixtures-bundle is in require-dev: deployments/docker/composer/entrypoint.sh installs the dev packages for demo too - a demo*) composer install --no-interaction ;; beside test*).)

config/services.yaml - the fixtures are services where the bundle is:

when@dev: &fixtures
    services:
        App\DataFixtures\:
            resource: '../src/DataFixtures/'
            autowire: true
            autoconfigure: true

when@demo: *fixtures

config/packages/doctrine.yaml - production's pools, a database of its own:

when@prod: &prod
    framework:
        cache:
            pools:
                doctrine.result_cache_pool: { adapter: cache.app }
                doctrine.system_cache_pool: { adapter: cache.system }

when@demo:
    <<: *prod
    doctrine:
        dbal:
            connections:
                default:
                    dbname_suffix: '_demo'

config/packages/base.yaml - which database production's is (the demonstration refuses to start on it, and without this line):

when@demo:
    base:
        demo:
            production_database: 'mysql://%env(DOCTRINE_DATABASE_HOST)%:%env(DOCTRINE_DATABASE_PORT)%/%env(DOCTRINE_DATABASE)%'
            reset:
                purge: []      # storages of the site's own that demo:reset empties

Every other when@prod (monolog.yaml, ...): when@prod: &prod, then when@demo: *prod at the end of the file. config/packages/mailer.yaml: when@demo: { framework: { mailer: { dsn: 'null://null' } } } (omnibase refuses every message in demo whatever the DSN; this keeps anything else from trying).

deployments/docker/cron/crontab - the same file in every environment, so the line checks:

30  3  * * *  [ "$APP_ENV" = demo ] && php /srv/app/bin/console demo:reset >> /srv/app/var/log/cron.demo-reset.log 2>&1

config/packages/flysystem.yaml - the demonstration's files in directories of its own, which demo:reset empties: nothing of another environment is ever there (a development machine runs both from one checkout):

when@demo:
    flysystem:
        storages:
            local.uploads: { local: { directory: '%kernel.project_dir%/var/storage/demo/uploads' } }
            local.wysiwyg: { local: { directory: '%kernel.project_dir%/var/storage/demo/wysiwyg' } }
            # and every other storage visitors write to (omnibase/office's local.share...)

# config/packages/base.yaml, under when@demo's base.demo
            reset:
                purge: ['%kernel.project_dir%/var/storage/demo']
                orphans: false     # everything is in the directory above: no search among the uploads

Makefile:

## Configure environment for the demonstration (production's behaviour, the database <name>_demo)
env-demo:
	@APP_ENV=demo APP_DEBUG=0 $(MAKE) env

## Create the demonstration's database (<name>_demo), its schema and its fixtures
database-demo:
	@$(DOCKER_DATABASE) mysql -h localhost -u root -p$(MYSQL_ROOT_PASSWORD) -e "CREATE DATABASE IF NOT EXISTS $(MYSQL_DATABASE)_demo; GRANT ALL ON $(MYSQL_DATABASE)_demo.* TO '$(MYSQL_USER)'@'%'; FLUSH PRIVILEGES;"
	@$(DOCKER_WEB) php bin/console doctrine:migrations:migrate --env=demo --no-debug --no-interaction
	@$(DOCKER_WEB) php bin/console doctrine:fixtures:load --env=demo --no-debug --no-interaction

The keys - what the fixtures need to seal (omnibase/office's SHARE_MASTER_KEY, omnibase/mailbox's MAILBOX_KEY) is given in .env.demo as demonstration keys, known to everyone and used nowhere else, as .env.test does (base64 of demo-key-demo-key-demo-key-00001): what they seal is the fixtures' fictional data, emptied every night. The one real secret of a demonstration, DEMO_SUPERADMIN_PASSWORD, is the server's: .env.demo.local, a real variable, or the demo vault (secrets:generate-keys --env=demo then secrets:set DEMO_SUPERADMIN_PASSWORD --env=demo, see Secrets; its private key stays on the server, as production's - .gitignore: config/secrets/demo*/demo*.decrypt.private.php). That key pair is also what #[Vault] needs if the super-administrator types API keys in the demonstration's back office (Sealed fields).

The templates - one line each:

{# templates/base.html.twig (or the layout): first thing in <body> #}
{{ include('@Base/demo/_banner.html.twig') }}

{# templates/security/login.html.twig: under the form #}
{{ include('@Base/demo/_accounts.html.twig') }}

The accounts - a bundle of the trade declares its roles; the site adds its own in src/Demo/DemoAccounts.php (DemoAccountProviderInterface), and its fixtures take them from Base\Demo\DemoAccountFactory instead of writing them a second time.

src/Kernel.php - only if it lists the environments it allows (getAllowedEnvs(), Symfony 8.1's skeleton): add 'demo'.

Then:

make env-demo && make up       # production's stack, APP_ENV=demo
make database-demo             # once

On a development machine, to look at it without leaving the dev stack: the web container alone in demo, by an override of two lines (services: { web: { environment: { APP_ENV: demo, APP_DEBUG: "0" } } }, docker compose ... -f that-file.yml up -d web), then make database-demo; make up brings dev back. The links public/uploads and public/images follow whichever environment cleared its cache last.

What a new site no longer copies

First start, in this order

make install-dev          # = make env-dev, make build, make up - build BEFORE up
make doctrine-migration   # the site's first migration
make doctrine-migrate
make database-test        # the test database
docker exec <app>-web-1 php vendor/bin/phpunit

make build comes before any up. /srv/app/public is a named volume (<app>-public) that no image seeds: the composer step of make build copies ./public (its index.php) into it when the volume is empty, then composer's assets:install links the bundles' assets (public/bundles/*). A stack started first - make up, a bare docker compose up - creates the volume with the public/assets mountpoint alone: not empty, so never seeded, and every page answers "File not found". Apfelschule's Makefile repairs that case itself since 2026-10-04 (seed-public, run by make build: a volume that exists without index.php gets ./public); with an older Makefile, by hand:

docker run --rm -v <app>-public:/to -v "$PWD/public":/from:ro alpine cp /from/index.php /to/
docker exec <app>-web-1 php bin/console assets:install public --symlink --relative

Stopping a site

make down (docker compose down, without -v): the containers and the site's two networks go, the volumes (database, public, vendor, storage) stay, and make up brings the site back as it was. Not docker compose stop: it keeps the networks, each holding a subnet of Docker's address pool, and with enough stopped sites the next up fails on "could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network". -v deletes the volumes: the database with them.

Steps

1. Copy the files of the first part - tracked files only, symfony.lock among them, neither .env.local nor .htpasswd; rename (APP_NAME, ports, composer.json, package.json); give the two networks their subnets.
2. make install-dev (composer and yarn in the setup containers, COMPOSER_ALLOW_SUPERUSER=1): see the order above.
3. Generate the key pairs (secrets:generate-keys, dev and test: see Secrets), then make doctrine-migration, make doctrine-migrate and make database-test. These run from a script or an agent as well as from a terminal: the Makefile's DOCKER_WEB, DOCKER_DATABASE, DOCKER_PROXY and DOCKER_ASSETS pass docker exec the TTY_FLAG (-ti when standard input is a terminal, -i otherwise), and so do make shell / make shell-debug given ARGS. Apfelschule's DOCKER_DATABASE and DOCKER_PROXY used a bare -ti, and make database-test stopped on "the input device is not a TTY" outside a terminal (fixed 2026-10-04): a site copied from an older Makefile changes those two lines the same way.
4. Write the site's SettingsSectionInterface classes for its own settings and keys.
5. docker exec <app>-web-1 php vendor/bin/phpunit: green before the first commit.

Apfelschule moved onto the shared bricks in migrations/Version20261004090000.php (textOverride → layoutTextOverride, blog_comment → threadComment, the hours tables): the model for the existing sites when they are attached one by one.

Settings

Settings are stored per locale and compiled into a single snapshot at warmup, so reading one at runtime never queries the database.

Reading a setting

$title = $settingBag->get('base.settings.title');

get() degrades to null on a missing path rather than throwing — a missing setting is a normal state during a deployment, not an error.

Translatable values

A setting's value lives in SettingIntl, one row per locale. The default locale is not special-cased at the storage layer; every locale is a row.

Architecture

The bundle is organised around a few long-lived pieces:

• Entities — Thread and its subtypes carry the shared title/slug/content model that articles, comments and pages all reuse.
• The contracts of the Fondation — what framework-free code asks of the application (URLs, translations, access, locales, files, the clock, events, mail), through Base\Contract\Runtime: The contracts.
• The Doctrine mapping — what omnibase assembles at runtime (the attributes, the translations, the discriminator maps, the filters, the types), wired by Base\Bridge\Doctrine under Symfony and on an entity manager built by hand, on doctrine/orm as published: The Doctrine mapping.
• Settings — a compiled snapshot of configuration, read through SettingBag.
• Admin — a from-scratch administration bundle (base-bundle-admin).
• Account security — what the administrator sets, and a second factor required of some roles: Account security.
• The demo environment — APP_ENV=demo: declared demonstration accounts, one click to sign in, a nightly reset, and what it refuses: The demo environment.
• Forms — the theme, and where a field's texts are translated: Forms.
• Sealed fields — #[Vault], its key pair, and what happens without one: Sealed fields.
• Errors — which status an error is answered under, and the 404 that are meant: Errors and refusals.
• Time — PHP's zone is the visitor's; a moment is stored in UTC (utc_datetime_immutable), see Time and time zones.
• The forms' guard — a trap, the time, the lists, a captcha, the classifier, one option (guard): The forms' guard.
• Politeness — tu or vous, です / ます or 敬語: one setting of the site (base.translator.politeness) and a variant per text (key._polite), see How the site addresses people.

The warm-up: every class of every bundle

On its first boot (and after a cache:clear), BaseBundle::warmUp() maps each Base\* bundle's directories onto their mirrors (Base\X\Entity\Y ↔ Base\Entity\X\Y, Base\Entity\Y ↔ App\Entity\Y...) and, to do so, loads every class it finds there. The result is kept in var/cache/<env>/pools/base/bundle.php.

A bundle may hold classes for a package it only suggests - a digest source implementing omnibase/newsletter's interface, an exporter extending a provider's class. Without that package, such a class cannot be declared (Interface "..." not found, or Class, Trait, Enum). The warm-up passes it by: it is not aliased, and the rest of the directory is. Nothing registers it without its package (the bundle's service configuration loads it only when the package is there), so nothing misses it. Any other error while loading a class

• a parse error, a broken bundle - still stops the boot.

AbstractBaseBundle::classLoads($class) is that check (true, false, or the error rethrown); AbstractBaseBundle::getUnloadableClasses() lists what the warm-up passed by in this process, with the reason - the first place to look when an alias is missing.

Rebuilding an entity's previous state

The attributes that act on a change (#[Uploader] above all) compare an entity with its state before the change: AbstractAttribute::getOldEntity() rebuilds it, without its constructor, from Doctrine's original data through object_hydrate(). Doctrine keeps an enum field there as its backing value ("draft", not Status::Draft); object_hydrate() turns it back into the case (BackedEnum::tryFrom(), or the case of that name for a pure enum) whenever the property is typed with an enum, and leaves the property out when no case matches. property_enum_value(ReflectionProperty, $value) is that conversion, for any other code that fills typed properties by reflection.

Entities and repositories

Repositories

Base\Database\Repository\ServiceEntityRepository is doctrine/orm's EntityRepository built from the ManagerRegistry (doctrine/persistence), as DoctrineBundle's service repository is - __construct(ManagerRegistry $registry, ?string $entityName = null), the entity guessed from the repository's name - plus the finder language (findByStateAndLocale(), cacheOneBySlug(), countByDomain()...). It does not extend DoctrineBundle's class: a repository loads without the framework (it is in tests/Fondation.php). Under Symfony every service extending it is tagged doctrine.repository_service (BaseExtension, registerForAutoconfiguration()), so an application's App\Repository\* is still handed out by getRepository() and autowired.

Counting gives an integer. count([]), count(['state' => 'draft']), countByState('draft') and distinctCountForLocaleByDomain('messages') each run one SELECT COUNT(...) and return an int, as Doctrine's count() promises. Only a grouped count (a $groupBy or a $selectAs argument) returns rows, each with its count (ThreadRepository::countForChildrenIn()).

What is registered as a repository. A bundle maps its src/Repository (setMapping() in its Bundle class): every class there is aliased under the application's namespace, and the ones that are repository services are registered (doctrine.repository_service, built with doctrine). A repository service is a class whose name ends with Repository, that can be instantiated and extends omnibase's ServiceEntityRepository or implements DoctrineBundle's ServiceEntityRepositoryInterface (AbstractBaseBundle::isRepositoryService()). An abstract base repository, an interface or a trait in that directory is aliased, never registered: a bundle may keep AbstractCatalogueRepository beside the repositories that extend it.

Translations

An entity using TranslatableTrait reads and writes its translated fields through translate():

$post->translate('de')->setTitle('Apfel');   // written in German, persisted at the next flush
$post->translate('ja')->getTitle();          // null when nothing is written in Japanese; creates nothing
$post->translate()->getTitle();              // what the current page shows

• translate($locale) is that locale's translation. When the entity has none, it is a new, empty one the entity holds aside (out of getTranslations()) until a value is written in it: a read creates no translation. A written one joins the collection at the next getTranslations() or flush (commitPendingTranslations(), called by IntlSubscriber before each flush).
• translate() without a locale is the translation to show on the current page: the page's language when something is written in it, else the same language in another region (pt-BR on a pt-PT page), else the default locale's, else the first available locale's, else any written one.
• The magic getters ($post->getTitle(), post.title in Twig) read translate(), then the default locale when the value is null.

An isEmpty() translation is never persisted (IntlSubscriber::onFlush).

Countries

{{ code|country_name }} names a country from its ISO 3166-1 code, in the page's language; {{ code|country_name('de') }} in the one given (Localizer::getCountryName(), on symfony/intl). JP is "Japon" on a French page; alpha-3 (JPN) is read too; an unknown code is printed as it is. The country of a locale (fr-BE → "Belgium") is |locale_country_name.

A taxon's slug is unique per type

Base\Entity\Thread\Taxon is the root of a JOINED hierarchy: a FAQ's Section, a classroom's Subject, a menu's MenuSection, a site's own Category all share the table threadTaxon and its slug column. The slug is unique among the taxa of one type - the unique index is on (class, slug), class being the discriminator - so a menu's section and a blog's category may both be desserts. (It was unique on the column alone: the second one became desserts-2, whatever its type.)

#[Slugify(reference: 'translations.label', perType: true)] is what numbers a slug only against the entities of the same class; any hierarchy that shares a slug column may use it.

The migration an application generates after updating omnibase (bin/console doctrine:migrations:diff), on threadTaxon: the unique index on slug is dropped, a unique index thread_taxon_type_slug on (class, slug) and a plain index thread_taxon_slug on slug are created. No row changes; the new constraint is weaker than the old one, so it always applies. Until that migration has run, omnibase sees the old index and keeps numbering slugs for all types together: nothing fails in between.

A taxon is found by its slug through the repository of its type (SectionRepository::findOneBySlug()): TaxonRepository itself may now find several types under one slug.

The second-level cache after the fixtures

A site that turns on Doctrine's second-level cache (doctrine.orm.second_level_cache) caches its entities by id. A command that rewrites the database behind the ORM's back leaves that cache wrong: doctrine:fixtures:load purges the tables with DELETE / TRUNCATE, the new rows are numbered from 1 again, and the cache answered yesterday's entity for today's id until it expired.

Base\Subscriber\SecondLevelCacheConsoleSubscriber empties every region (entities, collections, queries) of every entity manager when one of these commands ends: doctrine:fixtures:load, doctrine:schema:{drop,create,update}, doctrine:database:{drop,import}, doctrine:migrations:{migrate,execute}, dbal:run-sql. Nothing to configure; cache:pool:clear by hand after loading fixtures is no longer needed. A command of your own that writes SQL directly calls it: $subscriber->evict().

The contracts of the Fondation

What omnibase's framework-free code (an entity's getter, an attribute, a value object) asks of the application it runs in, by an interface, never by a Symfony service (plan "omnibase agnostique", step C4). Each is reached through one registry, Base\Contract\Runtime, which the framework fills at boot.

Locales is plural, as omnibridge's Urls and Translations are, and so that importing it never shadows PHP's \Locale.

A token per intent, under Symfony only. Symfony's CSRF tokens are one per intent (2fa_disable, passkey_delete_12...): a screen's action carries the token of its own intent, and the controller checks that one. Laravel has a single session token for every intent: an action pointing at a Symfony route, rendered by Laravel, would carry a token Symfony refuses. Nothing does that today - the Laravel twin shows no account page; a framework rendering another's actions binds Tokens to the other's tokens, or posts to its own routes.

No contract for the mail. symfony/mailer is a standalone component, allowed in the Fondation (decision D1), and Laravel's own mail is built on it: its MailerInterface is the contract, and another framework hands a Mailer over its own transport.

The registry

use Base\Contract\Runtime;

Runtime::urls()->path('blog_article', ['slug' => $slug]);
Runtime::access()->isGranted('ROLE_ADMIN');
Runtime::translations()->trans('@entities.article._singular', [], null, Runtime::locales()->getLocale());

• Filled at boot. BaseBundle::boot() hands it the base.contracts locator (ContractsPass): each contract by its interface's name, bound to the service the container gives that name - an application rebinds one by aliasing the interface. Only the contracts whose service exists are listed, and a locator holds closures: nothing is built before it is asked. Another framework calls Runtime::setContainer() with a PSR-11 container whose ids are the interfaces' names (Laravel's application is one), or Runtime::set() one contract at a time (it wins over the container's).
• Loud when empty. A contract asked and not filled throws Base\Exception\MissingContractException, which names it - where a getter through BaseTrait that found no service returned null in silence. Runtime::find() answers null instead, for a caller that can do without.
• One kernel at a time. A different container forgets what the previous one gave (as BaseCommonTrait::setRuntime() does); Runtime::reset() forgets everything (a test's tear-down).

The contracts, the registry, SystemClock and the adapters load without the framework (tests/Fondation.php); tests/BareTest.php runs tests/Contract/runtime-without-framework.php with the autoloader alone: plain PHP implementations bound as another framework binds them, and a user of the contracts that answers through them. tests/Bridge/Symfony/ContractAdaptersTest compares every adapter's answers with the services and the Twig functions they stand for.

A link by a router's reference type: Base\Contract\Link

The entities' __toLink(array $routeParameters = [], int $referenceType = ...) take Symfony's reference types. Link::to($name, $parameters, $referenceType) makes the address through Runtime::urls(): Link::ABSOLUTE_PATH (1) is path(), Link::ABSOLUTE_URL (0) is url() - the values of UrlGeneratorInterface's constants, named here so that a link is made without the routing component (LinkableInterface's default is Link::ABSOLUTE_PATH). A relative or a network path has no equivalent in the contract: it is asked of the implementation's own generate($name, $parameters, $referenceType) when it has one (RouterUrls, the router as before) and refused otherwise. It is a helper, not a contract.

The entities' getters on the contracts (step C3e)

What an entity of the core asked of BaseTrait's services and now asks of the registry, with the same answers under Symfony (tests/Contract/EntityGettersTest compares each with the service it used) and answers where there is no framework (tests/Contract/entities-without-framework.php, run by BareTest):

Base\Service\Model\LocaleNormalizer is the Localizer's rule for omnibase's xx-XX form, taken out of it: Localizer::normalizeLocale(), __toLocaleLang() and getLocales() now ask it with the Localizer's own statics, so the strings are the same by construction; the entities ask it with the Locales contract's (here()). The test keeps a copy of the rule as it was and compares both paths with it.

The screens (step C5)

A controller hands a template and a view model (Base\Screen\View: template, Base\Screen\Screen, the React component's name, the status) to Base\Bridge\Symfony\ScreenResponder, which renders it with the request's frame (Base\Screen\ContextProvider, under Symfony SymfonyScreenContext: locale, site, links, viewer, theme, a site's own fields; the flashes) - Twig with frame and screen, or omnibridge/react's page in JSON (X-Omnibridge; without omnibridge/react, a request asking application/json alone gets the props). A JSON answer carrying a viewer is private and varies on Cookie. The view models (Base\Screen\*: Frame, Site, Viewer, Author, Tag, Link, StoryText, Card, Story, Comment, Reply, Discussion) keep lesringostars' prop names (App\Screen\*, the pilot's); Base\Screen\Builder\Stories makes them from a Thread and its comments with the Texts and Pictures contracts and the clock (recent, so that no template compares a moment). All of them are in the Fondation (tests/Screen/screens-without-framework.php).

The account's pages are screens too (C5, its second part): a member's profile, the settings, the notifications (Base\Screen\Account\{ProfilePage, SettingsPage, NotificationsPage} and their parts), built by Base\Screen\Builder\Accounts from the entities and the security policy, with the Urls and Tokens contracts and the clock (a notification's group, in Twig's time zone), and handed by the controllers with Base\Bridge\Symfony\AccountScreens (what only Symfony knows: the viewer, an avatar's thumbnail, the providers, web push). A visitor's profile carries what its page shows them, nothing of the account. The settings' small forms are Actions (an address and the token of its intent); a screen carrying tokens is Base\Screen\Confidential, whose answers are private, no-store and vary on Cookie. A screen's props never take one of the frame's keys (Frame::RESERVED): the responder refuses it. A template a site overrides gets the variables of before as well (ScreenResponder::legacy()); a host page renders the core's profile template with the user alone, account_profile(user) giving it the model. The forms (profile edit, sign-in, sign-up, passwords, two-factor setup) stay Symfony's (D3).

The Doctrine mapping, with or without Symfony

omnibase assembles part of its entities' mapping at runtime: the attributes read by Base\Attributes\AttributeReader (#[DiscriminatorEntry], #[Alias], #[Hierarchify], #[Cache], #[OrderColumn], #[Cascade], #[OrphanRemoval], #[Vault]...), the translations' associations and discriminators (IntlSubscriber), the enumerations as column types, the trash_filter and the vault_filter, the DQL functions. Since step C6 of the plan "omnibase agnostique" all of it is wired by Base\Bridge\Doctrine - under Symfony through the bundle, as before, and on an entity manager built by hand without DoctrineBundle - on doctrine/orm as published: nothing needs a member Doctrine keeps private, and glitchr/base-plugin leaves doctrine/orm alone for this core (its composer.json says extra.base-plugin.doctrine/orm: false).

Without Symfony

use Doctrine\DBAL\DriverManager;
use Omnibridge\Doctrine\EntityManagers;
use Base\Bridge\Doctrine\Mapping;

$connection = DriverManager::getConnection(['driver' => 'pdo_mysql', 'host' => ..., 'dbname' => ...]);
$entityManager = EntityManagers::create($connection, [
    $vendor.'/omniscient/omnibase/src/Entity',
    $projectDir.'/src/Entity',
    // a bundle's src/Entity...
], configure: Mapping::configure(...));   // the repository factory, before the entity manager exists
$mapping = Mapping::register($entityManager, [
    'project_dir' => $projectDir,          // its src/Enum, its src/Attribute
    'environment' => 'prod',               // the vault filter's
    'types' => [/* a bundle's enumerations, by name */],
    'resolve_target_entities' => [/* interface => class */],
]);

$articles = $entityManager->getRepository(App\Entity\Blog\Article::class)->findBy([], ['id' => 'DESC'], 10);
$article = $entityManager->createQuery('SELECT a FROM App\Entity\Blog\Article a WHERE a.slug = :slug')->setParameter('slug', 'le-fuji')->getOneOrNullResult();

Mapping::register() is called before the first metadata is read. Doctrine's own ClassMetadataFactory is used; the class names are the core's (D6).

What the hand-built side does not have: the framework's services. The AttributeReader is given no router, request stack, token storage, filesystem nor event dispatcher (an asset's base path, the user signed in, the routes' attributes answer without them), IntlSubscriber no localizer, and the parameters are those given (Base\Service\ArrayParameterBag). Symfony's doctrine-bridge types (uuid, ulid, date_point...) are Symfony's alone.

The discriminator maps

A root entity that declares an inheritance and no #[DiscriminatorMap] gets one generated by MappingDriver, after the attributes are read: the class and every subclass the driver knows, each under its class name, which #[DiscriminatorEntry] (AttributeSubscriber, loadClassMetadata) then renames (common, marketplace_product, forum_topic...). Doctrine generates such a map itself, under the classes' lower-cased short names - which collide here (App\Entity\Thread\Tag and Base\Entity\Thread\Tag are both tag) - and its getShortName() is private: until C6 glitchr/base-plugin made it protected so that omnibase's factory could answer the class name. The map is now there before Doctrine looks, with the keys the factory gave.

The resolveDiscriminator event (Base\Database\Events) is dispatched by the driver before a class is read, as the factory dispatched it: IntlSubscriber gives a translation class (ThreadIntl...) the inheritance and the map of its translatable.

The proof

tests/Bridge/Doctrine/HandBuiltEntityManagerTest (the harness, or an application's vendor suite):

• an entity manager built by hand in a PHP process of its own (tests/Bridge/Doctrine/hand-built.php: Composer's autoloader, a DBAL connection, EntityManagers::create(), Mapping::register()) gives the metadata Symfony's gives, class by class - Base\Bridge\Doctrine\MetadataSnapshot: every public property of each ClassMetadata (table, inheritance, discriminator map and value, fields and their types, associations, cache, callbacks, entity listeners, repository), what each filter adds to a query of it, the completor the attributes filled (aliases, hierarchy), the types registered - on the same database, and reads the thread Symfony wrote; the process loads neither the kernel nor a bundle;
• Symfony's entity manager gives the metadata it gave before C6 (fixtures/doctrine-metadata.json, recorded on the code of before with DOCTRINE_SNAPSHOT=1; the discriminator maps and the subclasses compared sorted: generated, they come in the order PHP declared the classes).

The harness runs it on doctrine/orm as released: docker compose -f compose.yml -f compose.checkouts.yml run --rm -v <doctrine/orm's release>/src:/srv/demo/vendor/doctrine/orm/src:ro omnibase test.

Time and time zones

omnibase sets PHP's time zone per visitor: BaseBundle::boot() reads the visitor's zone in the cookie the page's script writes (LOCATION/TIMEZONE where the visitor answers for the time zone apart, else USER/INFO's timezone; User::getCookie('timezone') reads both) and calls date_default_timezone_set() with it, UTC without one - a visitor who refused that cookie included. new \DateTime(), date() and Twig's |date are therefore the visitor's clock: "today" is the visitor's day.

What a column holds depends on its Doctrine type:

datetime_immutable is Doctrine's own: the same instant is stored at different hours by a visitor in Paris and one in Tokyo, and a row written by one comes back as another moment to the other. It is right for a wall clock (a reservation at 20:00 in the restaurant, whoever looks at it) and wrong for a moment (when a message was sent, when a link expires).

A moment: utc_datetime_immutable

use Base\Database\Type\UtcDateTimeImmutableType;

#[ORM\Column(type: UtcDateTimeImmutableType::NAME)]   // 'utc_datetime_immutable'
private \DateTimeImmutable $sentAt;

#[ORM\Column(type: UtcDateTimeImmutableType::NAME, nullable: true)]
private ?\DateTimeImmutable $expiresAt = null;

The bundle registers the type (and utc_datetime, its \DateTime twin): nothing to configure. Whatever zone the object given carries, the column gets the moment in UTC; what comes back is a \DateTimeImmutable in UTC, the same moment for every request. To show it, {{ message.sentAt|date('d/m/Y H:i') }} converts to PHP's zone (the visitor's); in PHP, ->setTimezone(new \DateTimeZone('Europe/Paris')).

In a query, bind the parameter with the type, or as a UTC moment (Base\Database\Type\Utc):

$qb->andWhere('m.sentAt >= :since')
   ->setParameter('since', $since, UtcDateTimeImmutableType::NAME);
// or
   ->setParameter('since', Utc::from($since));          // the same moment, in UTC
Utc::now();                                             // the present, in UTC

A \DateTimeInterface bound without a type is formatted in its own zone, and compared as text with a column that holds UTC.

Existing columns

Nothing changes for a column that is not given the type: datetime_immutable keeps Doctrine's behaviour, datetime stays UTC.

Moving a column from datetime_immutable to utc_datetime_immutable changes no schema (both are the platform's DATETIME: doctrine:migrations:diff finds nothing on DBAL 4), but it changes what the stored values mean: rows written by requests in another zone than UTC hold that zone's wall clock. A site whose visitors have no timezone cookie yet (PHP was in UTC) has nothing to convert; otherwise the migration that accompanies the change shifts the rows from the zone they were written in:

UPDATE office_appointment SET startsAt = CONVERT_TZ(startsAt, 'Europe/Paris', 'UTC');

For bundles

Base\Restaurant\Model\Instant and Base\Office\Database\UtcDateTimeImmutableType answered the same need before the core did; a bundle now names the core's type and drops its own (utc_datetime_immutable is the same name as office's: its columns need no change).

Politeness

A site says tu or vous, du or Sie, 常体, 丁寧語 or 敬語. That is one setting of the site, and one variant per text that changes with it.

# config/packages/base.yaml
base:
    translator:
        politeness: polite      # plain | polite | formal - unset by default

Unset, nothing changes: every text is the one written in the catalogue. The parameter is base.translator.politeness; Base\Service\Translator holds it (getPoliteness(), setPoliteness() for a message written to somebody the site addresses otherwise).

The three levels and the key of a variant

A text keeps one key and one base text. A variant is that key followed by the level, beside it in the same file:

# translations/notifications+intl-icu.fr.yaml
login:
    already: Tu es déjà connecté !
    already._polite: "Vous êtes déjà connecté !"

Nothing changes where the text is asked: '@notifications.login.already'|trans answers the base text or its variant, by the site's level.

What is tried, the first found wins:

A variant takes the parameters of its text ({0}, {name}, a plural). It is a text like another: asked by its own key (key._polite) it is answered as it is, whatever the level.

The base text is not at the same level in every language

The base text is whatever was written first. What a level needs depends on it:

omnibase itself ships French and English. A language's row holds for a bundle's or an application's catalogue in that language too: say in which level the base text is written, write the variants of the others.

For a Japanese site in formal: a _formal variant of each sentence addressed to the visitor (confirmations, errors, e-mails, the checkout's steps - 保存しました。 becomes 保存いたしました。, できません becomes いたしかねます), in the catalogues of the bundles it uses and its own. Labels, titles and buttons stay as they are. Until a variant is written the sentence stays in です / ます, which a 敬語 page tolerates.

Language first, level second

The catalogues are walked as Symfony falls back between languages, and in each one the variants are looked for before the base text. A German page whose text has no _plain variant keeps its German text - it is not given the French one that has it. A text missing in German altogether is read in the fallback language, at the level asked.

Whose text it is

Within a language, the closest hand wins:

1. a text rewritten in the back office (omnibase/admin's « Textes du site »): its key._polite if it rewrote one, else its key;
2. the application's own catalogue (translations/ of the project): its key._polite, else its key;
3. the bundles': their key._polite, else their key.

So an application that replaced a bundle's text under its key - a practice's « Aucun message. » in place of a forum's « Tu n'as aucun message dans ta boîte. » - keeps its sentence when the bundle brings a polite variant of the one it replaced, and still gets the bundle's variants for what it did not replace. Nothing in the merged catalogues tells whose a text is: the application's keys are read while the container is built (ApplicationTextsPass, from translator.default_path: YAML, PHP and JSON catalogues), and only when a level is set.

Where it applies

Base\Service\Translator is the translator service (it decorates Symfony's), so the level holds on every way a text is asked:

• the service (trans(), transQuiet(), transEntity(), transEnum());
• Twig: |trans, {% trans %}, the form themes' labels, helps and errors;
• the e-mails and the notifications, which translate through it;
• the validator's messages (a constraint's message is a key like another).

A text that refers to another one ("@notifications.login.success.day.first") is answered at the same level.

A call that gives its own level

It is answered at that one, the site's is not asked:

$translator->trans('@emails.resetPassword.subject', [Translator::TRANSLATION_POLITENESS => Translator::POLITENESS_PLAIN]);
$translator->trans('@emails.resetPassword.subject', ['politeness' => 'none']);   // the text as written
$translator->transEntity($user, 'email', [Translator::POLITENESS_FORMAL, Translator::NOUN_SINGULAR]);

{{ '@notifications.login.already'|trans({politeness: 'plain'}) }}

politeness is taken out of the parameters before the text is formatted.

Adding variants in a bundle or an application

1. Find the texts that address the reader at the base level (in French: tu, te, ton, ta, tes, toi and the imperatives - Choisis, Clique - which no pronoun gives away).
2. Write each variant under <key>._polite (or ._plain, ._formal) right after its text, same indentation, same parameters, same meaning.
3. An application overrides a bundle's variant as it overrides any text: the same key in its own translations/<domain>+intl-icu.<lang>.yaml.

tests/Translation/PolitenessCataloguesTest is the check omnibase runs on its own catalogues: every variant beside its text, with its parameters; in French no polite variant that still says tu, no text that says tu without one. Copy it for a bundle's catalogues.

The forms' guard

One option on a form, every check in its order:

$this->createForm(ContactType::class, $model, ['guard' => true]);
$this->createForm(ContactType::class, $model, ['guard' => ['action' => 'contact', 'min_delay' => 5]]);

Step 5 is spam_protection, on by default outside the back office as it always was: it runs only once the form is otherwise valid, so nothing is sent to the classifier for a form already refused. A robot caught by steps 1 to 3 does not reach the captcha's provider either.

The messages are the forms domain's guard.* (French and English), the captcha's the validators domain's - none says tu.

The option

The captcha after a few refused tries

A visitor who fills a form once does not see the captcha. Each try of a guarded form that is refused - by the guard (trap, time, lists, the classifier's spam) or because the form is invalid - counts one for that form and that visitor (the address, else the session; in cache.app, for 15 minutes); a form sent forgets them. From captcha_after tries on, the form prints the widget and the guard asks its token; below, nothing of the captcha is printed (neither the widget nor its script) and no token is asked. The trap, the time and the lists are asked every time.

The form refused at the threshold, printed again, carries the widget: the field is always in the form, but below the threshold it is taken out of the form's view, so form.guard_captcha is defined is false, form_rest and form_end print nothing of it, and a template that writes {% if form.guard_captcha is defined %}{{ form_row(form.guard_captcha) }}{% endif %} needs no change. Without cache.app - or without an address or a session to count by - the captcha is always shown, as it was before the threshold. captcha_after: 0, on a form or in base.guard, does the same.

Without glitchr/omnishield

glitchr/omnishield is suggested, not required (it is not on Packagist yet). Without it - or without a gateway configured - the trap and the time alone, and no error. With it:

// config/bundles.php
Omnishield\Bridge\Symfony\OmnishieldBundle::class => ['all' => true],

# config/packages/omnishield.yaml
omnishield:
    gateways:
        forms: { factory: altcha, options: { hmac_key: '%env(ALTCHA_HMAC_KEY)%' } }
        emails: { factory: disposable }
    challenge: { gateway: forms }

when@test:
    omnishield:
        gateways:
            forms: { factory: fixed }      # the hidden field omnishield-token carries omnishield-fixed-token

# config/packages/base.yaml
base:
    guard:
        challenge: ~             # the captcha: null for omnishield.challenge.gateway, a gateway's name, false for none
        fallback: ~              # the captcha of a visitor who refused the third party the captcha reaches
        reputation: [emails]     # the lists asked about the sender
        classifier: ~            # the classifier behind SpamChecker; null: Akismet with api.spam.akismet
        unreachable: accept      # a list or a classifier that does not answer: accept, or reject
        min_delay: 3
        sign_in_after: 3         # failed sign-ins from an address before the sign-in asks the captcha
        captcha_after: 3         # refused tries of a form from a visitor before it shows its captcha; 0: always

The captcha's own conduct when its provider does not answer is omnishield's (omnishield.challenge.unreachable).

With glitchr/ux-google

Where google.recaptcha.enable is true, ux-google's extension adds its own captcha (_captcha) to every form: the option guard then adds no second one - the trap, the time, the lists and the classifier stay. The places that ask ux-google's reCAPTCHA themselves (CommentType's recaptcha, omnibase/faq's AskType, the sign-in's badge) are left as they are.

Guarded by default

The captcha is checked by the guard itself, in its order and whatever the form's validation groups (the sign-up validates in new alone, where a field's constraint is not asked).

The sign-in

Symfony's login_throttling is the first line (five tries a minute). From base.guard.sign_in_after failed sign-ins from an address (3, counted for 15 minutes in cache.app, forgotten after a success), the sign-in form carries the captcha and a sign-in without a valid token is refused before its password is checked (Base\Security\SignInGuard). Not the rescue door, not the demonstration's one click; nothing where ux-google's reCAPTCHA is on.

Consent

ALTCHA, the default, reaches nobody: omnishield's Symfony bridge serves its widget's script from the site (omnishield/altcha ships it: /omnishield/altcha/3.3.0/altcha.min.js), so the page loads nothing from anyone else and there is no consent to ask. Nothing to add on a site but omnishield's bundle; omnishield.serve_scripts: false would put the CDN back.

A captcha whose widget reaches a third party (Widget::reachesOthers(): Turnstile, reCAPTCHA, ALTCHA's script when a site names a CDN) waits for the visitor's consent - omnibase/consent's feature CAPTCHA, declared by Consent.use() - kept inert in a <template> until then. Beside it, the fallback that reaches nobody (base.guard.fallback, ALTCHA) is shown, and stays after a refusal: a refusal does not open the form. The guard asks the third party's token when there is one, the fallback's otherwise. Without a fallback, a widget that sets cookies (reCAPTCHA) waits all the same; one that sets none is loaded at once. A page without omnibase/consent's script shows the fallback alone.

In a site's tests

The test client submits a form the moment it reads it, and a suite signs in wrong on purpose:

when@test:
    base:
        guard:
            min_delay: 0          # the stamp is still checked: post the one the page prints
            sign_in_after: 0

With factory: fixed as the test captcha, the page prints a hidden omnishield-token field holding omnishield-fixed-token, outside the form: a test client that submits the page's form sends it; a request built by hand adds it. Below captcha_after the page prints no captcha and none is asked: a token posted all the same is not read.

The comment forms

Base\Service\CommentGuard is the comment forms' face of FormGuard: CommentType's url trap and opened time, and a second comment from the same address within base.comments.flood_interval. omnibase/blog and omnibase/video call it.

Account security

Base\Service\SecurityPolicy is the one place that says what an account may change about its own security; the settings page (/settings), the actions behind its buttons and the enrolment prompt all ask it. In a template it is the global security_policy.

What the administrator sets

Settings, saved in the back office (each has its own default while unsaved):

A second factor for some roles

"Mandatory" in the settings is for everyone or no one. An application that requires a second factor of some accounts only - the staff of a practice, not its patients - says which roles:

# config/packages/base.yaml
base:
    security:
        two_factor:
            required_roles: [ROLE_STAFF]   # held directly or through security.role_hierarchy
            postpone: true                 # false: no "not now" on the enrolment prompt

The list is one value: defined again - in the file's when@dev or when@test block, or in another file - the later definition replaces it (Symfony would append the items of a list; this one opts out), so an environment can require it of other roles, or of none:

when@test:
    base:
        security:
            two_factor:
                required_roles: []         # nobody is sent to the enrolment page in the tests

A definition that does not name required_roles (only postpone, say) keeps the list as it was.

An account holding one of these roles and no second factor is sent to /settings/security-required (user_settings_enrolment) by SecurityEnrolmentSubscriber - on a plain page load only: a form post, an XHR, a download are never interrupted, nor the settings, sign-in and sign-out pages. It cannot switch its last factor off afterwards. Every other account stays free to choose. While base.settings.security.two_factor is off, nothing is required of anyone.

postpone: true (the default) keeps the prompt's "not now": the answer lasts the session, and the prompt returns at the next sign-in. With false the button is gone and the account is sent back to the prompt on every page until it has a second factor. An administrator impersonating the account is never the one asked to enrol.

$policy->isTwoFactorMandatory();        // for the whole site (the administrator's setting)
$policy->isTwoFactorMandatory($user);   // for this account: the setting, or one of its roles
$policy->isTwoFactorRequiredByRole($user);
$policy->needsEnrolment($user);         // mandatory for it, and it has none
$policy->canDisableTwoFactor($user);
$policy->canSkipEnrolment($user);

A passkey replaces the password; it is not counted as a second factor.

In the demo environment

A declared demonstration account (The demo environment) is shared by every visitor: nothing above is required of it - not the second factor of its roles, not "mandatory for everyone" - and it changes none of its credentials (isDemoAccount($user), canChangeCredentials($user), canEnableTwoFactor($user)). Every other account, and every environment other than demo, is as described here.

The demo environment

A fourth environment beside dev, test and prod: APP_ENV=demo runs a site as a demonstration - production's behaviour (no debug), a database of its own, and accounts that are always there, one for each role of the trade. A visitor reads the account's name in the banner of any page, opens the sign-in page, clicks "Patient", and is in. The back office is not part of what is public: its accounts sign in with a secret.

Everything below lives in omniscient/omnibase and is active when kernel.environment is demo, and only then. In dev, test and prod none of it is in the container: no route, no listener, no header. What an application adds to run it is listed in Scaffolding a site.

Declaring the accounts

A bundle declares the roles of its trade, the application its own, by implementing Base\Demo\DemoAccountProviderInterface (autoconfigured, tag base.demo_account_provider):

namespace App\Demo;

use Base\Demo\DemoAccount;
use Base\Demo\DemoAccountProviderInterface;

final class DemoAccounts implements DemoAccountProviderInterface
{
    public function getDemoAccounts(): iterable
    {
        yield new DemoAccount(
            identifier: 'client',                      // what it signs in with (User::$userIdentifier)
            label: 'demo.client.label',                // the button: a translation key, or the text itself
            description: 'demo.client.description',    // one sentence on what this role sees
            roles: ['ROLE_USER'],                      // its own roles
            position: 20,                              // the order on the sign-in page
        );
        yield new DemoAccount('docteur', '@health.demo.practitioner.label', '@health.demo.practitioner.description',
            group: 'Praticiens', groupRoles: ['ROLE_PRACTITIONER']);   // a Base\Entity\User\Group and its roles
    }
}

• The password is the identifier unless password: says otherwise, the address <identifier>@example.org unless email: does. A demonstration account is public: that is what it is for.
• Base\Demo\DemoAccountRegistry gathers every declaration. The application's replaces a bundle's for the same identifier; base.demo.exclude: [kine] drops the ones a site has no use for.
• A super-administrator is never a demonstration account. A declaration whose roles reach ROLE_SUPERADMIN - its own, its group's, or through security.role_hierarchy (a ROLE_EDITOR above it) - is refused with a LogicException as soon as the registry is read, in every environment.
• An account that opens the back office is declared, and offered to nobody. One whose roles reach base.demo.admin_roles ([ROLE_ADMIN], through the hierarchy too) is created by the fixtures as the others are - dev and the tests sign in with it - and in demo it is neither in the banner nor on the sign-in page: DemoAccountRegistry::offered() is the list without them. See The back office.

One account for each role of the application, none for the back office

The roles of the application are the constants of its user_role type (App\Enum\UserRole, else Base\Enum\UserRole). Each one below the back office has a demonstration account holding it - its own roles or its group's; ROLE_USER is held by any account. Those that open the back office (base.demo.admin_roles, ROLE_SUPERADMIN, ROLE_EDITOR above it) have none offered. Roles a group gives and the enum does not name (a practice's ROLE_PRACTITIONER) are the bundle's to declare, as they do.

$registry->missingRoles();   // [] when every role has its account; demo:reset warns otherwise

A site's suite asserts it (self::assertSame([], $registry->missingRoles())). The banner names one account, the first offered (position); the others wait on the sign-in page.

In the fixtures

Base\Demo\DemoAccountFactory turns the declarations into rows, so that dev, test and demo have the same accounts and nobody writes them twice:

final class SiteFixtures extends Fixture
{
    public function __construct(private readonly DemoAccountFactory $accounts) {}

    public function load(ObjectManager $manager): void
    {
        $docteur = $this->accounts->account('docteur', $manager);   // the database's, or created from its declaration
        $this->accounts->load($manager);                            // every declared account

        // ...the practice's team, agenda and files, attached to $docteur
        $manager->flush();                                          // the factory flushes nothing
    }
}

An account the database already has is returned as it is: fixtures that create theirs themselves keep them, identifier included. A group is created with groupRoles when the database has none of that name, and left alone otherwise.

On the sign-in page

@Base/demo/_accounts.html.twig prints "Comptes de démonstration": one button for each account offered that exists. omnibase's own sign-in page includes it; an application with its own templates/security/login.html.twig adds the line under its form:

{{ include('@Base/demo/_accounts.html.twig') }}

Each button is a POST form with a CSRF token to security_loginDemo (/login/demo) - never a link: a GET that signs in is followed by a prefetch, a crawler, a link preview. The route is declared for the demo environment only. Base\Controller\DemoController signs in an account that is offered and nothing else: an identifier nobody declared, an account of the back office, or one promoted to it since, is sent back to the sign-in page.

The partial prints nothing outside demo. Its look hangs on .base-demo-accounts (it inherits the page's colours). A button and its sentence stand side by side; in a narrow place - a sign-in card of some twenty rem - the sentence goes under its button, full width (the flex line folds when less than 14rem are left beside the button: no script, no query on the window). To rewrite it, templates/bundles/BaseBundle/demo/_accounts.html.twig. In a template of your own: demo_mode() (true in demo) and demo_accounts() (the list).

The banner

@Base/demo/_banner.html.twig prints "Démonstration — données remises à zéro chaque nuit" (fr, en: the demo translation domain). A layout includes it once, first thing in <body>; omnibase/admin's layout does, so the back office shows it too:

<body>
    {{ include('@Base/demo/_banner.html.twig') }}

Two custom properties set its colours (--demo-banner-bg, --demo-banner-fg); templates/bundles/BaseBundle/demo/_banner.html.twig rewrites it.

The account, on every page

To a visitor who is not signed in, the banner goes on: "Compte de démonstration « Client » : identifiant client, mot de passe client. Se connecter" - the first account offered, what it signs in with, and a link to the sign-in page ("Se connecter ou choisir un autre rôle" when there are several). A site that includes the banner has nothing to add; a site with no account to offer keeps the banner's first sentence alone. Signed in, the sentence is gone.

It is a sentence and a link, not a button: a button that signs in is a form with a CSRF token, a token needs a session, and no public page starts one for a visitor who only reads.

demo:reset

php bin/console demo:reset                # the fixtures, the uploaded files, the caches
php bin/console demo:reset --keep-files   # the database and the caches only

In order: it refuses outside demo (and on what the guard below refuses); takes a lock (symfony/lock, the lock.factory service: two resets never overlap); empties the directories of base.demo.reset.purge; runs doctrine:fixtures:load; creates the declared accounts the fixtures left out; deletes the uploaded files no row names any more (uploader:entities --delete-orphans, unless base.demo.reset.orphans: false); empties every cache pool and Doctrine's second-level cache. Each step is written to the output and to the log; the exit code is not 0 when one failed.

It is written for the cron container. The crontab is the same in every environment, so the line checks the environment itself:

30 3 * * *  [ "$APP_ENV" = demo ] && php /srv/app/bin/console demo:reset >> /srv/app/var/log/cron.demo-reset.log 2>&1

# config/packages/base.yaml
when@demo:
    base:
        demo:
            reset:
                purge:                                   # storages of the application's own
                    - '%kernel.project_dir%/var/storage/documents'

The sessions open at that moment end: the accounts are new rows.

Give the demonstration storages of its own (when@demo in flysystem.yaml: var/storage/demo/uploads...), name that directory in purge, and turn the orphan search off (orphans: false): everything a visitor sent is then in one place that no other environment writes to. The orphan search reads the uploads through public/uploads, a link that points at the storage of whichever environment cleared its cache last - right on a server that runs the demonstration alone, not on a machine that runs dev from the same checkout.

The safeguards

E-mail: refused, not looped back

The two ways were a null transport and the "technical loopback" of dev (every message rewritten to one mailbox). The demonstration takes the first, and enforces it in the bundle rather than leaving it to MAILER_DSN: a visitor signed in as "patient" types any address in a form, and a loopback still delivers - to a mailbox someone then has to empty, and to a real person the day the loopback is misconfigured. A message that is never handed to a transport cannot reach anyone. An application still sets framework.mailer.dsn: 'null://null' under when@demo, so that nothing is even attempted by a library that would bypass Symfony's mailer.

What would have gone is in the log, at the info level of the demo channel (production's fingers_crossed handler keeps it for the context of an error; bin/console ... -vv shows it):

demo.INFO: Demonstration: e-mail not sent. {"to":["patient@example.org"],"subject":"Votre rendez-vous","queued":false}

What a demonstration account cannot change

Every visitor signs in with the same account: whoever changed its password would lock the next one out until the night's reset.

• omnibase's pages refuse with a message (@notifications.demo.locked): the second factor (/settings/2fa, its switches), closing the account (/account-goodbye), a password reset asked for or followed. The settings page says so first. They ask SecurityPolicy::isDemoAccount($user) / canChangeCredentials($user): use the same in a page of your own.
• For every other form - the application's "my account" page, the back office's users - Base\DatabaseSubscriber\DemoAccountLockSubscriber puts the values back before the row is written (and flashes the same message), and answers 403 to a deletion. Only during a request: the fixtures and demo:reset write these accounts from the console.

$policy->isDemoAccount($user);          // a declared account, in the demo environment
$policy->canChangeCredentials($user);   // false for it
$policy->canEnableTwoFactor($user);     // false for it
$policy->needsEnrolment($user);         // false for it, whatever its roles

The back office

A demonstration's password is its identifier: whoever reads "client / client" in the banner can guess "gestion / gestion". Behind the back office are the accounts of the visitors who signed up that day, the settings, the uploads - what one visitor writes there, every other one reads until the night's reset. So it is not public.

In demo, an account whose roles reach base.demo.admin_roles ([ROLE_ADMIN] by default; through security.role_hierarchy too) - declared as a demonstration account or not:

• is not offered: not in the banner, not on the sign-in page, not signed in by /login/demo;
• is the only one the back office opens to: any other account signed in
  • a demonstration account or one a visitor created, whatever its roles give it elsewhere (the kitchen's ROLE_STAFF reading the orders under /admin)
  • gets a 403 on every page of it (/admin, omnibase/admin's routes);
• signs in with base.demo.admin_password - by default %env(default::DEMO_ADMIN_PASSWORD)% - typed in the ordinary sign-in form with its identifier ("gestion"). The stored password is not looked at. Unset or empty, it cannot sign in by any means.

DEMO_ADMIN_PASSWORD is the secret given to whoever is shown the back office - a prospect, for the time of a presentation; changing it closes the door again. It is the deployment's, like the super-administrator's: a real environment variable or .env.demo.local, never .env.demo. Once in, the account is a demonstration account like the others: its credentials do not change, the staff's second factor is not asked of it.

when@demo:
    base:
        demo:
            admin_roles: [ROLE_ADMIN, ROLE_MANAGER]   # another role opens the back office here
            # admin_roles: []                         # ...or none: the back office as public as the rest

A role below these - the kitchen's ROLE_STAFF, a practitioner's group - stays public, with whatever pages of the back office the application opens to it: name it in admin_roles when those pages are not for everyone.

The super-administrator

The fixtures give Glitch Art's account a password everyone knows ("glitchr" / "glitchr"); a demonstration is public. In demo, Base\Subscriber\DemoBackOfficeSubscriber compares what is typed with base.demo.superadmin_password - by default %env(default::DEMO_SUPERADMIN_PASSWORD)% - and never looks at the stored password. Unset or empty, an account whose roles reach ROLE_SUPERADMIN cannot sign in by any means ("This account is not available in the demonstration."). It is not listed on the sign-in page and not signed in by /login/demo either way.

DEMO_SUPERADMIN_PASSWORD is a secret of the deployment: a real environment variable or .env.demo.local (git-ignored) on the demonstration's server. Never .env.demo, which is committed.

What it refuses to start on

Base\Demo\DemoGuard, asked by BaseBundle::boot() - for a page as for a command - throws Base\Exception\DemoRefusedException when:

• debug is on: APP_DEBUG=0 (bin/console --env=demo --no-debug);

• a connection reaches the production database: the application names it, and the guard compares server, port and database name (not the user: the same database under another account is the same database);

  when@demo:
      doctrine:
          dbal:
              connections:
                  default:
                      dbname_suffix: '_demo'            # <database>_demo, as the tests have <database>_test
      base:
          demo:
              production_database: 'mysql://%env(DOCTRINE_DATABASE_HOST)%:%env(DOCTRINE_DATABASE_PORT)%/%env(DOCTRINE_DATABASE)%'
  

• base.demo.production_database is unset: nothing could be compared, and demo:reset empties the database it is given.

One configuration for prod and demo

The demonstration behaves as production does: what a file sets under when@prod is shared, not copied. A YAML anchor does it within a file:

# config/packages/monolog.yaml
when@prod: &prod
    monolog:
        handlers: ...

when@demo: *prod

and a merge key when demo adds something of its own:

# config/packages/doctrine.yaml
when@prod: &prod
    framework:
        cache:
            pools: ...

when@demo:
    <<: *prod
    doctrine:
        dbal:
            connections:
                default:
                    dbname_suffix: '_demo'

(<< merges the top-level keys only: a key demo repeats replaces prod's whole block of that name.) A setting that has to differ in dev and test only is better turned round: the value at the root of the file, overridden under when@dev and when@test - then prod and demo both read the root.

A real environment variable beats every .env* file, and the containers receive .env and .env.local as real variables: .env.demo cannot change a value .env defines. What differs in demo is therefore said in the configuration (when@demo), and .env.demo holds only what .env leaves out (the hosts, as .env.prod does).

Reference

base:
    demo:
        production_database: ~            # DSN of production's database; required in demo
        superadmin_password: '%env(default::DEMO_SUPERADMIN_PASSWORD)%'
        admin_roles: [ROLE_ADMIN]         # the roles that open the back office: not offered, signed in by the secret
        admin_password: '%env(default::DEMO_ADMIN_PASSWORD)%'
        exclude: []                       # declared identifiers this site leaves out
        reset:
            purge: []                     # directories demo:reset empties before the fixtures
            groups: []                    # fixture groups it loads (--group); none: every fixture
            orphans: true                 # uploader:entities --delete-orphans after them

Forms

omnibase's form theme (templates/form/form_div_layout.html.twig, added to twig.form_themes by the bundle) renders every form: the form2 blocks, the label strip, the custom field types.

Labels, help and placeholders are translation keys

Texts are translated by Base\Service\Translator. A key may name its domain (@mailbox.form.subject), or be looked up in the field's translation_domain.

Every field has the domain fields by default (Base\Form\Extension\FormTypeExtension), where omnibase's own field types keep their words. A form type that declares its own domain is followed by its fields:

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults(['translation_domain' => 'mailbox']);
}

public function buildForm(FormBuilderInterface $builder, array $options): void
{
    $builder->add('subject', TextType::class, [
        'label' => 'form.subject',                         // mailbox.form.subject
        'help' => 'form.subject_help',
        'attr' => ['placeholder' => 'form.subject_placeholder'],
    ]);
}

The rule, applied when the view is finished (FormTypeExtension::inheritTranslationDomain()): when none of a field's label, help and placeholder exists in the field's own domain and one of them exists in the domain of a form above it, the field is rendered in that domain. Otherwise nothing changes: a field whose texts are in fields stays there, a key that names its domain is translated in it, and 'translation_domain' => false prints the texts as written.

(A field used to ignore its form's domain: the key was looked up in fields, found nothing, and the label was printed empty. The bundles named the domain in every key to go around it; they no longer need to.)

A PHP enum in a select

Base\Field\Type\SelectType bound to a property that holds a PHP enum finds its choices by itself - the cases - and hands the case back to the record:

$builder->add('state', SelectType::class);                                   // Doctrine enumType:, or a property typed with the enum
$builder->add('states', SelectType::class, ['class' => CommentState::class, 'multiple' => true]);

The select holds a case by its backed value (its name when the enum is not backed, Base\Form\Common\NativeEnum::id()). A case is labelled, in this order: by itself when the enum implements Symfony's TranslatableInterface; by the key <short class name in snake case>.<value> of the enums domain (comment_state.pending); by its name made readable. A value that names no case is an invalid choice, and the record keeps what it had.

A field that gives choices (or a choice_loader) keeps them as they are: the enum is not guessed over them, and ['Label' => 'value'] shows the label (translated when it is a key such as @agenda.role.soloist).

ClassMetadataManipulator::getFields() - what AssociationType builds an embedded form from - maps such a column to a SelectType as well; it used to be a TextType, which cannot print a case.

An entity in a select

SelectType with an entity class (or bound to a Doctrine association) is fed by the autocompletion and loads what was chosen from the class's repository: cacheById() on omnibase's repositories, find() / findBy() on a plain Doctrine one.

AssociationType embeds the related record's own form, always. The back office decides, for an AssociationField, between that form and a picker: see omnibase/admin's docs/crud-fields.md.

A select works before its script does

SelectType is drawn by select2, but the <select> the server prints is a whole one: on a page whose script did not run - blocked, failed, not loaded yet - it can be read, changed and sent.

• Its options. The choices of a static list or of an enum, groups as <optgroup>, with the labels select2 shows; for an autocompleted list, the records already chosen. select2 empties the select before filling it from its own data, as it always did: nothing is listed twice.
• Its selection. The record's value is the selected option - also in the lists that printed their options already (a choice_loader: CurrencyType), where none was selected and the browser sent the first of the list in place of the record's currency.
• An empty first option in a select of one value, carrying the placeholder: without it the browser picks the first choice for a record that has none. It is the option select2 itself asks for to show a placeholder.

(The select was printed with no option at all and filled by select2 alone: without the script a product's availability arrived null.)

required is checked by the server

A required SelectType sent empty is an error of the form - "This value should not be blank.", in the visitor's language (validators domain) - on the field itself, where its row prints it. The browser's required attribute was the only check, and the back office's forms are novalidate.

The empty value is not written into the record, which keeps what it had: the field fails as a transformation does (it is not synchronized), so a setter that takes no null - setStatus(PublicationStatus $status) - is not called with one. That call answered 500 ("Expected argument of type ..., null given") in place of the form's error.

• required is what the field says, true unless said otherwise ('required' => false, ->setRequired(false) on a CRUD field): a select on a nullable property that may stay empty has to say so.
• A list of several may be empty, as before, unless 'required_when_multiple' => true.
• A disabled field is not asked.

The field's errors no longer go up to the form (error_bubbling is false, as for Symfony's own compound choice and date fields): a constraint of the property is printed beside the select too, not at the top of the form.

Sealed fields (#[Vault])

Base\Database\Attribute\Vault seals the fields of an entity before they reach the database, with libsodium (a sealed box, through Symfony's SodiumMarshaller), and opens them when the entity is loaded. omnibase uses it for the settings typed on the back office's "API keys" page (Base\Entity\Layout\SettingIntl::$value); an application uses it for its own secrets:

use Base\Database\Attribute\Vault;
use Base\Database\Entity\Extension\VaultTrait;

#[ORM\Entity]
#[Vault(fields: ['apiKey'])]
class AssistantKey
{
    use VaultTrait;          // the `vault` column: null (not secured) or the environment whose key sealed the row

    #[ORM\Column(type: 'text', nullable: true)]
    protected ?string $apiKey = null;
}

$key->setSecure(true);       // sealed from the next flush on, with the running environment's key

A row is sealed when its vault column names an environment (setSecure(true), SettingBag::secure($path)); a row whose vault is null is stored as it is.

The key pair

The key is the one of Symfony's secrets vault for the environment: config/secrets/<env>/<env>.decrypt.private.php (and its public half, <env>.encrypt.public.php). One command creates both:

php bin/console secrets:generate-keys                 # the running environment (dev)
php bin/console secrets:generate-keys --env=test      # the test suite seals too
php bin/console secrets:generate-keys --env=prod

• dev and test: commit both files, as Symfony's documentation says for these environments (they protect nothing that is not in the repository already).

• prod: commit prod.encrypt.public.php only. The private key (prod.decrypt.private.php) goes to the server by hand, or as the SYMFONY_DECRYPTION_SECRET environment variable:

  php -r 'echo base64_encode(require "config/secrets/prod/prod.decrypt.private.php");'
  

  #[Vault] reads the file first, then that variable. Losing the private key loses every sealed value: keep a copy where the backups are not.

• In Docker, the web container mounts the project read-only: it cannot write config/secrets/. Run the command where the project is writable - the one-shot composer service - see Scaffolding a site:

  docker compose -f docker-compose.yml -f docker-compose.setup.yml run --rm --entrypoint "" composer \
      php bin/console secrets:generate-keys
  

A row remembers the environment that sealed it: a database copied from production to a development machine keeps its sealed values unreadable there (they come back as the sealed text), which is the point.

Without the key pair: refused, not stored in clear

When a secured field is about to be written and the vault has no key pair, the flush fails with Base\Exception\VaultKeyNotFoundException:

The "dev" vault has no key pair (…/config/secrets/dev/dev.decrypt.private.php): a secured value would be stored in clear, so it is refused. Generate the pair with "php bin/console secrets:generate-keys --env=dev" […]

The message names the vault, the file and the command, never the value. omnibase/admin's "API keys" page checks first (Vault::canSeal()) and shows the same explanation instead of saving.

Until omnibase 3.x of 2026-10-05 the value was written unsealed, without a word - a site without keys believed its API keys were encrypted. A site that wants that behaviour back says so:

# config/packages/base.yaml
base:
    vault:
        allow_plaintext: true      # no key pair: secured fields are stored in clear

Reading never fails: a value stored in clear before the keys existed is read as it is, and sealed at its next save.

What an existing site does

1. Generate the pairs (dev, test, prod) as above.
2. Open the "API keys" page and save it once: the rows stored in clear are sealed. Or, in a migration or a command: $settingBag->secure('api.stripe.secret') for each path.
3. Nothing to migrate in the schema: the vault column and the fields keep their types.

Errors and refusals

An application hands its errors to omnibase:

# config/packages/framework.yaml
framework:
    error_controller: Base\Controller\ErrorController::Main

• In debug (dev, and the test environment): Symfony's debug page (ErrorController::Rescue()), under the error's own status.
• Otherwise: exception.html.twig, or @Admin/error.html.twig for a path under /admin when omnibase/admin is installed; the kernel gives the response the error's status. exception.html.twig extends the site's layout3.html.twig, or its layout1.html.twig when it has no layout3 (until 2026-10-06 a site without layout3 could not render the page: every unknown address answered 500 in prod).

A test asserts the real status: assertResponseStatusCodeSame(403) for a refusal, 422 for a validation failure.

(The debug page used to answer 404 whatever the error, so in dev and in the tests every refusal and every validation failure of a signed-in user read as "not found". Production was right. Tests that expected 404 for a refusal expect 403 now.)

The 404 that are meant

Two refusals are answered 404 on purpose, so as not to tell that the place exists:

• While access is restricted (the base.settings.access_restriction.* settings: a site not open yet, or under maintenance), the back office and the profiler answer 404 to whoever is not granted BACKEND (Base\Subscriber\SecuritySubscriber).
• The profiler outside debug answers 404 (Base\Subscriber\ProfilerSubscriber).

An application that wants a record to stay unknown to those who may not see it (a private order, another customer's file) throws createNotFoundException() itself rather than denying access: that is its choice, record by record, not something omnibase does for it.

Deployment

This is the base deployment page. An application that deploys differently should override it by creating docs/operations/deployment.md.

Generic flow

1. Run the test suite.
2. Build assets.
3. Run migrations.
4. Warm the cache.

Cache

Warm the cache before switching traffic. Several warmers touch the database, so a cold cache on the first request after a deploy is both slow and risky.

Backups

timemachine:snapshot:backup builds one archive of the application (its code, its uploaded data and a database dump) and transfers it to one or more configured storages.

php bin/console timemachine:snapshot:backup sftp.glitchr --batch --database default

The positional argument names the destination storages, not the sources - every storage listed in config/packages/flysystem.yaml may be used, and the snapshot is written to each of them in turn.

What ends up in the archive

The tarball deliberately leaves out anything a deployment can rebuild by itself. On a typical application vendor/ and node_modules/ alone account for roughly three quarters of the tree, and none of it is data you could not reproduce with composer install and yarn.

The default exclusion list is Base\Service\TimeMachine::DEFAULT_EXCLUDES:

./vendor  ./node_modules  ./var/cache  ./var/log  ./var/coverage  ./var/phpunit  ./.git

Override it per application when the defaults do not fit:

# config/packages/base.yaml
base:
    time_machine:
        excludes:
            - ./vendor
            - ./node_modules
            - ./var/cache
            - ./public/build

Restoring a snapshot built with these defaults therefore needs composer install (and a front-end build) before the application boots. Everything that is not reproducible - uploads, the database dump - is always archived.

Where the archive is staged

The snapshot is assembled on local disk before being transferred, by default under the kernel cache directory. On a host where the application shares a filesystem with everything else, a large snapshot can therefore fill the disk the application itself is running on.

Point the staging directory at another volume when that is a risk:

base:
    time_machine:
        snapshot_dir: /mnt/storage/snapshots

Before building anything, the command measures the source (with the exclusions applied) and refuses to start when the target filesystem cannot hold roughly twice that - the tarball and its compressed copy exist side by side while compressing:

Not enough free space to build the snapshot in "/srv/app/var/cache/prod":
~2.6GB needed (source ~1.2GB x2.2), only 900MB available.

Retention

Snapshots older than time_machine.time_limit (default +30 days) are deleted from the destination storage at the start of every run, and max_cycle bounds how many same-day cycles are kept. A destination is therefore not an archive of record: it is a rotating window. Keep anything that must outlive that window somewhere the command does not prune.

The Docker harness

docker/ builds this checkout into one Symfony application with every omnibase/* plugin (admin, marketplace, forge, forum, mailbox, docs), paying through glitchr/omnitrade, shipping through glitchr/omnibus and signing through glitchr/omnisign (a DocuSeal gateway, its recorded answers in the tests), on SQLite. It is where the bundles' suites run: there is no PHP on the host.

cd docker
docker compose -f compose.yml -f compose.checkouts.yml run --rm omnibase test              # omniscient/omnibase's suite
docker compose -f compose.yml -f compose.checkouts.yml run --rm omnibase test admin        # a plugin's: admin, marketplace, forge...
docker compose -f compose.yml -f compose.checkouts.yml run --rm omnibase test forge --filter License
docker compose -f compose.yml -f compose.checkouts.yml run --rm omnibase check             # container and templates linted
docker compose -f compose.yml -f compose.checkouts.yml run --rm omnibase bare              # the Fondation loaded without the framework
docker compose -f compose.yml -f compose.checkouts.yml up                                  # the demo, http://localhost:8000/

compose.checkouts.yml mounts the checkouts beside this one (../admin, ../marketplace...) over the installed packages: what is edited is what runs, no rebuild needed. Without it, the plugins are the Packagist ones.

omnibase/blog and omnibase/classroom are not installed by the image; the overlay mounts their checkouts too (test blog, test classroom). Their tests' bootstrap registers their classes (and the omnibase/* bundles they require, read beside them), and the demo's config/bundles.php and config/routes/plugins.php - mounted as checked out, with demo.sh - register their bundles and their pages for their own suites only: the other suites' map the same entities as before.

What test sets up

• The test environment. APP_ENV=test; PHPUnit starts from tests/harness.php, which loads .env then .env.test (as an application's own tests/bootstrap.php does), then the suite's own bootstrap (it registers the suite's test namespace). docker/app/.env.test holds test values for every variable the bundles' configuration reads: KERNEL_CLASS, DATABASE_URL, DEFAULT_URI, CORS_ALLOW_ORIGIN, GOOGLE_RECAPTCHA_SITE_KEY / GOOGLE_RECAPTCHA_SECRET (Google's public test keys), MAILER_DSN, MAILER_CONTACT, MESSENGER_TRANSPORT_DSN, the Stripe keys (empty). A suite that dies before its first test on a missing variable wants a line there.
• A fresh database. var/test.db (SQLite) is deleted, and its schema created from every mapped entity, at each run; the test container cache (var/cache/test) too - first, before the bundles' public files are linked: the previous suite's container may list bundles this one has not.

The suites that need a host application (KernelTestCase: core's analytics, admin's widgets, the forge's entities) run here as they do inside an application. Those that need rows to look at skip when the fresh database has none.

The Fondation: bare

tests/Fondation.php lists the classes of the core that load without the framework, sorted. tests/BareTest.php, part of the suite, runs docker/bin/bare in a PHP process of its own: Composer's autoloader alone - no kernel, no container, no bundle booted - then each class of the list, and every class, interface, trait and file PHP loaded on the way is checked. None may be the framework's: the Symfony bundles (FrameworkBundle, DoctrineBundle, TwigBundle, SecurityBundle, every *-bundle) and bridges, dependency-injection, config, http-kernel, http-foundation, routing, security-*, form, console, ux-*, API Platform, HWI, Scheb, Webauthn's bundle, Nelmio (a namespace segment ending in Bundle is a bundle's, except symfony/intl's resource readers, Symfony\Component\Intl\Data\Bundle\). The standalone Symfony components (string, uid, intl, translation, validator, serializer, mime, mailer, notifier, cache, workflow, event-dispatcher, http-client, the contracts...), Doctrine (storage) and Twig (the view) are allowed. A failure names the framework's class or file, the class of the list that loaded it and the class that asked for it. A second case loads Base\BaseBundle and Base\Repository\UserRepository the same way and checks the report names the framework (HttpKernel\Bundle\Bundle, asked by AbstractBaseBundle; Security's UserProviderInterface, implemented by the users' repository): the check is not blind. A third loads a repository (ThreadRepository): doctrine/orm's EntityRepository, nothing of the framework (plan "omnibase agnostique", C3b).

docker compose run --rm omnibase bare                      # the Fondation; exits 1 when the framework was loaded
docker compose run --rm omnibase bare 'Base\Entity\User'    # the classes named
docker compose run --rm omnibase bare --all --each         # every class of src/, each in a process of its own: those that can join
docker compose run --rm omnibase bare --json               # the whole report
docker compose run --rm omnibase bare --names              # informative: the classes of the Fondation that name the framework
docker compose run --rm omnibase bare vendor/omniscient/omnibase/tests/Contract/runtime-without-framework.php   # a script, with the autoloader alone

What is checked is what loading a class loads - its parents, interfaces, traits, what its file runs - not what its methods do when called: an attribute's class, a type in a signature and a new in a method body load nothing until they run. Composer's autoloader itself includes api-platform/jsonld's HydraContext.php (a constant, a files entry) before any class: it is reported, not held against one.

A script given in place of a class (a path ending in .php) is run the same way, with the autoloader alone, and what it returns is in the --json report: BareTest runs tests/Contract/runtime-without-framework.php so, the contracts of the Fondation used without the framework (see The contracts of the Fondation).

The list only grows. A class enters it when it loads without the framework (bare --all --each); a class leaves it only by a decision written down in the plan "omnibase agnostique" and in CHANGELOG.md. On 2026-10-17 it held 599 of the 895 classes of src/; 691 of 908 after step C4; 694 of 911 after steps C3e and C3f; 718 of 921 after step C6 (the Doctrine mapping's bridge, and the services of omnibase's own caches, AbstractLocalCacheInterface no longer extending HttpKernel's WarmableInterface). The bare command is demo.sh's: an image built before it has the script only, docker compose run --rm omnibase php vendor/omniscient/omnibase/docker/bin/bare.

The names report: bare --names

A second report, informative, not a guard: which classes still name the framework, where loading them loads none of it (a type in a signature, a new in a method, an attribute). Nothing is loaded; each file of src/ is read, its use lines (grouped ones expanded, use function and use const too) and its fully qualified names. Two counts: the classes that name the framework themselves (●), and those that name it through the Base\ classes they name, followed to the end (○, with the chain). It is the dashboard of the seams (C3-C5): the Fondation only grows, this report only falls. --all reads every class of src/, a list of classes reads those; --json gives the whole report. On 2026-10-18 (after C4): of the 691 classes of the Fondation, 133 name the framework themselves (131 of the 679 before it, the two more are Symfony adapters), 420 themselves or through a Base\ name. After C3e and C3f: of 694, 129 name it themselves (128 of the classes of before, and Notification's Symfony half), 410 themselves or through a Base\ name. After C6: of 718, 134 name it themselves (the 129, and five of the services that joined: the AttributeReader and the ClassMetadataManipulator - form types in a method -, the Localizer, the Themizer, WebpackTagRenderer), 422 themselves or through a Base\ name.

doctrine/orm as released

The image's doctrine/orm is patched by glitchr/base-plugin while the plugin of its layer is one of before step C6 (bc3ef78 leaves it as published for this core: extra.base-plugin.doctrine/orm: false). To run the suites on doctrine/orm exactly as released, mount its release's src/ over the installed one:

git clone --depth 1 --branch 3.7.5 https://github.com/doctrine/orm.git /tmp/orm
docker compose -f compose.yml -f compose.checkouts.yml run --rm -v /tmp/orm/src:/srv/demo/vendor/doctrine/orm/src:ro omnibase test

(docker compose run --rm omnibase composer show doctrine/orm names the installed version.) See The Doctrine mapping.

SQLite

The harness's database is SQLite; the applications run MySQL/MariaDB. Code that writes SQL by hand says so per platform: the analytics counters (Base\Repository\Analytics\*) upsert with ON DUPLICATE KEY UPDATE / INSERT IGNORE on MySQL and ON CONFLICT elsewhere (VisitRepository::insertIgnore()), and count distinct pairs over a SELECT DISTINCT subquery rather than MySQL's COUNT(DISTINCT a, b, c).

Rebuilding the image

The image installs the plugins and the sibling families from Packagist, their development branches (glitchr/omnitrade 1.x with its catalogue, omnitrade/stripe, glitchr/omnibus 2.x and two carriers). Docker keeps that layer until this checkout changes; to fetch the families' latest commits:

docker compose -f compose.yml -f compose.checkouts.yml build --build-arg OMNI_REFRESH=$(date +%s) omnibase

The same goes for the core's own dependencies on their development branches (omnibridge/doctrine, omnibridge/twig, 1.x-dev): an image built before a commit of theirs that the core needs keeps the older one. Rebuild with OMNI_REFRESH rather than mounting a checkout over vendor/; the image of 2026-10-18 has omnibridge/doctrine cf6b3b9 (the UTC types the core extends), and the suite runs on it without a mount.

docker/app/ (configuration, .env.test, tests/harness.php) is copied into the image: a change there needs a build too.

Shared bricks

What several sites need and used to copy, written once in omniscient/omnibase. An application or an omnibase/* bundle uses these; it does not keep a copy.

Installation

Nothing to enable: the services are registered by the bundle (config/services/commons.php), the entities mapped with the others. A site that updates omniscient/omnibase gets these tables on its next migration (hoursWeekDay, hoursSpecialDay, hoursScopedWeek, threadComment, layoutTextOverride, layoutRedirection):

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Their names differ from the copies some sites kept (weekDayHours, specialDay, blog_comment, textOverride): a site that has not moved yet is not disturbed, and moving is a RENAME TABLE (or, for the blog's comments, an INSERT … SELECT) in the migration that drops its copy. See Scaffolding a site for what a new site copies.

Configuration

# config/packages/base.yaml
base:
    opening_hours:
        timezone: Europe/Paris       # the hours are given in it
        cutoff: '18:00'              # past it, orderDay() is the next open day (null: the day's last closing)
        week:                        # until a week is saved in hoursWeekDay
            3: [['09:00', '13:00'], ['16:30', '19:00']]
            6: [['09:00', '18:00']]
    local_business:                  # see LocalBusiness JSON-LD
        address: { street: '1 rue Lindebuckel', postal_code: '67300', locality: Schiltigheim, country: FR }
    comments:
        min_delay: 4                 # seconds: a form sent faster is a robot
        flood_interval: 60           # seconds between two comments from one address
    download_links:
        ttl: 600                     # seconds a signed link stays valid

Opening hours

Base\Service\OpeningHours says when the place is open: the usual week (Base\Entity\Hours\WeekDayHours, one row per ISO day, else base.opening_hours.week) and the days off it (Base\Entity\Hours\SpecialDay: closed, or open at other hours, for one day or a run of days).

public function __construct(private OpeningHours $hours) {}

$this->hours->isOpenAt();                    // now, in base.opening_hours.timezone
$this->hours->hoursOn($day);                 // [['09:00', '13:00'], ['16:30', '19:00']], special days included
$this->hours->orderDay();                    // the day an order made now is for
$this->hours->slots($day, step: 30);         // ['12:00-12:30', ...] not before now + 30 min
$this->hours->summary();                     // the footer's lines: days in a row with the same hours together
$this->hours->notices(days: 14);             // special days to announce

Saving the week and a day off:

$weekDays->save([3 => [['09:00', '13:00']], 6 => [['09:00', '18:00']]]); // WeekDayHoursRepository
$em->persist((new SpecialDay(new \DateTime('2026-12-24'), new \DateTime('2026-12-26'), 'Noël')));

In a template, opening_hours() is the service:

{% for line in opening_hours().summary() %}…{% endfor %}
{{ local_business_jsonld() }}

schema() gives schema.org's openingHoursSpecification and specialOpeningHoursSpecification (a closed day opens and closes at 00:00): Google reads the days off from there. local_business_jsonld() prints them with the business's name, address and phone: LocalBusiness JSON-LD.

The week and the days off are edited in the back office (omnibase/admin's "Opening hours" screen, /admin/hours).

Several places

A site with one place needs nothing more. With several (shops, practices, rooms), each place is a scope: a key its owner chooses ('store:12'), or an entity (OpeningHours::scopeOf($store) is its class and id).

$hours = $this->hours->for($store);          // or ->for('store:12'): the same service, for that place
$hours->isOpenAt(); $hours->hoursOn($day); $hours->schema(); // ... every method above

$scopedWeeks->save('store:12', [1 => [['08:00', '12:00']]]);  // ScopedWeekRepository: the place's own week
$scopedWeeks->forget('store:12');                             // back to the site's
$em->persist(new SpecialDay($from, $until, 'Travaux', 'store:12'));

{% for line in opening_hours(store).summary() %}…{% endfor %}

• The week: the place's own (Base\Entity\Hours\ScopedWeek, one row per place) when it has one, else the site's.
• The special days: the place's own and the site's; on a date both cover, the place's wins (a shop open on a day the company is closed).
• The injected service and opening_hours() without an argument stay the whole site's: for() returns a new instance.

An update of omniscient/omnibase adds the table hoursScopedWeek and a nullable scope column (indexed) to hoursSpecialDay; hoursWeekDay is untouched.

Tests and a change made in the same request: withWeek([...]) and withSpecialDays([...]) replace what would be read from the database.

Calendar

Base\Service\Calendar\Ics writes iCalendar files (RFC 5545: CRLF, lines folded at 75 octets without cutting a character, escaped texts, a VTIMEZONE for each timezone used, whole days as dates) and GoogleCalendarLink the "add to Google Calendar" link. Both read a CalendarEntry, so any date of any bundle can be written: map your entity to one.

use Base\Service\Calendar\CalendarEntry;

$entry = new CalendarEntry(
    uid: $appointment->getId().'@'.$host,
    title: 'Consultation',
    start: $appointment->getStartsAt(),          // in the timezone it happens in
    end: $appointment->getEndsAt(),              // null: start + defaultDuration (PT2H)
    description: "Bring your card\nSecond floor",
    location: '12 rue de la Paix, Paris',
    url: $urls->generate('app_appointment', [...], UrlGeneratorInterface::ABSOLUTE_URL),
    cancelled: $appointment->isCancelled(),
);

return new Response($ics->calendar([$entry], 'Mes rendez-vous'), 200, ['Content-Type' => 'text/calendar; charset=utf-8']);
$link = $google->for($entry);

Ics::escape(), Ics::fold() and Ics::unfold() are public for whoever writes or reads a line by hand. omnibase/agenda maps its Event through Event::toCalendarEntry().

LocalBusiness JSON-LD

schema.org's LocalBusiness for a page: who the business is, where, how to reach it, when it is open. Search engines read the address, the phone and the hours - the days off too - from there.

{# in the layout's <head>, or on the contact page #}
{{ local_business_jsonld() }}

<script type="application/ld+json">{"@context":"https://schema.org","@type":"LocalBusiness","@id":"https://soifdepub.com/#business","name":"PANO Strasbourg","url":"https://soifdepub.com/","telephone":"03 55 40 13 81","address":{"@type":"PostalAddress","streetAddress":"1 rue Lindebuckel","postalCode":"67300","addressLocality":"Schiltigheim","addressCountry":"FR"},"openingHoursSpecification":[…],"specialOpeningHoursSpecification":[…]}</script>

Where each property comes from

In this order: what the template gives, the back office's settings, the configuration. A property nobody gives is left out.

# config/packages/base.yaml
base:
    local_business:
        type: LocalBusiness
        image: assets/ico/android-chrome-512x512.png
        address: { street: '1 rue Lindebuckel', postal_code: '67300', locality: Schiltigheim, country: FR }
        geo: { latitude: 48.6071, longitude: 7.7399 }
        same_as: ['https://www.facebook.com/panostrasbourg/', 'https://www.instagram.com/pano_strasbourg']
        area_served: [Strasbourg, Schiltigheim, Bas-Rhin]
        extra:
            parentOrganization: { '@type': Organization, name: PANO, url: 'https://pano-group.com' }

omnibase/admin's settings page has the phone and the address (BusinessSettingsSection): what is typed there wins over the configuration.

In a template

{{ local_business_jsonld({priceRange: '€€', servesCuisine: 'Japanese'}) }}   {# properties of the page's own; null removes one #}
{{ local_business_jsonld({name: store.name}, store) }}                       {# one place: its own hours (OpeningHours::for()) #}
{% set business = local_business() %}                                        {# the properties, to put in a graph of the page's own #}

The script is printed as it is (<, > and & are escaped inside the JSON: a title cannot close the script). In PHP: Base\Service\LocalBusiness::schema() and jsonLd().

Invitations

Nobody signs up, someone is invited: a random token (48 hexadecimal characters) is sent by e-mail and never stored - only its SHA-256 is kept. Its link, before it runs out, creates the account (the link proved the address) or attaches the existing one.

• Base\Entity\User\Invitation: a mapped superclass (e-mail, name, tokenHash, createdAt, expiresAt, acceptedAt, invitedBy). Each bundle keeps its own table and says what an invitation opens.
• Base\Service\Invitations: token(), hash(), expiry($days), save(), findOpen($class, $token), markAccepted(), createUser(), existingUser().

#[ORM\Entity]
#[ORM\Table(name: 'office_invitation')]
class Invitation extends \Base\Entity\User\Invitation
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column] private ?int $id = null;
    #[ORM\ManyToOne] private Practice $practice;
    public function getId(): ?int { return $this->id; }
}

$token = Invitations::token();
$invitations->save(new Invitation($email, $name, Invitations::hash($token), Invitations::expiry(14)));
// mail the link with $token; on the link:
$invitation = $invitations->findOpen(Invitation::class, $token) ?? throw new GoneHttpException();

omnibase/estate extends both (its Invitation keeps estate_invitation, its Invitations opens an associate, a tenant, a contractor or a member).

Downloads and QR codes

Base\Service\DownloadLinks signs a route's absolute URL with Symfony's UriSigner for base.download_links.ttl seconds (or the TTL given). Who may download is checked when the link is handed out; the download action only checks the signature.

return $this->redirect($links->sign('forge_download_file', ['id' => $artifact->getId(), 'filename' => $artifact->getFilename(), 'license' => $license->getId()], 900));

#[Route('/telechargements/fichier/{id}/{filename}', name: 'forge_download_file')]
public function file(Request $request, ...): Response
{
    if (!$this->links->verify($request)) { throw $this->createAccessDeniedException(); }
    ...
}

omnibase/forge (artifacts) and omnibase/classroom (resources) use it.

QR codes

Base\Service\Qr\QrCode draws a code with endroid/qr-code: svg($data), dataUri($data, $size, $margin, 'svg'|'png'). In Twig: qr_code(url).

Base\Service\Qr\QrSheet lays codes out on A4 pages to print at 100 %:

#[Route('/admin/tables/qr')]
public function sheet(QrSheet $sheet): Response
{
    $items = array_map(fn (Table $t) => ['data' => $this->generateUrl('app_table', ['id' => $t->getId()], UrlGeneratorInterface::ABSOLUTE_URL), 'label' => $t->getName()], $tables);

    return new Response($sheet->render($items, 'L7160', 'Tables', skip: 2)); // the first two labels already used
}

pages() gives the positions without rendering, for a template of your own. Check a layout once with a test print: label sheets of other makes differ by a millimetre or two.

Allergens

Base\Enum\Allergen lists the fourteen allergens a food business declares in the European Union (Regulation (EU) No 1169/2011, Annex II), in the Annex's order: gluten, crustaceans, eggs, fish, peanuts, soybeans, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs.

#[ORM\Column(type: 'json')]
private array $allergens = [];                       // ['gluten', 'milk']

Allergen::fromList($dish->getAllergens());            // [Allergen::GLUTEN, Allergen::MILK], in the Annex's order
Allergen::MILK->number();                             // 7
$builder->add('allergens', ChoiceType::class, ['choices' => Allergen::choices(), 'multiple' => true, 'expanded' => true, 'choice_translation_domain' => 'enums']);

{% for a in allergens %}<abbr title="{{ ('@enums.' ~ a.trans)|trans }}">{{ a.number }}</abbr>{% endfor %}

Names in the enums domain (allergen.<value>), French and English.

Comments

Base\Entity\Thread\Comment is what a visitor leaves under a thread (a blog post, a sequence, a video) - or, with no thread, in the site's visitors' book: a name, an e-mail (never shown), a site, a text, a reply to another comment (one level), the account when signed in. Table threadComment.

• States (Base\Enum\CommentState): pending, approved, spam, trash.
• Akismet: the form's model (Base\Form\Model\CommentModel) implements SpamProtectionInterface; the score decides the state (toComment($thread, $autoApprove)).
• Robots: Base\Form\Type\CommentType adds a trap field (url) and the time the form was opened (opened); Base\Service\CommentGuard::check($form, $request) answers trapped (thank it, save nothing), too_fast, flood or null (base.comments.min_delay, base.comments.flood_interval).
• Reading: Base\Repository\Thread\CommentRepository::findVisible($thread), countVisible(), findPending(), countPending().

$model = CommentModel::forUser($user);
$form = $this->createForm(CommentType::class, $model, ['signed_in' => null !== $user]);
$form->handleRequest($request);
if ($form->isSubmitted() && CommentGuard::TRAPPED === $guard->check($form, $request)) { return $this->redirect($back); }
if ($form->isSubmitted() && $form->isValid()) {
    $comment = $model->toComment($thread, autoApprove: true)->setIp($request->getClientIp());
    $em->persist($comment); $em->flush();
}

A bundle that needs more on its comments extends Comment (JOINED) with a #[DiscriminatorEntry] of its own and passes its class to toComment(). omnibase/blog is the reference user (moderation screen, notifications, Akismet reports).

Pages and texts

{% set frame = embed_url(link) %}
{% if frame and frame.src %}
    <div style="aspect-ratio: {{ frame.ratio }}"><iframe src="{{ frame.src }}" title="{{ frame.title ?? frame.provider }}" loading="lazy" allowfullscreen></iframe></div>
{% else %}
    <a href="{{ link }}">{{ link }}</a>
{% endif %}

frame is {provider, src, ratio, height, title, html, url, known} (height: a player of a fixed height across the width, SoundCloud's, has no ratio). Known providers are read from the address alone (known: true): YouTube (as youtube-nocookie.com), Vimeo, Canva, Padlet, LearningApps, Genially, Google Slides. Any other address is asked to its site through the embed/embed library (oEmbed, Open Graph, a requirement of omniscient/omnibase), cached a day per address, and only the iframe's address is kept. embed_url(link, false) never asks.

Contact form

Base\Form\Type\ContactType on Base\Form\Model\ContactModel, as it is:

$form = $this->createForm(ContactType::class, $message = new ContactModel(), ['phone' => true, 'subject' => false, 'attachments' => false, 'buttons' => false, 'trap' => true]);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
    if (!$message->isRobot()) { $mailer->send(...); }   // the trap filled: thanked, nothing sent
}

Options: phone (off), subject (on), attachments (on), buttons (submit and reset, on), trap (the off-screen website field, off). The model validates the name, the e-mail and the message.

The data-protection notice, and the box to tick

A form that collects personal data says what they are used for (GDPR, art. 13), and may ask for a box to be ticked before it is sent. One brick for every site and bundle, Base\Form\Type\PrivacyType, which ContactType adds through three options:

$form = $forms->createNamed('contact', ContactType::class, $message = new ContactModel(), [
    'phone' => true, 'subject' => false, 'attachments' => false, 'buttons' => false, 'trap' => true,
    'privacy' => '@messages.contact.privacy',              // its text links {url}, the privacy page
    'privacy_parameters' => ['url' => $this->generateUrl('app_legal')],
    'privacy_consent' => true,
]);

{{ form_row(form.message) }}
{{ form_row(form.privacy) }}   {# the notice, then the box when asked #}

Any other form - a quote request, an application, a registration - adds the same field rather than its own checkbox and sentence:

$builder->add('privacy', PrivacyType::class, [
    'notice' => '@forms.privacy.notice',   // or the bundle's key, or false
    'notice_parameters' => [],
    'consent' => true,
    'consent_label' => '@forms.privacy.consent',
    'consent_message' => 'privacy.consent_required',
]);

The field is not mapped: the model keeps the message, not the tick (read it with $form->get('privacy')->get('accept')->getData() if it must be kept). The notice is printed by omnibase's form theme (block base_privacy_row: a div.form-privacy holding p.form-privacy-notice, then the box) as HTML, since it is a translation the site wrote. The default texts exist in English and French (forms: privacy.notice, privacy.consent); a site in another language, or with other words, gives its own keys.

Pictures: |picture

<img src="{{ post.cover|picture(640) }}">   {# an upload, resized; a URL or /path as is; else public/assets/<it> #}

Texts rewritten in the back office

Base\Entity\Layout\TextOverride (table layoutTextOverride): a key, a domain, a language and the new text. Base\Translation\OverridingTranslator decorates the translator (between omnibase's and Symfony's): a rewritten key wins over translations/, ICU syntax included. The texts are cached (the application's cache.redis pool when it has one, else cache.app) and the cache is emptied when one is saved. The screen is omnibase/admin's "Textes du site" (Base\Admin\Controller\Crud\TextOverrideCrudController).

A text written in the editor: |wysiwyg

A field edited with omnibase's editor (WysiwygField, EditorJS) stores a JSON document, {"blocks": [...]}; a field edited with Quill stores HTML. |wysiwyg prints either:

{{ page.content|wysiwyg|raw }}
{{ page.content|wysiwyg({headings: 3, semantics: true, media: {storage: 'local.public'}})|raw }}
{{ page.content|wysiwyg({hydrate: false})|raw }}        {# the HTML alone #}

The blocks of an EditorJS document are rendered on the server (Base\Service\Model\Wysiwyg\EditorJsRenderer): paragraph, header, list (nested, ordered, checklist), quote, image, embed, table, code, delimiter, warning / alert, raw, link, attachment. The page reads without any script, and so does a crawler. (It used to print an empty <div data-edjs="…"> that only the editor's script could fill: a site that does not load that script on its public pages showed nothing.)

A block's text keeps the editor's inline HTML (bold, links, marks, mentions); tags outside that list, on… attributes and javascript: addresses are removed. In PHP: EditorJsRenderer::render($json) gives the HTML of a document (an e-mail, a feed, a search index).

Signatures

A document sent to be signed - a lease, a quote, a surety - for any entity of the application, through glitchr/omnisign (Yousign, DocuSign, a DocuSeal instance of one's own): signed by the provider's e-mail or in the site's own page, followed until it is over, and once completed the signed document and its evidence kept in the site's private storage.

use Omnisign\Model\{Document, Envelope as Request, Field, File, Signer};

$envelope = $signatures->send($quote, new Request(
    'Devis D-2026-042',
    [new Document('quote', new File($pdf, 'devis-D-2026-042.pdf'))],
    [new Signer('client', 'Camille Érable', 'camille@erable.example')],
    [new Field('client', 'quote', page: 1, x: 72, y: 640)],
    embedded: true,                                    // signed in the site's page, no e-mail from the provider
));
return $this->redirect($signatures->signingUrl($envelope, 'client', $returnUrl));

$signatures->refresh($envelope);                       // on the way back - the provider's webhook does it too
$signatures->signed($envelope);                        // the signed PDF, once completed
$signatures->evidence($envelope);                      // its audit trail or certificate
$signatures->of($quote);                               // the envelopes about the quote, newest first

Only with the family

glitchr/omnisign is suggested, not required. Without it nothing of this exists in a site:

• Base\Service\Signatures is not registered;
• Base\Entity\Signature\Envelope is not an entity - no signature_envelope table, nothing in the site's schema, migrations or fixtures (its fields are those of the mapped superclass AbstractEnvelope, which has no table);
• POST /signatures/{gateway}/webhook answers 404.

With it: composer require glitchr/omnisign omnisign/docuseal (or omnisign/yousign, omnisign/docusign; not on Packagist yet: the vcs repositories of omniscient/omnibase's composer.json), register Omnisign\Bridge\Symfony\OmnisignBundle, configure a gateway, then make:migration and doctrine:migrations:migrate for the table:

# config/packages/omnisign.yaml
omnisign:
    gateways:
        contracts:
            factory: docuseal
            options:
                url: '%env(DOCUSEAL_URL)%'                 # https://sign.example.org/api
                api_key: '%env(DOCUSEAL_API_KEY)%'
                webhook_secret: '%env(default::DOCUSEAL_WEBHOOK_SECRET)%'

# config/packages/base.yaml
base:
    signatures:
        gateway: contracts        # null: the only gateway configured
        storage: ~                # null: the uploads' storage (base.uploader.storage, var/storage/uploads)

What an envelope keeps

The files are read back through signed() and evidence(); a site serves them to whoever may see them, with a signed link (Base\Service\DownloadLinks) or its own access check - the storage itself is out of public/.

Following it

• refresh() asks the provider where it stands (a page the signer comes back to, a command).
• The provider's webhook: POST /signatures/{gateway}/webhook (base_signature_webhook) - its signature checked by the gateway (webhook_secret, or the provider's own key), the envelope it names asked again. A callback whose signature does not hold is answered 400.
• Events (Base\Event\SignatureEvent), dispatched once each: SIGNED when a signer signed, then COMPLETED, DECLINED, EXPIRED or CANCELED; getSubject() gives the entity it is about. The application answers there: a quote accepted, a lease in force.

#[AsEventListener(event: SignatureEvent::COMPLETED)]
public function onSigned(SignatureEvent $event): void
{
    if ($event->getSubject() instanceof Quote) { ... }
}

remind() asks the provider to remind who has not signed; cancel() withdraws it.

Tests

tests/Service/SignaturesTest.php, in the harness (which installs glitchr/omnisign and omnisign/docuseal and registers a DocuSeal gateway): a lease sent for a member, signed in the page, followed to completion, its files kept and read back, its events, the webhook's signature - DocuSeal answering as an instance of its open-source edition answered (omnisign/docuseal's recorded answers). What a provider does for real is said in each gateway's documentation.

Front end

The same on every site: the year on two lines beside the pixel monkey (it dances on hover), Source Code Pro bold 18pt/21px, linking to https://www.glitchr.io. Its stylesheet (bundles/base/css/credits.css) is linked by the partial.

{% include '@Base/partials/_credits.html.twig' %}                                   {# black #}
{% include '@Base/partials/_credits.html.twig' with {color: 'white', outline: true} %}
{% include '@Base/partials/_credits.html.twig' with {mirror: true, rule: true, site_name: 'Apfelschule'} %}

The detail line (the address, the time the page took, the site's name) fades in while the signature is pointed at or focused, and is always shown without a pointer (@media (hover: none)). Filling it differently:

{% embed '@Base/partials/_credits.html.twig' with {color: 'black'} %}
    {% block credits_detail %}{{ parent() }}<span class="ga-credits-line" lang="de">Ein Apfel am Tag</span>{% endblock %}
{% endembed %}

The signature stands against the edge the site sets it on, whether its detail is shown or not: where the detail fades in and out (@media (hover: hover)) it holds no room and overflows on its own side. It is declared on the inner side: the default (detail on the left) for a signature on the right of its footer, mirror: true (detail on the right) for one on the left - else the detail opens outwards, over the page's margin. Without a pointer the detail is always shown and part of the block.

Nothing else is customisable: neither the font nor the colours.

Base.boot()

What every site's assets/app-defer.js repeated: Sticky.ready(), StickyStops.attach() and Transparent.ready() in that order, the back office as a website-in-website. The three come from @glitchr/flowjs (one library, one module per feature; the stops measure themselves again after each navigation). Install it from npm (yarn add @glitchr/flowjs) and import only the modules the site uses: Base.boot() starts a module only if its global is there, so a site that imports the navigation alone starts the navigation alone. The core's own bundle imports none of them - in particular not Ajaxer, which a site that sends named AJAX channels imports itself (import '@glitchr/flowjs/ajaxer').

The one module the core does import is the library's sixth, the cookies: base-async brings @glitchr/flowjs/cookie (the Cookie global, with flowjs's core) to every page, see Cookies below. The core's base-async runs before a site's entries and the library keeps the first Flow loaded, so a site takes the same @glitchr/flowjs as the core (^1.3.1 in its package.json, 1.3.1 or later in its yarn.lock): an older navigation or sticky module would otherwise run on the newer core.

import '@glitchr/flowjs/navigation';   // the modules the site uses: '/sticky', '/stops', '/navigation'
import Base from '../vendor/omniscient/omnibase/assets/boot.js';

Base.boot({
    nest: ['/admin*'],                                  // default
    stops: { reach: 140, settle: 320, duration: 700 },  // StickyStops' options; true: its defaults; false: none
    viewTransitions: false,
    exceptions: ['/agenda.ics'],                        // after /_*, /login*, /logout*, /register*, /locale/*, /connect/*
    current: '.site-nav a',                             // aria-current="page" follows the page
    transparent: { exit_duration: 380 },                // anything else for Transparent.ready(); false: not started
    sticky: false,                                      // Sticky.ready()'s options; false: not started
});

It also makes jQuery's closestScrollable safe, keeps the <style> blocks scripts inject into <head> across swaps (data-headlock), and sends a site page that lands inside the nest frame to the main window. The routes that open in the nest answer X-Transparent-Nest (omnibase/admin's NestHeaderSubscriber: every page under /admin, and any route with defaults: ['_nest' => true]).

media:play: one thing sounds at a time

A page may hold several players - the audio bar of omnibase/music, the video player of omnibase/video, a film in its card, a third-party embed, a plain <audio>. They share nothing but this contract:

1. a player that starts sounding dispatches media:play on document, with detail: { player, kind?, id?, … } - player is any object that is this player and no other;
2. a player that hears media:play from another player pauses itself.

No queue, no common state, no interface to implement: each player keeps its own. media.js (no dependency) is those two lines written once:

<script src="{{ asset('bundles/base/js/media.js') }}" defer></script>

import '../vendor/omniscient/omnibase/assets/media/media.js';     // bundled: the same script, window.MediaPlay

const leave = MediaPlay.join(player, () => player.pause());      // 2. paused when another starts
MediaPlay.announce(player, { kind: 'audio', id: track.id });     // 1. when this one starts
leave();                                                         // the player is destroyed
MediaPlay.current;                                               // the player that sounded last, or null

A script that does not load media.js takes part with the event alone:

document.dispatchEvent(new CustomEvent('media:play', { detail: { player: me } }));
document.addEventListener('media:play', (event) => { if (event.detail.player !== me) pause(); });

Plain elements need nothing. An <audio> or a <video> that starts with its sound on announces itself (detail.player is the element, kind its tag), and is paused when another player starts. A muted one - a hero's silent loop, a preview on hover - neither announces nor is paused; unmuted while playing, it announces itself then. data-media-play="off" on an element, or on anything around it, leaves it out (a sound effect; an element driven by a player that calls announce() itself).

A third-party player that cannot be paused (an embed without an API) is removed, or its frame reloaded, by the function given to join(); a player whose pause fails does not keep the others from pausing.

Stimulus poll

Ask a JSON address every few seconds and react when a value grows - a kitchen board, a queue.

// assets/bootstrap.js
import Poll from '../vendor/omniscient/omnibase/assets/controllers/poll_controller.js';
app.register('poll', Poll);

<div data-controller="poll" data-poll-url-value="{{ path('app_kitchen_state') }}"
     data-poll-key-value="latest" data-poll-since-value="{{ latest }}"
     data-poll-chime-value="true" data-poll-awake-value="true"
     data-action="poll:change->board#show">
    <button data-action="poll#arm">Activer les alertes</button>
    <button data-action="poll#silence">Vu</button>
</div>

The answer must hold the compared field ({"latest": 42, ...}). On a larger value: poll:change (detail: the answer), the class is-ringing, and with chime three notes every two seconds until poll#silence. arm() is the touch browsers ask before a page may make sound; it also keeps the screen on (awake). A hidden page is not polled.

Nothing from elsewhere

A page of a site loads its scripts, stylesheets and fonts from the site itself: no CDN sees the visitor (tests/Http/NothingFromElsewhereHttpTest reads the contact page of the harness - which links base and form as a site's layout does - and what its files pull in).

The editor's code blocks (editorjs-code-highlight) are coloured by highlight.js's default theme. The package's own bundle @imports it from cdnjs.cloudflare.com, and injects it with its styles on every page the editor's script is on - every page with a form. That @import is dropped at build (assets/loaders/no-remote-import.js); the theme is the bundle's copy, bundles/base/css/highlight.js/default.css (highlight.js 11.6.0, BSD 3-Clause, its licence beside it as LICENSE.txt), linked by the editor's script once, and only on a page that shows an editor or a block of code.

The emoji picker (EmojiPickerType, entry form.emoji, picmo) fetched its emojis and their labels from jsDelivr. They are the bundle's copy: bundles/base/emoji/<locale>/data.json and messages.json (emojibase-data 17.0.0, MIT, its licence beside them as LICENSE.txt), in English, French, German and Japanese - the page's <html lang> picks, English otherwise. form-type-emoji.js fetches them on the first click on a field and gives them to the picker, which then fetches nothing; what remains of picmo's own fetching is pointed at the same copy at build (assets/loaders/local-emoji-data.js). The harness's /fields carries one.

The JavaScript dependencies

yarn.lock names every package the bundles are built from, and make assets installs those alone (yarn install --frozen-lockfile): from a clean copy it rebuilds bundles/base byte-identical to what is committed. To take newer packages: ALLOW_ASSETS_UPDATE=1 make assets, then commit the lock with the bundles it built. Node 24 or later (select2's engines).

Cookies

base-async imports @glitchr/flowjs/cookie: the Cookie global on every page (Cookie.set(group, name, value, expires), Cookie.get(), Cookie.cookies, Cookie.local, Cookie.session, Cookie.use(), see the library's docs/cookie.md). It replaces @glitchr/cookie, whose methods and localStorage keys (cookie/<GROUP>) it keeps: a site drops @glitchr/cookie from its package.json and, if it imported it itself, imports nothing in its place.

What is written goes through it, so that the visitor's answer decides (omnibase/consent declares the categories and shows the panel; without that bundle a group is written until Cookie.setConsent(false, group) refuses it):

| USER/LAST_VISIT | the server, when a template asks app.site.is_newcomer() - not for a visitor who refused USER (Base\Security\CookieAnswer::refused('USER') reads the answer the script keeps in the cookie cookie-consent) | USER |

The server reads the others and writes none of them: User::getCookie('timezone') is LOCATION/TIMEZONE, else USER/INFO's; getCookie('country') is read from that zone. A script of a site writes its own the same way (Cookie.set('USER', 'THEME/MODE', mode, ...), or Consent.cookie(group, name, value, expires)), never with document.cookie: what is written behind Cookie is neither kept from being written after a refusal nor known to the detailed section.

Redirections

The addresses a site no longer answers, and where they lead now: the pages of a site taken over (/produit/enseigne-lumineuse/ → /savoir-faire/enseigne), a page renamed. One row each in Base\Entity\Layout\Redirection (table layoutRedirection), written in the back office (omnibase/admin's "Redirections" screen), by fixtures or by an import.

public function __construct(private Redirections $redirections) {}   // Base\Service\Redirections

$this->redirections->add('/produit/enseigne-lumineuse/', '/savoir-faire/enseigne');          // 301
$this->redirections->add('/soldes', '/boutique', Redirection::TEMPORARY);                    // 302
$this->redirections->add('/?p=123', '/actualites/ouverture');                                // a WordPress address
$this->redirections->add('/categorie-produit/*', '/savoir-faire/*');                         // everything beneath
$this->redirections->add('/charte', 'https://pano-group.com/charte', flush: false);          // another site; flushed by the caller

When

Only when a request ends in "not found" - no route matched, or a controller found no record (Base\Subscriber\RedirectionSubscriber, on the kernel's exception). A page the site answers is never redirected, whatever the table says, and costs no query. GET and HEAD only: a form sent to an old address is not replayed elsewhere.

Which

A source is stored as its path (Redirection::normalize(): no host, no trailing slash, no fragment), so a whole address pasted from the old site is fine. The one written for the address with its query comes first, then the one for its path, then the longest prefix.

The case of an exact source is the database's to judge: with MySQL's default collation /Produit/Enseigne is /produit/enseigne and is redirected (the row was found, then refused for its case: the address answered 404); on a case-sensitive database (SQLite, a _bin collation) only the same letters match. A prefix (/categorie-produit/*) is compared letter for letter everywhere.

The target is a path of the site or a whole address. When the source has no query and the target none either, the visitor's query follows (?utm_source=…).

What it keeps

status (301 by default: search engines move what they know of the old address to the new one; 302 for a detour that will not last), enabled, hits and lastHitAt (counted at each redirection, in UTC): the back office shows which old addresses are still visited, and which can go.

A site that updates omniscient/omnibase gets the table on its next migration. Until then nothing is redirected and nothing fails.

PDF responses

Base\Response\PdfResponse answers an HTML page as a PDF: an invoice, a rent receipt, a quote. It renders with Dompdf, a suggested package - omnibase does not require it:

composer require dompdf/dompdf

Without it, PdfResponse throws a LogicException that says so (Try running "composer require dompdf/dompdf"), where PHP used to stop on Class "Dompdf\Dompdf" not found.

use Base\Response\PdfResponse;

return new PdfResponse($this->renderView('invoice.pdf.twig', ['order' => $order]));

return new PdfResponse($html, 200, [
    'filename' => 'facture-2026-041.pdf',
    'stream' => ['Attachment' => true],            // downloaded, not shown in the browser
    'options' => ['defaultPaperSize' => 'a4'],     // Dompdf's options
    'Cache-Control' => 'private, no-store',        // anything else is a header
]);

$pdf = PdfResponse::render($html);                 // the PDF as a string: an e-mail attachment, a file to keep

The PDF is the response's content

The PDF is in getContent(), with Content-Type: application/pdf and a Content-Disposition; the kernel sends it like any response. (It used to be sent by Dompdf's stream() from the constructor: headers and bytes went out before the kernel answered, a test could not read the response, a listener could not touch it.)

Remote resources are off

isRemoteEnabled is false by default: an <img>, a stylesheet or a font at an http(s) address is not fetched, and is left out of the PDF. The page often carries what a visitor typed (a name, an address, a message), and fetching what it names from the server is a request forgery (SSRF).

• images: embed them, <img src="{{ logo|embed_base64 }}">;
• styles: in a <style> of the page; fonts: Dompdf's own (DejaVu, Helvetica, Times) or files installed with Dompdf's font loader;
• a page that names only addresses you wrote yourself may turn it back on: ['options' => ['isRemoteEnabled' => true]].

A template that linked a web font (<link href="https://fonts.googleapis.com/…">) now prints in the fallback font until it does one of the above.

E-mails

omnibase's frame

@Base/notifier/email.html.twig is the frame of omnibase's e-mails (Inky, styles inlined). A notification renders it with its own context; a plain TemplatedEmail extends it and gives nothing but its blocks:

{# templates/email/appointment.html.twig #}
{% extends '@Base/notifier/email.html.twig' %}
{% block subject %}{{ 'booking.email.subject'|trans({date: date}) }}{% endblock %}
{% block content %}<p>{{ 'booking.email.lead'|trans }}</p>{% endblock %}

$mailer->send((new TemplatedEmail())
    ->to($client->getEmail())
    ->htmlTemplate('email/appointment.html.twig')
    ->context(['date' => $date]));

• Every variable has a default: importance, markdown, raw, content, action_url, action_text, exception, footer_text. (The frame used to stop on "Variable importance does not exist" outside a notification.)
• Blocks: subject, title, style, header, lead, content, action, exception, footer, footer_content.
• The logo is optional: the header block prints one only when there is one - the logo variable of the context, else the back office's setting (base.settings.logo.email, then base.settings.logo). A site without a logo sends its e-mails without one.

A site with its own frame (templates/email.html.twig, as the scaffold copies) keeps it: omnibase's own templates extend email.html.twig, which is the site's when it has one.

The subject is written in the template

{% block subject %} of a TemplatedEmail's template is the message's subject (Base\Subscriber\TemplatedEmailSubjectSubscriber, before the body is rendered): rendered with the e-mail's context, tags removed, entities decoded. It was only printed in the body, and the message left without a subject.

A subject set in PHP wins - ->subject('Rappel') - and is handed to the template as the subject variable, which the frame prints as its title and lead instead of the block.

A notification and its e-mail

Base\Entity\User\Notification is what a notification is - subject, content, importance, channels, recipients, context, templates - and its sending through omnibase's notifier (send(), sendBy(), sendAdmins()). What needs Symfony is Base\Bridge\Symfony\NotificationMessages' (plan "omnibase agnostique", step C3f): the e-mail of asEmailMessage() (Twig's NotificationEmail, the uploaded attachments embedded, the HTML rendered), render()'s Response (renderHtml() is the HTML alone), and the error an ExceptionEvent or a FlattenException carries made the content. The entity's methods are those of before and answer the same; it names nothing of the framework (Symfony's Notifier is a standalone component). addAttachment() takes a \SplFileInfo; the e-mail embeds the uploaded files (UploadedFile), as it did.

Sitemap

/sitemap.xml and /sitemap.txt (app_sitemap) list the pages a site wants indexed. Base\Service\Sitemapper builds the list at each request, in two passes.

Pages without a parameter: #[Sitemap]

use Base\Attributes\Attribute\Sitemap;

#[Route('/agenda', name: 'agenda_index')]
#[Sitemap(priority: 0.8, changefreq: 'weekly')]
public function index(): Response

Every route whose action carries the attribute is listed (registerAttributes()), once per locale. A route with a parameter is listed too when its requirement spells its values out ({extension} with xml|txt): one page per value.

Pages of records: SitemapEvent

A route open to any slug or id is the application's - or the bundle's - to enumerate, from a listener:

#[AsEventListener(event: SitemapEvent::BUILD)]
final class SitemapListener
{
    public function __invoke(SitemapEvent $event): void
    {
        foreach ($this->posts->findAllPublished() as $post) {
            $event->getSitemapper()->register('blog_post', ['slug' => $post->getSlug()], $post->getUpdatedAt()?->format('c'));
        }
    }
}

The route's action still carries #[Sitemap]: the attribute says the page belongs in the sitemap, with which priority; the listener says which pages there are. registerUrl('/blog/petit-cours') does the same from an address.

A page that cannot be listed is left out, never fatal

register() and registerUrl() do not throw. A page is left out, and the reason logged once per request (warning, Sitemap: page left out, ...), when:

• the route does not exist;
• the address, parameters filled in, matches no route;
• the route's action carries no #[Sitemap] - no #[Sitemap] on "App\Controller\BlogController::post" (route "blog_post").

The last one used to throw SitemapNotFoundException: a listener registering a route nobody had declared put the whole /sitemap.xml - every other page with it - in 500. The fix is still to add the attribute; the log says where. A route whose controller is given as an array ([Controller::class, 'method']) or a closure is read without failing as well.

The attributes of a class are read once and kept with the container's cache (var/cache/<env>/pools/simple/, Base\Attributes\AttributeReader): a #[Sitemap] just added is not seen until that cache is rebuilt. When the page stays out after a cache:clear, delete var/cache/<env> and warm it again.

The router's scheme is the request's

Until 2026-10-17 AdvancedRouter::getScheme() read

$use_https ??= $_SERVER["REQUEST_SCHEME"] ?? true;
return $use_https ? "https" : "http";

so it answered https whatever the request: REQUEST_SCHEME is a string, and "http" is as true as "https". Only an empty REQUEST_SCHEME (or "0") gave http. It now answers the scheme of the request being handled.

What it answers

• A request on the stack: get_url_scheme() of the main request - Request::isSecure() (HTTPS on, or X-Forwarded-Proto: https from an address within framework.trusted_proxies), then, without HTTPS, the variables the core always read (USE_HTTPS, REQUEST_SCHEME, X-Forwarded-Proto). It is the function get_url() gives the visited address and the site's routes their scheme with (f115e368), so the router and the addresses agree.
• A web request not yet on the stack: the same function on PHP's globals.
• No request (a command, a worker, a test between two requests): https, unless the site sets HTTPS (or USE_HTTPS) to a false value (off, false, 0) in its environment. PHP's globals hold no scheme in a console, and get_url_scheme() would say http there: links written by a command keep the https they had.

What it decides

It does not decide the scheme of the addresses of the site's own routes: AdvancedUrlGenerator::resolveParameters() sets the request context's scheme from get_url(), and https when no request gives one. The visited address (get_url()) and its port (getPort(), 532f991a) follow the request too.

getScheme() decides:

• the scheme of the absolute addresses of Symfony's own routes (_profiler, _wdt, _switch_locale...), and of every route when the router's advanced features are off (AdvancedUrlGenerator::generate() replaces http:// and https:// by it);
• which declared ports the host fallbacks are filtered against (getFallbackParameters(): HTTPS_PORT on https, HTTP_PORT on http), whether a fallback port is the scheme's default (getPortFallback()), and the scheme getPort() judges by when the address has none;
• the scheme of the address a request outside the allowed IPs is sent to (RouterSubscriber), the host getUrl() strips from an address asked as a path, and app.site.scheme.

What moved

On every site served over https (all of them, behind a proxy that terminates TLS, in development and in production) nothing changes: the request is https, as the router said. Where a site is answered over plain http - the harness (http://localhost:8000), the sites' tests (http://localhost), latoucheoriginale's tests on 8081 - the router now says http:

• an address of _profiler or _wdt is http, as the page is;
• the fallbacks' ports of an http request are filtered by HTTP_PORT, as getPort() already judged the visited port: latoucheoriginale's (HTTP_PORT='[8081]', no HTTPS_PORT) is 8081, where HTTPS_PORT's [443] made it 443 and the IP restriction sent to https://localhost/;
• AdvancedUrlGenerator::generate() no longer forces an absolute address when HTTPS is on in the environment while the scheme is http. The rule never fired while the scheme was always https, and following the request it would have written every link of a site's tests (.env.test sets HTTPS=on, the client asks http://localhost) as an absolute address with the request's own scheme and host, which a path says as well. A route with a host of its own is still written whole.

How it is checked

tests/Routing/RouterSchemeTest: a plain http request is http (the router, _switch_locale and security_login absolute, a path still a path); https is https; FrankenPHP behind nginx terminating TLS (HTTPS "", REQUEST_SCHEME http, X-Forwarded-Proto: https on 8663) is https from a trusted address and http from an untrusted one; without a request it is https, http when the site sets HTTPS=off or USE_HTTPS=false; an http site on 8081 keeps its port and scheme in its fallbacks, getPort(), its links and through the kernel (200); the fallbacks' ports of a site with HTTP_PORT='[80,8094]' and HTTPS_PORT='[443,8473]' are the https ones on https and the http ones on http. Every test but the https one fails on the previous code. ForwardedHttpsUrlTest, NonDefaultPortUrlTest, AbsoluteUrlWithoutRequestTest and BasicAuthUrlHttpTest stay green, and so do the core's, omnibase/admin's and omnibase/marketplace's suites in the harness.

omnibase/marketplace's QuickOrderTest failure, once suspected of this, was its own: a Location answered to an http request compared with QuickOrder::doneUrl() made outside a request (marketplace d1d93bf).

Code that needs the scheme the visitor used may read the router's now, or the request's (get_url_scheme(), app.request.scheme): they are the same.