z77 / persistence-doctrine
Z77 Doctrine driver | relational persistence behind the kernel's UnifiedEntityManager — Doctrine ORM on MariaDB, reached through the same Repository API as the File driver.
Requires
- php: >=8.4
- ext-pdo_mysql: *
- doctrine/dbal: ^4.4
- doctrine/migrations: ^3.9
- doctrine/orm: ^3.7
- symfony/cache: ^8.1
- symfony/console: ^8.1
- z77/kernel: ^1.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 05:00:45 UTC
README
The Doctrine driver for the z77 persistence layer (ADR-039). Relational entities on
MariaDB, reached through the same UnifiedEntityManager::getRepository() / persist() /
flush() / remove() as file-backed ones — the backend is a property of #[Entity], not of
the calling code. Depends on z77/kernel, Doctrine ORM 3 / DBAL 4 / Migrations 3 and
symfony/cache; requires PHP 8.4 (native lazy objects) and pdo_mysql.
Developed in the z77-ch/z77-framework monorepo
(packages/persistence-doctrine); not yet a split target or on Packagist — projects consume it
through a path repository until it is.
Why a separate package: the kernel carries no Composer dependency (ADR-001); Doctrine brings
about fifteen. An installation without this package runs exactly as before — the kernel's driver
map names doctrine, and only the first Doctrine entity boots the driver.
Scope
Bootstrap— found by the kernel'sZ77\Persistence\{Driver}\Bootstrapconvention; boots on the first Doctrine entity of a request, never on a file-only request.DoctrineEntityManager— the kernel'sEntityManagerInterfaceover Doctrine's EntityManager.reorder()is refused: it is a File-driver concept. After a rollback the Doctrine EntityManager is replaced (EntityManagerHolder), so the request can still read; entities loaded before are detached.Transaction\DoctrineTransaction— the kernel'sTransactionInterface(UnifiedEntityManager::getTransaction(Entity::class)):run(callable)commits on return, rolls back and rethrows on exception; nesting joins, an exception anywhere rolls back the whole (a swallowed inner failure ends inTransactionRolledBackException);isOpen(). The File driver refuses the port.Entities\NumberRange/Repositories\NumberRangeRepository— gapless numbering:getRepository(NumberRange::class)->next('invoice')underSELECT … FOR UPDATE, inside the caller's transaction only, one bare integer sequence per name; a rolled-back unit of work consumes no number.create('journal-entry.2027')creates a range ahead of concurrent use without consuming a number;dropUnused('journal-entry.2027')deletes a range again as long as it has drawn no number.OpenWork\OpenWorkChecks— the open-work check registry: modules declare checks underopenWorkChecks→{scope}in their config, a caller asksask($scope, $parameters)and gets anOpenWorkresult (isEmpty(),isBlocked(),blocking(),warnings()) — e.g. for a period close or a stocktake block. A project adds its own checks inoverride/z77/module/{module}/src/App/Config/openWorkChecksConfig.inc.php(same shape), without copying the module config.Repository\DoctrineRepository—find/findAll/findBy/findOneBy. An entity-specific repository{Module}\Repositories\{Entity}Repositoryextends it and may use two protected, driver-specific seams (documented deviations, never handed further up):connection()for report SQL on the DBAL connection of the same EntityManager, andem()for a DQL read that must hydrate entities (a fetch-join instead of one lazy proxy per row).Type\MoneyType—Money↔DECIMAL(15,2)as a decimal string, never through float (ADR-042). Read in the installation's base currency.EntityManagerFactory— connection (utf8mb4/utf8mb4_unicode_cithroughout), attribute metadata over the modules' explicitdoctrineEntitieslists, native lazy objects, caches: metadata and query cache compiled to PHP files under the release-localvar/cache/doctrine/(in memory when DEBUG is on). «Cache leeren» and the DEBUG toggle in the backend delete the directory and invalidate every file in OPcache — through the kernel'sGeneratedPhpCache, so the backend needs no Doctrine.bin/z77-db— the migrations CLI (doctrine/migrations):migrate,status,diff,generate, andsetup(migrate, then write one migration per owner for what the mapping still needs and apply it — the developer's flow after changing an entity). Migrations are collected from this package (res/migrations, first one:number_range) and from every module that declaresdoctrineEntities(res/migrations/, namespace{Module}\Migrations); a successfulmigrateclears the compiled cache. The schema changes here and nowhere else — never from a web request.
Connection: config/client/database.inc.php — the one place, shared with the db backup.
Entities: a module lists them under doctrineEntities in its config, exactly like importEntities.
#[Entity('doctrine')] // z77 routing attribute — which driver #[ORM\Entity, ORM\Table(name: 'journal_line')] class JournalLine { #[ORM\Column(type: MoneyType::NAME)] private Money $debit; }
cd /path/to/project
php vendor/bin/z77-db status
php vendor/bin/z77-db setup # developer: after changing an entity
php vendor/bin/z77-db diff --namespace="Z77\Module\Financial\Migrations" # developer: write the migration
php vendor/bin/z77-db migrate # on the release about to go live
Not built yet
- Foreign-currency document amounts:
MoneyTypemaps the base currency only; how a document keeps currency and rate in the database is not designed yet. - Publishing: not a split target and not on Packagist yet (see above).
Documentation
docs/topics/persistence-doctrine.md— rules, known issues, pendingdocs/topics/persistence-architecture.md— the unified API both drivers sit behind- ADR-039 — the decision for a relational driver
Getting started
Don't start a project with composer require. Use the
z77-skeleton template — Use this template →
composer install. composer require z77/persistence-doctrine then adds this driver to an
existing z77 project; the business modules that need it require it themselves.