omnisense/omnibase

Getting started

Requirements

What composer.json requires:

The framework itself is not required by the core (since 4.0, see What the core requires): under Symfony it comes with omnibridge/symfony (FrameworkBundle, SecurityBundle, TwigBundle, DoctrineBundle, MonologBundle, Messenger, Form, 6.1 to 8). The sites run MySQL 8; the core's harness runs on SQLite. The commands doctrine:schema:charset and doctrine:array:upgrade, and the backups, are MySQL's.

Installation in a Symfony application

composer config allow-plugins.omnibridge/composer true
composer require omnisense/omnibase omnibridge/symfony

omnibridge/composer is a Composer plugin (it applies the core's patch to symfony/process): Composer asks before it runs one, hence the first line.

Register the bundle in config/bundles.php, after the bundles it works with:

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
    // ...
    Base\BaseBundle::class => ['all' => true],
];

Give it its configuration, config/packages/base.yaml - the smallest one is in the Configuration reference - and import its routes (Routes and access). Then the schema and the front end:

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

A new site is better started from an existing one: Scaffolding a site says what to copy and in which order to start it. The core's harness (The Docker harness) runs the core with every omnibase/* plugin, without a site.

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. bin/console base:mapping lists the aliases (Console commands).

Scaffolding a site

A new omnibase site starts as a copy of Apfelschule (~/Sites/apfelschule), the reference application: Symfony 8, PHP 8.4, Docker, omnisense/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 omnisense/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. They are what the back office edits (base.settings.title, base.settings.maintenance, api.spam.akismet...), read through Base\Service\SettingBag (Base\Service\SettingBagInterface).

base.parameter_bag.use_setting_bag must be on: off, the snapshot is empty and every setting reads as unset (Configuration reference).

Reading a setting

$title = $settingBag->getScalar('base.settings.title');          // 'My site', or null
$title = $settingBag->getScalar('base.settings.title', 'fr-FR'); // in that locale
$tree  = $settingBag->get('base.settings');                      // the values under the path

get() answers an array: the path's own value under _self, the values of the paths under it by their names (get('base.settings.title') is ['_self' => 'My site']). getScalar() is get($path, $locale)['_self'] ?? null. Both take a list of paths too. A value is read in the locale asked, else the default locale, else the first locale it has.

A missing setting degrades to null rather than throwing - a missing setting is a normal state during a deployment, not an error. A malformed path (_self in the middle of it) still throws.

In a template, app.settings is get('app.settings'), and the setting base.settings.maintenance puts the site under maintenance.

Writing a setting

$settingBag->set('base.settings.title', 'My site', 'en-GB');
$settingBag->set('base.settings.title', null, 'en-GB'); // removes that locale's value

set() creates the setting when it does not exist, refuses a locked one (lock(), unlock()), flushes, evicts the second-level cache and invalidates the snapshot. setLabel() and setHelp() give the back office's label and help text, secure() marks a setting as secret. has(), remove().

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.

A setting over a parameter

setBag($path, $parameterName) links a setting to a parameter of the configuration: with base.parameter_bag.use_hot_bag on, the setting's value (in the default locale) answers for that parameter before base.yaml's (getBagParameters(), laid over the parameters by HotParameters on each request and command). This is how the back office changes an option of the configuration without a deploy.

Architecture

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

• What the core requires — since 4.0 its Foundation alone (Doctrine, Twig, the standalone components); under Symfony the framework comes with omnibridge/symfony, and the bundles the core works with are suggested: What the core requires.
• Entities — Thread and its subtypes carry the shared title/slug/content model that articles, comments and pages all reuse.
• The contracts of the Foundation — 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 — the back office is a package of its own, omnibase/admin (formerly base-bundle-admin), with its own manual.
• 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.

What the core requires

Since 4.0 (branch 4.x, plan "omnibase agnostique", step C7) omnisense/omnibase requires its Foundation alone: what tests/Foundation.php loads, and what it stands on. The framework is no longer a requirement of the core: a Symfony application adds it, a Laravel application does not.

symfony/console is still installed with the core alone: doctrine/orm 3 requires it. Nothing of the Foundation loads it, which is what bare checks: "free of Symfony" reads nothing of the framework loaded, not absent from vendor.

