Consolidate 25 historical 2.x migrations into one end-of-2.8 schema

[turegjorup]

Why now

A major version is the natural clean-cut point for retiring migration history. Consolidating into 3.0 means:

• The 25 historical 2.x migrations are no longer replayed on every fresh install or CI run — boot time and test setup get measurably faster.
• Operators upgrading 2.x → 3.0 do this once, with a documented step. There's no follow-up migration debt sitting in the repo.
• The Template API surface change (removing the description query parameter, which dates back to 2.7) lands on the same major boundary, so 3.1 is internal cleanup only — no further user-visible API change required to finish the deprecation.

Doing this on a minor would mean introducing a coordinated cross-version operator step (rollup) and an API-filter trim mid-cycle, neither of which fit minor-version etiquette.

Summary

• Squashes the 25 historical 2.x migrations (Version20220309093909 … Version20250828084617) into a single consolidated migration Version20260506215847.php representing the end-of-2.8 schema. Generated via doctrine:migrations:diff --formatted (not dump-schema, which silently omits FK constraints in doctrine/migrations 3.7).
• Picks up feat: prep db identifiers for cross-platform (Postgres) portability #444's portability prep into the consolidated DDL: 15 <table>_changed_idx index names (Postgres-safe) and the backtick-quoted user table. The same shape is what 2.x → 2.8 → 3.0 upgraders end on via Version20260507120000, so fresh installs and rollups produce identical schemas.
• Restores three previously removed Template entity properties (icon, resources, description) as deprecated, write-only fields with no getters/setters. The columns are kept in the consolidated 3.0 schema so fresh installs and 2.x → 3.0 upgraders end up with identical schemas, and Doctrine writes a value on every INSERT (the columns are NOT NULL with no DB default — without entity-side defaults, fixtures and app:templates:install fail).
• Removes the previously 3.0-only Version20250815092648 (template column drop). The properties and the matching column-drop migration are scheduled for joint removal in 3.1 (TODO[3.1] markers throughout).
• Adds a Template-specific template.search_filter (title only) so the deprecated description property is not re-exposed as a GetCollection query parameter. The shared entity.search_filter keeps description for other entities. #[ApiFilter] / #[ApiProperty] attributes were tried first but are silently ignored when the resource is YAML-configured.
• Rewrites UPGRADE.md step 3: prerequisite check (latest 2.8.x with all migrations applied), then doctrine:migrations:rollup for upgraders (rewrites doctrine_migration_versions without re-running SQL). Fresh installs continue to use doctrine:migrations:migrate.
• CHANGELOG entries under [Unreleased] for the consolidation and the deprecated-fields preservation.

Why diff and not dump-schema

doctrine:migrations:dump-schema produces a migration with zero FK constraints in this stack — only CREATE TABLE with inline indexes. migrations:diff against an empty DB produces the full schema including all 96 FK clauses.

Why entity restoration instead of an ignore-listener

An earlier iteration used a postGenerateSchemaTable listener to inject the deferred columns into the entity-side schema, with the entity left untouched. That kept schema:validate clean but broke INSERTs:

• Fresh installs: fixtures couldn't INSERT templates (Field 'resources' doesn't have a default value).
• Upgraders: would hit the same error the moment anyone ran app:templates:install, since rollup doesn't change schema.

The columns aren't truly dead — they're NOT NULL with no DB default. Restoring the entity properties (with their PHP-level defaults) makes Doctrine emit a value on every INSERT, fixing both populations uniformly.

Test plan

• Fresh install end-to-end: drop test DB → create → migrations:migrate → schema:validate exits 0
• 2.x → 3.0 upgrade simulation: applied 25 latest-2.8.x migrations to fresh DB → replaced migration files with consolidated only → migrations:rollup → migrations:status reports 1 executed / 1 available / 0 unavailable → schema:validate exits 0
• Full PHPUnit suite: 155 tests / 637 assertions green (post-release/3.0.0 sync brought in 6 new InstantBook tests)
• PHPStan: no new errors
• OpenAPI spec stays in sync after Template entity restoration (composer update-api-spec produces no diff)
• Regenerated migration's DDL diff against the pre-feat: prep db identifiers for cross-platform (Postgres) portability #444 form is exactly the 15 index renames + 4 `user` quotings, nothing else
• CI green on this push
• Reviewer to verify the consolidated migration's DDL matches expectations against a real 2.8-final snapshot if available

Follow-up for 3.1

The three deprecated Template properties, the template.search_filter service, and the column-drop migration must land together in 3.1 — all carry TODO[3.1] markers. Removing one without the others would either re-introduce the schema mismatch (column without entity property) or the INSERT failure (entity expects the property gone but column still required).

🤖 Generated with Claude Code

[github-actions]

API specification not up to date

The committed API specification files do not match the exported output.

Please run the following command, then commit and push the changes:

docker compose exec phpfpm composer update-api-spec