Doctrine: the latest major, one line. The core follows each Doctrine package's current major, open upwards - doctrine/orm ^3.4, doctrine/dbal ^4.2 (omnibridge/doctrine's floors), doctrine/collections ^3.1 (which requires PHP 8.4, the core's floor), doctrine/event-manager ^2.0, doctrine/persistence ^4.0, doctrine/common ^3.0 - with no older branch kept alive, no upper bound and no pinned version; Doctrine is used as published (no patch, no fork). doctrine/dbal included (4.0, step C6b): no Composer plugin rewrites its schema managers; what omnibase needs of them goes through DBAL's own SchemaManagerFactory (Base\Bridge\Doctrine\SchemaManagerFactory, a SET column read with its values, the (DC2Type:...) comments of before left out). A new major is taken up when it comes, not maintained beside the old one.

A Symfony application

composer require omnisense/omnibase:4.0.*-dev omnibridge/symfony:1.x-dev

then the bundles its config/bundles.php registers, for an application made on omnibase's usual set:

composer require scheb/2fa league/flysystem-bundle hwi/oauth-bundle web-auth/webauthn-symfony-bundle \
    api-platform/symfony api-platform/doctrine-orm symfony/webpack-encore-bundle symfony/ux-twig-component \
    glitchr/ux-google glitchr/well-known nelmio/cors-bundle nelmio/security-bundle

An application coming from 3.x already had every one of them, through the core: requiring them itself keeps them (Composer would otherwise remove what nothing requires any more). No Flex recipe runs again for a package already locked: nothing changes in config/.

Composer: omnibridge/composer

The core requires one Composer plugin, omnibridge/composer (in place of glitchr/base-plugin until 4.0), and declares what it asks of it in its own composer.json, extra.omnibridge:

• the stubs of App\Entity, App\Enum, App\Form, App\Notifier and App\Repository - one per plain class Base\<Name>\X the application does not define in src/<Name>/, the alias AbstractBaseBundle declares at run time - by the providers Base\Bridge\Composer\Stub\*, written after every dump-autoload into vendor/composer/omnibridge/stubs/, which no autoloader reads (for an IDE; never a definition at run time; StubsTest). The providers are loaded by the engine alone, outside the Foundation;
• one patch, process-timeout-from-env on symfony/process: a Process built without a timeout waits SYMFONY_PROCESS_TIMEOUT seconds, 60 when unset.

An application allows the plugin:

"config": { "allow-plugins": { "omnibridge/composer": true } }

and checks vendor/ in its CI with composer omnibridge:patches --check (and composer omnibridge:stubs --check). composer omnibridge:patches --diff shows the patch.

Nothing else is changed in an application: its bin/console keeps its own line, use Base\Console\Application; in place of FrameworkBundle's (glitchr/base-plugin used to rewrite it at each install; a site made from the skeleton writes it once).

None required de facto

Up to step C7b two of them could not be left out; each has its fallback now, and the user class and the storages load without either:

• scheb/2fa - Base\Entity\User implements Base\Contract\SecurityUser and Base\Contract\TwoFactorUser. Where symfony/security-core and scheb/2fa are installed, they are aliases of Base\Bridge\Symfony\SecurityUser (Security's UserInterface and PasswordAuthenticatedUserInterface) and Base\Bridge\Symfony\TwoFactorUser (scheb's TOTP, e-mail, backup-code and trusted-device interfaces): under Symfony the user implements exactly what it did. Elsewhere they are empty interfaces, and the user loads without them. Installed means declared, and nothing else decides (Base\Contract\Framework::declares(), step C7c): no environment variable, no switch - a Laravel application reading a Symfony application's vendor/ gets the user with Security's interfaces, which ask nothing of it but the methods the user has. Without the bundle registered (the package installed) the interfaces are still declared: only the two-factor sign-in itself is the bundle's. Where the framework is not installed is measured on such a vendor: bare loads the Foundation with the core installed alone (composer install --no-dev, see the harness). The users' repository follows the same rule (step R2): Base\Repository\UserRepository implements Base\Contract\SecurityUserLoader and SecurityUserProvider, aliases of Base\Bridge\Symfony\SecurityUserLoader (doctrine-bridge's UserLoaderInterface) and SecurityUserProvider (Security's UserProviderInterface and PasswordUpgraderInterface) where symfony/doctrine-bridge and symfony/security-core are installed, empty interfaces elsewhere. So do the passkeys' repositories (plan "omniauth", AU1): PasskeyRepository and WebauthnUserEntityRepository implement Base\Contract\PasskeyRecords and PasskeyUsers, WebauthnBundle's interfaces where it is installed.
• league/flysystem-bundle - Base\Service\Flysystem (the flysystem service, which the file, image, upload, backup and cache-clear services read) is the core's own class, built from a PSR-11 container of storages by name: the services tagged flysystem.storage, which the bundle tags from the application's config/packages/flysystem.yaml. Without the bundle, FlysystemStoragesPass gives omnibase's local storages: local.cache (var/cache/<env>/images), local.uploads and local.wysiwyg (var/storage/...), each with its .public under public/.

The others have a fallback:

A Laravel application

Laravel does not install Symfony's framework: it requires the core and, when it exists, omnibridge/laravel, which fills the contracts (Base\Contract\Runtime, see The contracts) with Laravel's services. Doctrine stays the storage (laravel-doctrine/orm), Twig the view (omnibridge/twig). The pilot, lesringostars-laravel, does so already from a Symfony application's vendor/.

The core's own suite

require-dev holds omnibridge/symfony and the bundles the core's code names (scheb/2fa, league/flysystem-bundle, hwi/oauth-bundle, web-auth/webauthn-symfony-bundle, api-platform/symfony, symfony/webpack-encore-bundle, glitchr/ux-google), so that Dockerfile.test (composer install of the core alone) resolves what its kernel tests use. The harness's application (docker/Dockerfile) requires omnibridge/symfony and every bundle its config/bundles.php registers, as a site does.

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/Foundation.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.

Repositories behind interfaces. The code of a site and of the core asks its repositories through interfaces named by what they answer, in the namespace of their entity (audit "lesringostars face au master plan", step R15): Base\Database\Repository\Entities - what every repository answers: find(), findAll(), findBy(), findOneBy(), count(), persist(), remove(), flush() -, and one per entity: Base\Repository\Threads, Users, Thread\Tags, User\Notifications, Layout\Settings; a site adds its own beside its repositories (App\Repository\Article\Articles extends Threads). Nothing of the ORM in what they take or give back: arrays of criteria and of order (field => ASC|DESC), the entities, lists of them, integers. The Doctrine repository implements its interface, each method by the finder call it replaces (Threads::oneBySlugAndState() is cacheOneBySlugWithRouteAndState()): same query, same result cache. Under Symfony each interface is an alias of the repository service (config/services/database.php; a site's own by #[AsAlias] on its repository); under Laravel the application binds each to the repository omnibridge/laravel resolves by its class. Another persistence implements the same interfaces over the same tables (the structure: schema.md).

The finder language (cacheOneBySlug()...) stays the repositories' own: an application calls the interface's methods, never the finder through 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 Foundation

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.

The host's contracts are omnisense/omnibridge's (plan "omnibase agnostique", A2). What any host answers - addresses, translations, languages, access, sessions, tokens, stored files, routes, environment - lives in the omnibridge family's core, omnisense/omnibridge, as Omnibridge\Contract\*, with the registry itself (Omnibridge\Runtime, its MissingContractException and SystemClock). What describes omnibase's own models stays here as Base\Contract\*: Nouns, Media, Pictures, Texts, the screens' ContextProvider, the user's SecurityUser/TwoFactorUser, its repository's SecurityUserLoader/SecurityUserProvider and the passkeys' repositories' PasskeyRecords/PasskeyUsers. Base\Contract\Runtime is omnibridge's registry (the same state) with omnibase's accessors beside it: parameters(), nouns(), media(), pictures(), texts(), mailer(). The former names (Base\Contract\Urls... and omnibridge/twig's Omnibridge\Twig\Contract\Urls and Translations), aliases of the moved interfaces since A2, were removed at omnibase 4's final pass: name Omnibridge\Contract\*.

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 Foundation (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.

BaseTrait and BaseService: the application's shortcuts (step C9)

The rule: BaseTrait to go fast in an application; the contracts in the core and the bundles. Base\Traits\BaseTrait (static accessors usable from an entity, an attribute, a subscriber) and Base\Service\BaseService (its facade) are the tool for writing an application quickly, and they stay - neither is deprecated, nor removed in 5.0. The core and its bundles add no new use of either: a class of theirs asks Base\Contract\Runtime (or is given the service it needs), so that it runs where there is no Symfony.

What changed in C9:

• BaseService is a lazy service. The container hands out a ghost of the class (PHP 8.4's lazy objects, not a proxy subclass), built with its 23 services the first time one of its methods reads a property. Injected in a class that never calls it, it builds nothing.
• Nothing on a page's path injects it any more. SiteVariable and AdminVariable (app.site, app.admin) and EmailVariable read the settings from the SettingBag and the route index from the router; FormTypeBootstrapExtension the parameters; ErrorController the Environment contract (Base\Service\Model\DevelopmentEnvironment, isDevelopment()'s rule); MainController and UserSettingsController never called it. The core's getService()->isDebug(), getSalt(), isGranted(), isEntity() calls are Runtime::environment()->isDebug(), ->secret(), Runtime::access()->isGranted(), and BaseTrait's static isEntity() (the class metadata manipulator).
• What a contract answers, they ask the contract when the registry has it, so they answer outside Symfony too, and the methods below read no property of BaseService - called on the ghost, they build nothing:

The other accessors hand out the framework's services, typed as they always were (getRouter(), getTranslator(), getLocalizer(), getTwig(), getTrading(), getDoctrine(), getTokenStorage()...): no contract has their type, so they stay on the lazy base.runtime locator, one service built on its first call.

The bundles' uses (for step C8, which moves them to the contracts; nothing changed in the bundles): no bundle injects BaseService or calls getService(). Fourteen entities use BaseTrait - marketplace's Order (getTrading() x8, getTranslator() x3, getRouter(), getParameterBag()), Product (getParameterBag(), getRouter(), getTranslator(), getTwig()), Order\OrderItem (getTrading() x3), Order\Method\PaymentMethod (getParameterBag()), ShippingMethod (getParameterBag() x2), Sales\Attribute\Rule\TotalPriceAdapter (getTrading()); forum's Category (getRouter()); and, calling none of its accessors, marketplace's Sales\Discount, Fee, Sales\Attribute\Action\FixedAmountAdapter, forum's Post, mailbox's Conversation, classroom's Entitlement and Resource.

The parameters and the settings over them (step C9)

Base\Service\DottedParameterBag (Foundation) reads parameters given by their full names (base.user.active_delay => 300) by a dotted path - a path naming the values under it (base.user) gives them all. ArrayParameterBag (an array) and ParameterBag (the Symfony container's parameters, and DependencyInjection's two interfaces) read through it. has() is whether get() finds a value: a parameter set to false, 0 or "" is there, one set to null is not (it was the value's truth).

Base\Service\HotParameters (Foundation) lays the settings stored in the database - a back office's setting linked to a parameter - over any ParameterBagInterface. get() reads, in this order, by the presence of a value:

1. the $bag given to the call,
2. the settings (add(); when the overlay is on and $useHotBag is true),
3. the configuration.

A setting stored as false wins over the configuration's true; a setting whose value is null (none was typed) is no value, the configuration's is read. The overlay is on when base.parameter_bag.use_hot_bag is true; off, the configuration is read (it read nothing at all before: every parameter was null unless a $bag was given). has() reads the same sources in the same order.

Under Symfony parameter_bag is HotParameterBag, that overlay over ParameterBag as DependencyInjection's ParameterBagInterface and ContainerBagInterface; it refuses clear() and remove() as the frozen bag does, and HotParameterBagSubscriber gives it the settings on the first request or command. parameter_bag, the autowiring of Base\Service\ParameterBagInterface (which gave the plain ParameterBag, without the settings: an autowired EditorController, AttributeReader read the configuration alone), DependencyInjection's interfaces, Runtime::parameters() and BaseTrait::getParameterBag() are one object (ParameterBagServicesTest). Elsewhere: new HotParameters(new ArrayParameterBag([...]), true) and add() the settings.

Base\Service\SettingBag (the settings themselves) keeps its snapshot in a PSR-6 pool (Psr\Cache\CacheItemPoolInterface, no longer Symfony's CacheInterface); its cache warmer is Base\Bridge\Symfony\SettingBagWarmer. It is in the Foundation: Doctrine and psr/cache.

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/Foundation.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 - Symfony's adapter of the framework-free Base\Screen\Negotiation (step R10; omnibridge/laravel's Screen\Responder is Laravel's), which also answers what an action written once for every host hands back: a Template (its data in JSON too when it allows it), Json (its templates rendered), a Shell (omnibridge/react's protocol), a File, or null for no such page -, 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 Foundation (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).

What the classes read through BaseTrait, on contracts (step C4b)

What a class of the core still asked of BaseTrait's services after C3e, now asked of the registry, in the order lesringostars' pages go through it. Each move keeps the answers under Symfony (a test compares them with the service's, its old code copied as it was) and gives answers where there is no framework (tests/Contract/basetrait-seams-without-framework.php, run by BareTest). BaseTrait itself stays, its accessors' signatures unchanged, for the bundles and the sites that call them (since C9 the ones a contract answers ask it, above).

Base\Entity\User reads nothing through BaseTrait any more (it still uses it: the sites call its accessors on a user).

Where C4b stops. Left on BaseTrait, each for a reason: Notification (the notifier, Twig and the project's directory - its message half is already Bridge\Symfony, step C3f; the notifier is a Symfony service by nature), AbstractExtension::isEntity() (Doctrine's metadata, a question for Bridge/Doctrine), Uploader's AttributeReader (omnibase's own service, already in the Foundation), MediaEnhancer (the media service inside the Wysiwyg pipeline, which Texts already covers from outside), the forms, fields, controllers and validators (Symfony by nature, decision D3), and the bundles' entities (step C8).

What an entity is called: Base\Service\Model\EntityNouns. The rule of Translator::transEntity(), transEntityExists() and parseClass() (the key of a class: its name less its entity namespace, dotted, in snake case - Base\Marketplace\Entity\Order is marketplace.order; then the variants its options ask for, NounVariants, the first the "entities" catalogue holds) moved into a class of the Foundation, built on the Translations contract and the entity namespaces of the application's bundles. The translator now answers by an instance of it over itself (getEntityNouns(), the bundles BaseBundle knows), and that instance is the Nouns contract under Symfony: one rule, the same strings. A host without the framework builds one with new EntityNouns($translations, EntityNouns::namespacesOf([...its bundle classes])) and binds it to Base\Contract\Nouns.

A number of seconds in words: Base\Service\Model\Duration. Translator::transTime()'s words (base.years to base.seconds, ICU plurals; a month of 30 days) over the Translations contract (trans()). Under Symfony that is the translator chain, so a unit the team rewrote in the back office is the one printed, as before; transTime() now answers by it.

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 nothing patches doctrine/orm (since 4.0 the core declares its one patch, on symfony/process, to omnibridge/composer: extra.omnibridge).

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.'/omnisense/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).

Since step R14 the mapping driver also reads the classes' declarations rather than the attributes (omnibridge/doctrine's DeclarationDriver): the structure is described once, outside Doctrine - see schema.md.

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.

The data structure, described outside Doctrine

Marco's bridge principle (2026-10-19): the omni bridges are only the adapters of contracts for one technique, so that several persistence techniques can map the same tables - Doctrine today, Eloquent or another tomorrow - without changing the structure (the naming, the columns, the relations, the discriminators). Since step R14 of the audit "lesringostars face au master plan", that structure is described once, outside any ORM, and Doctrine reads it.

Where it lives, and why

• omnisense/omnibridge, Omnibridge\Schema (framework-free, ORM-free): the generic part. Schema\Declaration reads what the entity classes declare from their attributes by reflection, without instantiating them - the attributes are Doctrine\ORM\Mapping's, the vocabulary every omnibase entity is written in, but their classes need not exist (Vocabulary holds their parameters and defaults as data). Schema\Description is the neutral description: each Entity (table, kind, parent and root, Inheritance with its column, map and value, identifier, Fields with their portable types, Relations with their JoinColumns or JoinTable) and each Table (Columns, primary key, Indexes, ForeignKeys), plain data too (toJson()). Schema\Builder builds it from the declarations alone, the way Doctrine completes its metadata and the way its SchemaTool makes the tables; Schema\Naming (CamelCaseNaming) names what the declarations leave unnamed, including an index or a foreign key as DBAL names it. Schema\Database\MySqlSchema reads a MySQL information_schema and compares it with a description.
• omnibridge/doctrine: the Doctrine side. DeclarationDriver builds Doctrine's metadata from the declarations (wrapping the application's driver, which still says which classes exist); MetadataDescription writes what an entity manager maps in the neutral form; NamingStrategy answers Doctrine's naming strategy with the family's Naming.
• the core, Base\Database\Schema (Foundation): what is omnibase's own - the rules its listeners add to Doctrine's metadata, written once more as Omnibridge\Schema\Builder\Rules applied at the same three moments (before the declaration is read, once declared, once loaded): DiscriminatorRule (the maps generated under class names, #[DiscriminatorEntry]'s values), VaultRule (#[Vault]'s unique constraints), OrderColumnRule (#[OrderColumn]'s json column), TranslationRule (a translation's inheritance from its translatable, the translations and translatable relations, locale, <table>_unique_translation), TargetRule (the targets DoctrineBundle resolves) and ExtensionRule (extension_entity); and Describer, which builds an application's description from its entities' folders with omnibase's naming and rules.

The split follows the A1/A2 rule of the plan: generic glue for a host or a technique goes to omnibridge, what reads omnibase's own models stays in the core.

How Doctrine uses it

Under Symfony DoctrineConfigurationPass wraps every entity manager's driver in omnibridge/doctrine's DeclarationDriver, then in Base\Bridge\Doctrine\MappingDriver; Base\Bridge\Doctrine\Mapping::register() does the same on an entity manager built by hand. Doctrine thus no longer reads the attributes itself: its metadata are built from the declarations - the same source the ORM-free description is built from - and they are those its attribute driver built, to the property (MetadataSnapshot, every class, on both hosts).

use Base\Database\Schema\Describer;

$description = Describer::describe([$vendor.'/omnisense/omnibase/src/Entity', $projectDir.'/src/Entity'], ['project_dir' => $projectDir]);
$description->table('thread')->column('slug');                    // string(255), not null
$description->entity(Base\Entity\Thread::class)->relation('tags'); // many_to_many, join table thread_tags
file_put_contents('var/schema.json', $description->toJson());

The proof

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

• the entity manager's driver is the DeclarationDriver;
• the description Describer builds without any ORM is MetadataDescription's of the entity manager, entity by entity and table by table (the harness: 202 classes; lesringostars: 115), and #[DiscriminatorEntry]'s values derived without the attribute's reader are Doctrine's;
• on MySQL (lesringostars), the description is the database's own schema: every table, column (SQL type, nullable, default, auto-increment), primary key, index and foreign key read from information_schema, nothing of Doctrine asked (doctrine_migration_versions and messenger_messages apart).

How another persistence would read it

An Eloquent (or any other) bridge needs no attribute of Doctrine's and no class of the core's mapping: it reads Omnibridge\Schema\Description - built by Describer::describe() once, or read back from the JSON file it wrote - and maps from it:

• a model per Entity: $entity->table is the table, $entity->identifier the key(s), $entity->fields the attributes with the column each one is kept in (Field::$column), its portable type (string, integer, json, datetime, thread_state...: the casts), nullable, length, enum (the PHP enumeration to cast to), generated (identity: the database gives the key);
• the relations: Relation::$kind says belongsTo (many_to_one, by its joinColumns), hasMany (one_to_many, through the owning side's join column named by mappedBy), hasOne/belongsTo for one_to_one, and belongsToMany with JoinTable::$name and its joinColumns/inverseJoinColumns;
• the hierarchies: Entity::$inheritance gives the discriminator column, the map (value => class) and the entity's own value - a single-table hierarchy is a global scope on the discriminator, a joined one a model per table keyed by the root's identifier (Entity::$root, Entity::$parent);
• the tables themselves (Description::$tables) for migrations or a schema check, with the same names, types, indexes and foreign keys as Doctrine's.

Nothing of it needs Doctrine installed: omnisense/omnibridge requires PHP and three PSR interfaces, and its BareTest proves the Schema loads with nothing else. The Eloquent bridge itself is a later step; this one gives it what to read.

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

Or keep the site's delay and move the clock rather than wait: the guard reads the time from the clock (Symfony's clock, else Base\Contract\Runtime::clock()), never time(); the core's HTTP tests use Tests\Base\Http\MovesTheClockTrait (takeTheTimeAPersonTakes() between reading the form and sending it, putTheClockBack() in tearDown()).

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.

Under omniauth (Base\Auth\)

With omnisense/omniauth installed (the core suggests it, its identity providers included, and its method packages omniauth/webauthn and omniauth/otp - formerly omniauth/passkey and omniauth/totp; Google is omniauth/google), Base\Auth\ fills its contracts on omnibase's own tables - the same rows Symfony's sign-in reads today, so an account signs in the same way under any host. Nothing is wired by the core itself: a host bridge (omnibridge/symfony, omnibridge/laravel) mounts them.

The TOTP secrets at rest (Marco's decision QA5). A site turns sealing on with totp: { secret_key: '%env(OMNIAUTH_TOTP_KEY)%' } in omniauth.yaml (its Laravel twin: 'secret_key' => env('OMNIAUTH_TOTP_KEY') in config/omniauth.php, the same key): base64 of 32 bytes, from the secrets vault in production, .env.local in development, a fixed key of the test environment's own in .env.test - never a committed real key. The settings page (UserSettingsController) writes the enrolled secret through omniauth's TotpSecrets and opens it only to draw the QR code; the sign-in opens it only to verify a code. The secrets written in clear before are read as they are until the site's migration rewrites them (lesringostars: Version20261023120000, up seals, down opens, idempotent); the column (VARCHAR(255)) holds the 130 characters of a sealed secret unchanged. Rotating the key: omniauth/otp's docs/otp.md.

Base\Auth\Policy is this page's rule on omniauth's second-factor rule: a demonstration account is never asked for one; an account a second factor is required of and that has none is signed in, then sent to enrol (needsEnrolment()); turning off the last second factor of such an account is refused (onRevoking(), reason two-factor-mandatory), any credential of a demonstration account too (demo-account); and an account that has a second factor or an administration role (SecurityPolicy::isAdministrator()) is never linked to an identity provider by its address alone (allowsEmailLinking(), through PolicyLinking).

The listeners, Base\Auth\Listener\*, each say which events they take (events()): GuardSignIn (the captcha after failures from an address, SignInGuard), TrackConnections (the browsers' connections), WarnNewDevice (the e-mail and the offer of a new device), UpdateAccount (unknown roles, time zone, language, kick, at each sign-in) and WelcomeBack (the e-mail of a disabled account).

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 omnisense/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.)

File links

The debug page's and the profiler's links open the file on the developer's machine when the site runs in a container: APP_PATH (the project's path on the host, which a site's Makefile writes in .env.local) is mapped from kernel.project_dir with Symfony's own format, vscode://file/%f:%l&/srv/app/>/Users/me/site/ (omnibridge/symfony's Omnibridge\Symfony\FileLinks, formerly Base\Bridge\Symfony\FileLinks). debug.file_link_formatter is decorated with Symfony's FileLinkFormatter on that format (the HTML error renderer and the profiler receive it), and SYMFONY_IDE is set to it when Base\BaseBundle is constructed, for the page Symfony's ErrorHandler renders by itself before a request is handled (a container that does not compile). A site's own framework.ide or SYMFONY_IDE is kept; one that already maps (&...>) too; with none, VS Code's format. omnibase's former syntax, which the sites' framework.ide writes - "vscode://file/%%f[%%b:%env(APP_PATH)%]:%%l", %b read as the path in brackets - is read as Symfony's mapping.

Until 4.0, Base\Inspector\HtmlErrorRenderer and FileLinkFormatter did this by extending Symfony's classes - the formatter is @final - and glitchr/base-plugin patched symfony/error-handler for it (@final removed, private made protected, the ErrorHandler's new HtmlErrorRenderer replaced). Gone: symfony/error-handler is installed as published.

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/30-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.

omnibase's cache:clear checks the PHP configuration, the disk, webpack's build and the technical recipient before Symfony's clear, holds a lock (a second cache:clear started meanwhile exits without clearing), and on an installation's first clear runs a second one in a process of its own (base.autoclear). See Console commands.

Before switching traffic

• base.notifier.technical_loopback is true by default: every e-mail goes to the technical recipient. Production sets it to false.
• base.site.index names the home page's route, base.uploader.storage and base.twig.editor.storage the storages of the uploads (Configuration reference).

Commands to schedule

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              # omnisense/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 Foundation 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, omnibase/classroom, omnibase/agenda, omnibase/scholar, omnibase/press and omnibase/consulting are not installed by the image; the overlay mounts their checkouts too (test blog, test classroom, test agenda, test scholar, test press, test consulting), and omnisense/omnischolar's (OMNISCHOLAR, ../../../omnischolar by default), whose classes the scholar's tests' bootstrap registers. 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 Foundation: bare

tests/Foundation.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 Foundation; 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 Foundation that name the framework
docker compose run --rm omnibase bare vendor/omnisense/omnibase/tests/Contract/runtime-without-framework.php   # a script, with the autoloader alone

Where the framework is not installed (plan "omnibase agnostique", C7c): the classes are loaded with the autoloader of var/bare/vendor, the core installed alone by composer install --no-dev - its composer.json as it is, its autoload pointed back at the checkout's src/ - so none of Symfony's framework packages is there (symfony/console aside, doctrine/orm's). bare --install makes it, and makes it again when composer.json changed; demo.sh runs it before bare and before the core's suite, whose BareTest measures the Foundation there (skipped in an application's suite, where it was not made). A class declares what is installed: Base\Entity\User's contracts are empty interfaces there, Security's and scheb/2fa's on the harness's own vendor (BareTest checks both). OMNIBASE_AUTOLOAD names another autoloader to measure on.

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 Foundation used without the framework (see The contracts of the Foundation).

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/omnisense/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 Foundation 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 Foundation, 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

Since 4.0 the image's doctrine/orm is as released: glitchr/base-plugin, which patched it for the cores before step C6, is gone (omnibridge/composer applies only what the core declares, extra.omnibridge: symfony/process). To run the suites on another release of doctrine/orm, mount its 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 omnisense/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 omnisense/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 omnisense/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 omnisense/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 omnisense/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/omnisense/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/omnisense/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/omnisense/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 omnisense/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.

Configuration reference

Everything under the base: key of config/packages/base.yaml, as Base\DependencyInjection\BaseConfiguration declares it, with its type, its default and what reads it. The values are processed once, when the container is built, by Base\DependencyInjection\BaseExtension::load().

How the values are read

BaseExtension does not hand the processed tree to services one by one: it sets every node as a container parameter named after its path, base. and the keys joined by dots (AbstractBaseExtension::setConfiguration()). An array is set both whole and leaf by leaf: base.time_machine.excludes is the list, base.time_machine.excludes.0 its first entry. The code reads them through Base\Service\ParameterBagInterface ($parameterBag->get('base.uploader.storage')), %base.download_links.ttl% in a service definition, or Base\Contract\Runtime::parameters() where there is no container (an entity's getter).

Under Symfony the parameter bag is Base\Service\HotParameterBag: the settings stored in the database are laid over the container's parameters (see The parameters and the settings over them). A path the configuration does not declare reads as null.

The smallest configuration

The harness's application (docker/app/config/packages/base.yaml) runs on this:

base:
    parameter_bag:
        use_hot_bag: true
        use_setting_bag: true
    database:
        use_custom: true
    router:
        use_custom: true
    attributes:
        use_custom: true
    twig:
        use_custom: true
        use_form2: true
        use_bootstrap: true
        editor:
            storage: "local.wysiwyg"
    uploader:
        storage: "local.uploads"
    site:
        index: demo_index

The four use_custom flags and the two parameter_bag flags default to null (off): a site that leaves them out runs without omnibase's router, Twig loader, attribute reader and Doctrine features, without the settings stored in the database, and without those settings laid over the parameters (HotParameters reads the configuration whether the overlay is on or not). The storages are Flysystem storages of the site's own (config/packages/flysystem.yaml).

Dumping the tree

bin/console config:dump-reference base dumps it, and debug:config base the site's values (BaseExtension::getConfiguration()). The tree below was dumped in the core's harness with Symfony's reference dumper, from this script (the image's vendor, the core mounted over its copy):

<?php
// dump.php
require '/srv/demo/vendor/autoload.php';

use Symfony\Component\Config\Definition\Dumper\YamlReferenceDumper;

echo (new YamlReferenceDumper())->dump(new Base\DependencyInjection\BaseConfiguration());

docker run --rm --network none \
    -v "$PWD":/srv/demo/vendor/omnisense/omnibase:ro -v "$PWD/var/scratch":/scratch:ro \
    --entrypoint php omnisense/omnibase-harness:latest /scratch/dump.php

The full tree, with its defaults

The options read by nothing are deprecated (excluded_fields, share, access_restriction.redirect_on_deny, site.maintenance.exception, uploader.warmup, files.storage, images.autorotate, images.disable_profiler, images.warmup, images.formats, extension.logging_default_expiry): a site that sets one gets Symfony's deprecation notice, and they go at the next major.

twig.default_path is the package's own templates/ wherever Composer put it: /srv/demo/vendor/omnisense/omnibase/templates is the harness's.

base:

    # Automatically clear cache in case of integrity issue
    autoclear:            true
    database:

        # Fallback warning disable in case there is no fallback
        fallback_warning:     true

        # Use custom database settings
        use_custom:           null
        excluded_fields:

            # Defaults:
            - id
            - locale
            - translatable
    share:

        # Prototype
        -
            id:                   ~
            url:                  ~
    user:

        # Default throttling time between two tokens received
        token_default_throttling: 180

        # Allow using a token sent by email
        login_with_token:     false

        # Property used to identity user
        identifier:           email

        # Threshold considering user as inactive ("active delay" is expected to be lower than "online delay")
        active_delay:         60

        # Threshold considering user as offline
        online_delay:         300
        notifications:

            # Time before erasing data if read
            expiry:               '+30 days'
        register:

            # Administrator check required
            autoapprove:          false

            # Administrator are notify when someone register
            notify_admins:        false
    access_restriction:

        # Redirection in case of access restriction
        redirect_on_deny:     null

        # Access to public visitors
        public_access:        true

        # Access to users
        user_access:          true

        # Access to administrators
        admin_access:         true
        firewalls:

            # Default:
            - main

        # Routes (regular expressions on their names) no access restriction stops, and the referrer never remembers: the sign-in pages, the language switch, the UX endpoints.
        route_exceptions:

            # Default:
            - /^(?:locale_|ux_|user_|security_)/
        exceptions:

            # Prototype
            -
                locale:               null
                env:                  null

                # Regex 
                host:                 null

                # Regex 
                path:                 null

                # Regex 
                domain:               null

                # Regex 
                subdomain:            null

                # Regex 
                scheme:               null
    site:

        # Website home page
        index:                app_index
        maintenance:

            # Maintenance redirection
            redirect_on_deny:     security_maintenance
            exception:

                # Prototype
                code:                 ~

            # Maintenance lock file location
            lockpath:             '%kernel.project_dir%/public/maintenance.lock'
    router:

        # Use custom router
        use_custom:           null

        # Allow accessing by
        ip_access:            false

        # Restrict to permitted hosts
        use_fallbacks:        false

        # Fallback warning disable in case there is no fallback
        fallback_warning:     true
        host_fallbacks:

            # Prototype
            -
                locale:               null
                env:                  '%env(APP_ENV)%'
                reduction:            null

                # Sub-domain
                subdomain:            []

                # Machine name
                machine:              []

                # Domain
                domain:               []

                # Port number
                port:

                    # Default:
                    - 80

                # Base directory
                base_dir:             /
    translator:

        # How the site addresses people (docs/20-architecture/politeness.md): a text asked without a level of its own is taken in its "._plain", "._polite" or "._formal" variant when the catalogue has one (formal falls back on polite), else as it is. Unset: the texts as they are written.
        politeness:           null # One of null; "plain"; "polite"; "formal"
    parameter_bag:

        # Use setting bag from database
        use_setting_bag:      null

        # Use hot bag parameter rewriting
        use_hot_bag:          null
    notifier:

        # Enable mailer
        mailer:               true

        # Do not allow sending email until loopback is removed
        technical_loopback:   true
        technical_recipient:

            # Technical contact email
            email:                null

            # Default phone number
            phone:                null

        # Administrators receiving notifications
        admin_role:           ROLE_EDITOR
        test_recipients:

            # Default:
            - @localhost$
        options:

            # Prototype
            -
                channel:              ~
                markAsRead:           ~
    spam:

        # AKISMET API Key
        akismet:              ''
    time_machine:

        # Default compression algorithm
        compression:          gzip

        # Default time limit before deleting
        time_limit:           '+30 days'

        # Default compression algorithm
        max_cycle:            -1

        # Directory the snapshot is staged in before transfer (defaults to the kernel cache directory)
        snapshot_dir:         null

        # Paths left out of the application tarball
        excludes:

            # Defaults:
            - ./vendor
            - ./node_modules
            - ./var/cache
            - ./var/log
            - ./var/coverage
            - ./var/phpunit
            - ./.git
    icon_provider:

        # Default icon provider class
        default_adapter:      Base\Service\Model\IconProvider\Adapter\FontAwesomeAdapter
    uploader:

        # Automatic image uploader warmup
        warmup:               true

        # Upload storage location
        storage:              null
        formats:

            # Prototype: Specific formats
            -
                class:                ~
                property:             ~
                width:                ~
                height:               ~
    files:
        storage:              null
    images:
        max_resolution:       Base\Imagine\Filter\Basic\Definition\UltraHighDefinitionFilter
        autorotate:           true
        debug:                false
        disable_profiler:     true
        max_quality:          1
        timeout:              60
        enable_webp:          true
        no_image:

            # Prototype: Replacement image
            -
                extension:            ~
                path:                 ~
        fallback:             false
        warmup:               true
        formats:

            # Prototype: Specific formats
            -
                class:                ~
                property:             ~
                width:                ~
                height:               ~
    paginator:

        # Range around the current page
        page_range:           1

        # Number of element per page
        page_size:            10

        # Default parameter name in route
        page_parameter:       page

        # Default template used to display pages in sliding control
        default_template:     '@Base/paginator/sliding.html.twig'
    obfuscator:

        # Compression level
        level:                -1

        # Use uuid shortening
        uuid:                 6ba7b811-9dad-11d1-80b4-00c04fd430c8

        # Compression encoding
        encoding:             null

        # Decoding max length
        max_length:           0

        # Compression algorithm
        compression:          'null'

        # Identifier-map storage directory; must survive cache:clear/deploys or previously-issued short URLs become permanently unresolvable
        cache_dir:            '%kernel.cache_dir%'
    twig:
        breakpoints:

            # Prototype
            -
                name:                 ~
                media:                ~
        themes:
            audiences:

                # Prototype
                name:
                    age:                  null
                    icon:                 null
            widths:

                # Prototype
                name:
                    icon:                 null
                    class:                null

            # Default audience key among valid audiences
            default_audience:     null
            events:

                # Prototype
                name:
                    begin:                null
                    end:                  null
                    priority:             0
                    icon:                 null
            modes:

                # Prototype
                name:
                    class:                null
                    icon:                 null
                    prefers:              null
            filters:

                # Prototype
                name:
                    icon:                 null
                    filter:               null
        script_attributes:
            defer:                false
            async:                false

            # Scripts run in the order of the page: a file named -async is loaded defer. The core's base-async sets window.jQuery, which the site's entries read as an external; false brings back async, with no guarantee that it runs first.
            ordered:              true
        link_attributes:
            defer:                false
            async:                false

        # Use base filesystem loader
        use_custom:           null

        # Use custom base form style
        use_form2:            true

        # Include EA form style
        use_ea:               true

        # Use bootstrap style in forms
        use_bootstrap:        true

        # Autoappend required dependencies in html content
        autoappend:           true

        # Default twig path: the templates/ of this package, wherever Composer installed it (vendor/omnisense/omnibase, a path repository, a checkout)
        default_path:         /srv/demo/vendor/omnisense/omnibase/templates
        form_themes:

            # Default:
            - ./form/form_div_layout.html.twig
        editor:
            storage:              null
        paths:

            # Prototype
            -
                path:                 ~
                namespace:            ~
    attributes:

        # Use custom attribute reader
        use_custom:           null
        paths:

            # Default:
            - %kernel.project_dir%/src/Attribute
    security:
        two_factor:

            # Roles whose holders must have a second factor (directly or through the role hierarchy), e.g. [ROLE_STAFF]. Empty: the administrator's "mandatory for everyone" setting alone decides. A later definition (when@dev, when@test, another file) replaces the list, it does not add to it.
            required_roles:       []

            # Whether the enrolment prompt offers a "not now" (kept for the session). False: an account a second factor is required of is sent back to the prompt on every page until it has one.
            postpone:             true
    demo:

        # The DSN of the production database ("mysql://host:3306/name"; user and password are not compared). The demo environment refuses to start on it - and refuses to start while this is unset.
        production_database:  null

        # The super-administrator's password in the demo environment: a secret (DEMO_SUPERADMIN_PASSWORD). Unset or empty: no account whose roles reach ROLE_SUPERADMIN can sign in there.
        superadmin_password:  '%env(default::DEMO_SUPERADMIN_PASSWORD)%'

        # The roles that open the back office. In the demo environment an account whose roles reach one of them is not offered to visitors - neither in the banner nor on the sign-in page - and signs in with base.demo.admin_password or not at all. Empty: the back office is as public as the rest of the demonstration.
        admin_roles:

            # Default:
            - ROLE_ADMIN

        # The password of the back office's accounts in the demo environment: a secret (DEMO_ADMIN_PASSWORD), given to whoever is shown the back office. Unset or empty: no account whose roles reach base.demo.admin_roles can sign in there.
        admin_password:       '%env(default::DEMO_ADMIN_PASSWORD)%'

        # Identifiers of declared demonstration accounts this site leaves out.
        exclude:              []
        reset:

            # Directories demo:reset empties before it reloads the fixtures: the files visitors sent to a storage of the application's own.
            purge:                []

            # The fixture groups demo:reset loads (doctrine:fixtures:load --group). Empty: every fixture.
            groups:               []

            # Whether demo:reset deletes the uploaded files no row names any more (uploader:entities --delete-orphans).
            orphans:              true
    opening_hours:

        # The timezone the hours are given in.
        timezone:             Europe/Paris

        # "HH:MM": past it, orderDay() is the next open day. Null: the day itself until it closes.
        cutoff:               null

        # The usual week until one is saved (hoursWeekDay): ISO day (1 = Monday) => [["09:00", "13:00"], ...].
        week:                 []
    local_business:

        # The schema.org type: LocalBusiness, or one of its kinds (Restaurant, Store, Dentist, ProfessionalService...).
        type:                 LocalBusiness

        # Null: the site's title (base.settings.title).
        name:                 null

        # Null: the site's home address.
        url:                  null

        # Null: the setting base.settings.phone.
        telephone:            null
        email:                null

        # A path under public/ ("assets/ico/android-chrome-512x512.png") or an address.
        image:                null

        # "€€", "10-50 €"...
        price_range:          null
        address:
            street:               null
            postal_code:          null
            locality:             null
            region:               null

            # ISO 3166-1 alpha-2: FR.
            country:              null
        geo:
            latitude:             null
            longitude:            null

        # The business elsewhere: its Facebook, Instagram, LinkedIn pages.
        same_as:              []
        area_served:          []

        # Any other schema.org property, merged as it is: {parentOrganization: {"@type": Organization, name: PANO}}.
        extra:                []
    guard:

        # The captcha: a gateway of omnishield.gateways. Null: omnishield.challenge.gateway when glitchr/omnishield is installed; false: none.
        challenge:            null

        # The captcha shown to a visitor who refused the third party the captcha reaches (consent): a gateway that reaches nobody, ALTCHA.
        fallback:             null

        # The lists asked about whoever submits (IP address, e-mail, name): gateways of omnishield.gateways - disposable, stopforumspam.
        reputation:           []

        # The classifier of what is written (SpamChecker): a gateway of omnishield.gateways. Null: Akismet with the key api.spam.akismet (base.spam.akismet) when omnishield/akismet is installed.
        classifier:           null

        # A list or a classifier that does not answer: the form goes on (accept) or is refused (reject). The captcha's is omnishield.challenge.unreachable.
        unreachable:          accept # One of "accept"; "reject"

        # Seconds between a guarded form being shown and sent: faster is a robot. 0: not checked.
        min_delay:            3

        # Failed sign-ins from an address before the sign-in form asks the captcha too. 0: never.
        sign_in_after:        3

        # Refused tries of a guarded form from a visitor (address, else session; 15 minutes) before its captcha is shown and asked. 0: always shown. A form sets its own with the option guard.captcha_after.
        captcha_after:        3
    signatures:

        # The gateway envelopes go through: one of omnisign.gateways. Null: the only one configured.
        gateway:              null

        # The private Flysystem storage the signed documents and their evidence are kept in. Null: the uploads' (base.uploader.storage).
        storage:              null
    comments:

        # Seconds between a comment form being opened and sent: faster is a robot.
        min_delay:            4

        # Seconds between two comments from the same address.
        flood_interval:       60
    vault:

        # #[Vault]: without the environment's key pair (bin/console secrets:generate-keys), store a secured field in clear instead of refusing it. Off: the save fails with VaultKeyNotFoundException.
        allow_plaintext:      false
    download_links:

        # Seconds a signed download link stays valid.
        ttl:                  600
    extension:

        # Max number of revision for a given entity
        max_revisions:        5

        # Time a trashed entity is kept before the purge may delete it for good: a relative date PHP reads ("+7 days", "+1 month"); a bare number is a number of days
        empty_trash:          '+7 days'

        # Default logging expiry
        logging_default_expiry: 180
    screens:

        # The version of the front end that renders the screens (omnibridge/react's X-Omnibridge-Version): a front end of another version reloads the page whole. Null: none checked.
        version:              null

Top level

database

share

A list of {id, url}. Deprecated, read by nothing: the sharing buttons come from the adapters tagged base.service.sharing (Base\Service\Model\Sharing\SharingAdapterInterface).

user

access_restriction

Who may see the site, checked by Base\Security\Voter\AccessVoter (see Routes and access).

site

router

RouterSubscriber applies the IP-address rule only when isGranted('VALIDATE_IP', $route) is true; no voter of the core decides VALIDATE_IP (only PermissionVoter could, for a user holding that permission tag), so ip_access has no effect at this commit.

translator

parameter_bag

notifier

spam

time_machine

The backups (Base\Service\TimeMachine, Backups).

icon_provider

uploader and files

images

Read by Base\Service\MediaService.

paginator

obfuscator

Base\Service\Obfuscator: the data of the media and UX routes, and the |obfuscate filter.

twig

attributes

security

demo, opening_hours, local_business, guard, signatures, comments, vault, download_links

Each has its page, which describes its options: The demo environment, Opening hours, LocalBusiness JSON-LD, The forms' guard, Signatures, Comments, Sealed fields, Downloads and QR codes. Their types and defaults are in the tree above; the integer options of guard and comments refuse a negative value, download_links.ttl one below 1.

extension

screens

What the extension registers

Besides the parameters, BaseExtension:

• loads the package's config/services.php (every file of config/services/), services-public.php, services-fix.php and services-decoration.php;
• puts twig.form_themes after base.twig.form_themes in twig.form.resources;
• before every extension loads (prepend()): sets base.package_dir, the package's directory wherever Composer installed it (what a configuration names instead of a vendor path: '%base.package_dir%/docs'); declares to DoctrineBundle the DBAL types utc_datetime_immutable, utc_datetime, the passkey's columns and every type of src/Enum (the package's and the application's) that has a getStaticName(); and, when symfony/ux-twig-component is installed, the component namespaces Base\Twig\Component\ (templates @Base/components/, prefix base) and App\Twig\Component\ (@App/components/, prefix app);
• tags by autoconfiguration what implements:

Console commands

The commands the core registers (config/services/core.php, config/services/demo.php, services-decoration.php), as bin/console list shows them in the core's harness. Most extend Base\Console\Command, which needs a ConsoleOutput (it throws LogicException on any other output, a BufferedOutput included) and adds a --purpose option to some of them; user:create is a plain Symfony command, usable from scripts and tests.

The usages below are bin/console help <name> in the harness, Symfony's common options (-h, -q, -v, -e, --no-debug...) left out.

Summary

The developer's lookups, each listing what it names without changing anything:

cache:clear

Usage:
  cache:clear [options]

Options:
      --sessions             Kill all existing sessions
      --no-extension         Skip base extension
      --no-warmup            Do not warm up the cache
      --no-optional-warmers  Skip optional cache warmers (faster)

Base\Console\Command\CacheClearCommand runs Symfony's own command (console.command.cache_clear) between omnibase's steps:

1. It takes a lock, var/cache/<env>/.lock (a lock file older than 120 seconds is taken as stale and removed). When another cache:clear holds it, it prints "Cache clear aborted: another process is already clearing the cache." and exits 0.
2. Unless --no-extension: the PHP configuration, disk and memory, the cache, the virtualisation and the PHP extensions are checked and reported, then webpack's build, the technical recipient (base.notifier.technical_recipient), a phpinfo page and the public symlinks are made or checked - all before the cache goes, while the services they read can still be built.
3. Symfony's cache:clear runs, with the same options.
4. A counter of clears is kept in var/cache/<env>.txt; --sessions then runs cache:clear:sessions.
5. Unless --no-extension: on the first clear of an installation and with base.autoclear, cache:clear runs a second time in a process of its own; then OPcache is reset.

cache:clear:sessions

Usage:
  cache:clear:sessions [options]

Options:
      --purpose[=PURPOSE]  Show command description ?

Deletes every sess_* file of var/sessions, which signs everybody out where the sessions are kept in files there.

$ php bin/console cache:clear:sessions
 [INFO] Session files cleared from /srv/demo/var/sessions.

user:create

Usage:
  user:create [options] [--] <username> <email>

Arguments:
  username                 Its username
  email                    Its e-mail address

Options:
  -r, --role=ROLE          Its role(s): USER, ADMIN, SUPERADMIN... [default: ["USER"]] (multiple values allowed)
  -p, --password=PASSWORD  Its password (otherwise generated)
      --keep-password      Do not ask for a new password at the first sign-in
      --no-email           Do not e-mail the account its username and password

The account is verified and approved. A role is a key of UserRole, with or without ROLE_ (-r ADMIN -r EDITOR); an unknown one fails the command. Without --password, the password is four groups of four letters and digits, without the characters read alike (0/O, 1/l/I), printed once. Without --keep-password the account gets a change-password token, and PasswordChangeSubscriber asks for a new password at its first sign-in. Without --no-email, Notifier::sendAccountCreated() mails it its username and password. The username is written only where the application's User has a username property (Base\Entity\User has none); an e-mail address or a username already taken fails the command.

$ php bin/console user:create jdoe jdoe@example.com --no-email

 [OK] jdoe (jdoe@example.com), ROLE_USER.

Password: a56J-S2gs-m7Lj-CLQj - to be changed at the first sign-in

user:notifications

Usage:
  user:notifications [options]

Options:
      --user=USER      The account (its identifier); every account without it
      --expiry=EXPIRY  The age past which a read notification is erased ("+30 days"); base.user.notifications.expiry without it
      --show           List them
      --clear          Erase the read ones older than the expiry
      --clear-all      Erase every read one, whatever its age

Counts every notification (the account's with --user), those read, and those read and older than the expiry (--expiry, else base.user.notifications.expiry, +30 days); --show lists them, --clear erases the read ones past the expiry, --clear-all every read one. An unread notification is never erased.

$ bin/console user:notifications --user=anne@example.org --clear
3 notification(s) found, 1 notification(s) are marked as read, 1 notification(s) older than +30 days
These notifications are now erased..

notifier:mail:test

Usage:
  notifier:mail:test [options]

Options:
      --user[=USER]     User ID (or email, or username) to send the notification to

Sends Notifier::testEmail() to the user named, else to the user whose address is the technical recipient's, else to an unsaved user with that address. With base.notifier.technical_loopback on, it says so: the e-mail goes to the technical recipient whoever it is for.

$ php bin/console notifier:mail:test

 ! [NOTE] Notifier loopback is enabled. Notifications will be sent to the
 !        technical recipient:
 !        "admin@example.org <admin@example.org>" / en-GB

 [WARNING] No user found in database as technical recipient: "admin@example.org
           <admin@example.org>" / en-GB

 [OK] Sent test email to admin@example.org (Name: admin@example.org, ID: 0)
      using async transport.

app:notifier

Lists the public methods of Base\Notifier\Notifier that BaseNotifier does not declare: the notifications it can build.

$ php bin/console app:notifier
Available templated notifications:
 * getContactRecipient
 * testEmail
 * contactEmail
 * contactEmailConfirmation
 * userAccountGoodbye
 * userApprovalRequest
 * userApprovalConfirmation
 * accountCreated
 * resetPasswordRequest
 * verificationEmail
 * loginToken
 * loginLink
 * emailCode
 * userWelcomeBack
 * words
 * duration

base:mailer:trap

Usage:
  base:mailer:trap [options] [--] [<action> [<id>]]

Arguments:
  action                status, on, off, list, show, purge, release [default: "status"]
  id                    Which held message, for show/purge/release

Options:
      --all             Apply to every held message
      --reason=REASON   Note why the trap was armed, for whoever finds it later

Holds the outgoing mail during an incident. Armed (on, or arm), the trap (Base\Mailer\MailTrap, listening to symfony/mailer's MessageEvent at priority -1000) keeps every message in var/mail-trap/ instead of sending it - at send time, so mail already queued for a worker is caught too.

$ php bin/console base:mailer:trap status

 [OK] Trap off - mail is being delivered normally.

 Held messages: 0
 Directory:     /srv/demo/var/mail-trap

thread:publishable

Usage:
  thread:publishable [options]

Options:
      --publish         Should I publish them ?

Reads the threads in the FUTURE state (Threads::byStateUncached()), says which are publishable (their publication time has come), and with --publish publishes each: its row locked (PESSIMISTIC_WRITE) and read again, so that two runs at once publish it once, then poke()d and flushed, which raises thread.publishable (see Events). With -v each thread is listed. Meant for a cron.

$ php bin/console thread:publishable

 [OK] 0 scheduled thread(s) found: 0 thread(s) publishable.

trash:purge

Usage:
  trash:purge [options]

Options:
      --force           Actually destroy them (without this, only reports)
      --limit=LIMIT     Destroy at most N entries in this run

Destroys the trashed entities (TrashBall) past their grace period (base.extension.empty_trash). A dry run unless --force: it lists what it would destroy. Meant for a cron.

$ php bin/console trash:purge
Nothing to purge. The trash holds 0 entries, none past its grace period.

timemachine:snapshot, :backup, :restore

Usage:
  timemachine:snapshot [options] [--] [<storages>...]

Arguments:
  storages                   What storages do you want to backup?

Options:
      --cycle[=CYCLE]        Which version do you want to get?
      --prefix[=PREFIX]      Which prefix do you want to use? [default: "dev"]
      --database[=DATABASE]  Which database do you want to backup?

The prefix's default is the kernel's environment (dev in the harness). :backup adds --id, --batch (no confirmation asked) and --userlog (the user configuration included); :restore adds --id.

timemachine:snapshot lists the database connections, the storages of the backups (Flysystem storages, remote ones marked) and, with -v, the snapshots by day. :backup asks for confirmation (none with --batch), says whether the user configuration is included (--userlog), and fails without a storage named. :restore asks whether to restore the latest version (when no --id), then whether to restore the application from its tarball and the database. See Backups and base.time_machine in the configuration.

In the harness (a SQLite connection) timemachine:snapshot stops on "Could not find field serverVersion in configuration for connection type default": the backups read the connection's parameters of a MySQL server.

uploader:entities, uploader:images, uploader:images:crop

Usage:
  uploader:entities [options]

Options:
      --entity[=ENTITY]      Should I consider only a specific entity ?
      --property[=PROPERTY]  Should I consider only a specific property ?
      --uuid[=UUID]          Should I consider a specific uuid ?
      --orphans              Do you want to get orphans ?
      --delete-orphans       Do you want to delete orphans ?

uploader:entities reads every #[Uploader] property of the entities (App\Entity\... and Base\Entity\..., or the one --entity names), counts their files and, with --orphans, finds the orphans: files of the storage no row names, and names in rows with no file. --delete-orphans deletes them from the storage. A property declared missable is passed by (it cannot have orphans). -vv lists the orphans, -vvv every file. demo:reset runs it with --delete-orphans (base.demo.reset.orphans).

uploader:images adds --warmup (build the cached images: each file, as is and in WebP, and its thumbnails at the sizes of base.uploader.formats), --format (only one WIDTHxHEIGHT), --cache and --batch (both flags, they take no value). uploader:images:crop adds --normalize and --max-definition, and warms up the crops of the ImageCrop entities (each crop of each image's source, WebP and not).

icon:entities

Usage:
  icon:entities [options]

Options:
      --id[=ID]          Should I pick up one specific entityId ?
      --entity[=ENTITY]  Should I consider only a specific entity ?

Without --entity, each entity class implementing IconizeInterface (the core's and the application's) and its static icons; with --entity, the icons of each row (or the one --id names).

$ php bin/console icon:entities
Entity list:
 * Base\Entity\Extension\Abstract\AbstractExtension: [fa-solid fa-external-link]
 * Base\Entity\Extension\Revision: [fa-solid fa-sort-numeric-down]
 * Base\Entity\Extension\TrashBall: [fa-solid fa-trash-alt]
 * Base\Entity\Layout\ShortLink: [fa-solid fa-compress-alt fa-rotate-45]
 ...

translation:controllers and translation:settings

Usage:
  translation:controllers [options]

Options:
      --controller[=CONTROLLER]  Should I consider only a specific controller ?
      --suffix[=SUFFIX]          Should I add a specific translation suffix to the default path ? [default: "title"]
      --locale[=LOCALE]          Should I display only a specific locale ?

Usage:
  translation:settings [options]

Options:
      --path[=PATH]      Should I consider only a specific setting path ?
      --raw              Should I display the raw information ? (including user label and help information)
      --locale[=LOCALE]  Should I display only a specific locale ?

translation:controllers prints, for each route whose controller is in App\ or Base\ (or starts with --controller), the text of @controllers.<route>.<suffix> in each available locale, "no translation found" where the catalogue has none. translation:settings prints the settings (those under --path) in each locale, --raw their labels and help texts. A --locale outside the available locales is an error.

entity:discriminator

Usage:
  entity:discriminator <entity>

Throws "Class "..." is not an entity." when the class is not a mapped entity; otherwise prints nothing and exits 0.

base:mapping

Lists the classes of the core's Enum, Form, Entity and Repository directories, each "aliased to" its App\ name when the application has no class of that name, or overridden by the application's.

doctrine:database:import

Usage:
  doctrine:database:import [options] [--] [<path>]

Arguments:
  path                             Path or URL

Options:
      --spreadsheet[=SPREADSHEET]  Import selected spreadsheet (e.g. 1,3,4 [NB: starts from 1])
      --extension[=EXTENSION]      Specify file extension to be used
      --entries[=ENTRIES]          Only read N-rows
      --skip[=SKIP]                Skip i-entries [default: 0]
      --batch[=BATCH]              Persist by batch of X entries. [default: 25]
      --notify                     Send notification if needed
      --force                      Import without asking confirmation.
      --on-the-fly                 Import right after each single entity got hydrated

Reads a workbook (xls, xlsx, xlsm, or xml), or a csv or txt file as one sheet named after the file (from the file's MIME type or --extension; the path is asked when not given), lets you choose its sheets (or takes --spreadsheet), and imports each sheet as entities of the class its first column's heading names. The second line of a sheet is a comment line, skipped. A heading is a property path; name:unique makes the column a key (a row already in the database is not imported again), tags:explode(,) splits a cell into a list, parent[title] finds an associated entity by one of its fields. The notifier is disabled unless --notify.

doctrine:schema:charset

Usage:
  doctrine:schema:charset [options]

Options:
      --update                         Update database charset,collate
      --charset[=CHARSET]              Database charset value
      --collate[=COLLATE]              Database collate value
      --update-tables                  Update table collate
      --table[=TABLE]                  Table name
      --table-collate[=TABLE-COLLATE]  Table collate value

MySQL only (SHOW VARIABLES, SHOW TABLE STATUS, ALTER DATABASE). Without options it shows the database's character set and collation and each table's collation. --update alters the database to --charset/--collate (else the connection's charset and defaultTableOptions.collate); --update-tables converts every table (or --table) to them. --table-collate only appears in the message printed: the tables are converted to --collate.

doctrine:array:upgrade

MySQL only. Finds the columns whose comment says (DC2Type:array) (DBAL 3's serialized arrays) or that are JSON, rewrites each row's serialized value as JSON (an empty value becomes [], a value already JSON is left, a value that does not unserialize is skipped and reported), then alters an array column to JSON. Errors are printed, not thrown.

Events

The events the core dispatches - through Symfony's event dispatcher, and through Doctrine's event manager for those of the mapping and the queries - and the listeners it registers on the framework's own events. The lists of listeners are bin/console debug:event-dispatcher and doctrine:debug:event-manager in the core's harness, the core's alone (the plugins' listeners left out).

Events the core dispatches

The constants are the names to listen to: ThreadEvent::PUBLISHABLE, UserEvent::APPROVAL, SitemapEvent::BUILD, SignatureEvent::COMPLETED...

Entity events

ThreadEvent and UserEvent extend Base\EntityDispatcher\AbstractEvent:

Their dispatchers (Base\EntityDispatcher\AbstractEventDispatcher) are Doctrine listeners: on prePersist and preUpdate they compare the entity with its state before the change (EntityHydrator::getOriginalEntity()) and record the events it raises; on postPersist, postUpdate and postRemove they dispatch them, each event once per entity. A listener may change entities, but never flushes: the dispatcher flushes those changes once the flush that raised the events is over, from EntityDispatcherFlushSubscriber (on kernel.response, console.terminate and WorkerMessageHandledEvent, priority 64), for five rounds at most. A flush the application makes later in the request takes them along.

An application adds its own: a class extending AbstractEventDispatcher, named after its event class with Dispatcher appended (App\EntityDispatcher\Event\OrderEventDispatcher dispatches App\EntityDispatcher\Event\OrderEvent, which extends AbstractEvent), with supports(), onPersist(), onUpdate() or onRemove() calling addEvent($name, $entity). Autoconfiguration tags it (see What the extension registers).

namespace App\EntityDispatcher\Event;

use App\Entity\Order;
use Base\EntityDispatcher\AbstractEventDispatcher;
use Doctrine\Persistence\Event\LifecycleEventArgs;

class OrderEventDispatcher extends AbstractEventDispatcher
{
    public function supports(mixed $subject): bool
    {
        return $subject instanceof Order;
    }

    public function onUpdate(LifecycleEventArgs $event)
    {
        $order = $event->getObject();
        if ($order->isPaid() && !$this->entityHydrator->getOriginalEntity($event)->isPaid()) {
            $this->addEvent(OrderEvent::PAID, $order);
        }
    }
}

What the core does on them

Base\EntitySubscriber\ThreadSubscriber listens to thread.scheduled (the thread's state becomes FUTURE) and thread.publishable (its state becomes PUBLISH; each author is e-mailed thread.published, each member mentioned who is not an author thread.mentioned).

Base\EntitySubscriber\UserSubscriber tells an account's owner what happened to it, each notification sent with the importance success through the site's channel policy (framework.notifier.channel_policy), and only for what the owner did, or what happened with nobody signed in (a command, a worker) - an administrator closing someone's account sends nothing:

SitemapEvent

registerAttributes() can only list the routes it can generate without parameters; the pages of entities are the application's to list. getSitemapper() gives the SitemapperInterface being built, getHostname() the scheme and host of the request. See Sitemap.

SignatureEvent

getEnvelope() the Envelope, getSubject() the entity it is about when it still exists, getSigner() the signer's key (SIGNED only). See Signatures.

Doctrine events of the core

Base\Database\Events names four events dispatched on the entity manager's event manager:

DoctrineQueryEventArgs::getClassMetadata() and getEntityName() say which entity is queried. Each is dispatched only when a listener exists.

What the core listens to

The kernel

The Subscriber classes are in Base\Subscriber\. In the demo environment, and only there, config/services/demo.php registers DemoSubscriber (kernel.response at -1024: noindex on every response; MessageEvent at 1024: no e-mail leaves), DemoBackOfficeSubscriber (CheckPassportEvent at 128, kernel.request at 4) and the Doctrine listener DemoAccountLockSubscriber (preFlush): see The demo environment. IntegritySubscriber, in the same directory, is registered by no configuration, on purpose: it would open a session on every main request, run bin/console cache:clear inside the request on a Doctrine TypeError, and sign the user out when its checks fail.

The console, the mailer and Messenger

Security and omniauth

The Omniauth\Event\* listeners exist where omnisense/omniauth is installed (see Account security).

Doctrine