The upgrade starts under Sulu 2: PHPCR migrations, check keys, remove the article bundle, clean up PHPCR. Then sulu/sulu:3.0.*, the new tables and sulu:phpcr-migration:migrate. After that you adapt templates and Twig. Date format, caches, bundle columns and legacy leftovers cost the most time.
Series 5: Sulu for developers Chapter 16 of 16
From Sulu 2 to Sulu 3
In short
Moving from Sulu 2.6 to Sulu 3 is a major upgrade with a tool of its own for the data. The instructions are in UPGRADE-3.x.md and in the official documentation. Here is the sequence in short form, plus what caused problems when moving the website bertrams-media. The website previously ran on Sulu 2.6.7 and has been live on Sulu 3.0.9 since 14/15 October 2026.
Helpful first: 5.1 Sulu 3 at a glance
Before the upgrade
The upgrade starts under Sulu 2:
- Install the latest 2.x versions of Sulu and its bundles and run all PHPCR migrations:
php bin/adminconsole phpcr:migrations:migrate. - Check the keys. Webspace, template and navigation keys are checked strictly: only
[a-z0-9_-]+, at most 31 characters. If they do not fit, change them beforehand by PHPCR migration or in the database. - If you have the
sulu/article-bundle, update it to the latest version first and make sure the migrationVersion202407111600has run. Then remove the bundle withcomposer remove sulu/article-bundle --no-scripts. Flex may deleteconfig/templates/articles/*in the process; restore the files from version control. - Clean up the PHPCR repository:
php bin/adminconsole sulu:document:phpcr-cleanup.
Installing Sulu 3
Then come the new packages and the data migration:
composer require sulu/sulu:"3.0.*" --no-scripts
# adapt config/bundles.php and the routes (see UPGRADE-3.x.md)
composer require sulu/phpcr-migration-bundle
php bin/adminconsole sulu:phpcr-migration:migrate
Before the command you need the new tables: run the Doctrine migrations of Sulu 3. Example SQL for this is in UPGRADE-3.x.md in the section “Add new Content storage tables”. You register the migration bundle in config/bundles.php and point it at the PHPCR repository in config/packages/sulu_phpcr_migration.yaml, in the example website with DSN: "dbal://default?workspace=default" and the target dbal (connection default). Anyone who used Jackrabbit takes a jackrabbit:// DSN. The command can be repeated: content that was already migrated is overwritten, not duplicated. Afterwards, set the permissions for articles and snippets in the admin and check that everything works.
Templates and Twig
These changes affect the code of the project:
- Address.
resource_locatorandrouteare now alwaysrouteand carry the nameurl. The title needs the tagsulu.rlp.partso that the admin suggests the address, and the address field needs the tagsulu.rlp. Make it a required field. - Article types become groups. What used to be in
sulu_article.typesis now in the element<group>of the template (see “Articles in Sulu 3”). - Twig functions.
sulu_content_loadis split intosulu_page_loadandsulu_article_load, and the parameterpropertiesis required. Navigation is calledsulu_page_navigation_*(see “Page templates”). - Search. The MassiveSearchBundle is gone, search runs on SEAL (see “Search in Sulu 3”).
- Document manager. It no longer exists. You change content by message (see “Sulu 3 at a glance”).
<property name="title" type="text_line" mandatory="true">
<tag name="sulu.rlp.part"/>
</property>
<property name="url" type="route" mandatory="true">
<tag name="sulu.rlp"/>
</property>
Stumbling blocks after the data migration
The data is migrated, the site runs, and yet some things are not right. This is what we found during the move:
- Empty date fields. The
DatePropertyResolveraccepts only the formatY-m-dfor the field typedate. If the value held a timestamp such as2022-10-24T00:00:00+00:00, it returnednull. The value has to be corrected in the data itself (in our case in 24 rows). - Old template cache. An outdated, compiled cache still asked for the old field. After the move, clear both caches, and with Apache the OPcache.
- Bundle columns. The table of the testimonial settings still had
idUsersCreatorandidUsersChanger, while the bundle expectedcreator_idandchanger_id. The admin showed the error “Unknown column 't0.creator_id'”. A targeted Doctrine migration solved it, notschema:update. - Empty legacy blocks. A page with empty blocks of the old type
heading-and-textthrew an exception in theBlockPropertyResolver. We only removed the empty blocks, after a backup. - Old Composer script. The script
massive:search:initwas still in theauto-scriptsof thecomposer.json. It should be removed, because the MassiveSearchBundle no longer exists. - Schema differences. After the move,
doctrine:schema:update --dump-sqllisted 83 statements. Many concerned legacy tables kept on purpose and suggestions to drop. Do not run this across the board with--force. Sort every statement: dangerous cleanup, harmless difference in naming or necessary migration.
The example website has only kept doctrine_migrations_versions since the beginning of October 2026. While preparing for go-live, 19 migrations counted as “not migrated” although their effect was already in the database. We registered them with doctrine:migrations:version --add and never ran migrate, because one of them cannot be reversed.
Onto the server
The migrations in the project do not fully reproduce the data transfer from Sulu 2. At go-live, a checked database dump was therefore taken over, without the phpcr_* tables, and the server got a new database in a new folder. That kept the way back open through the domain target. The procedure for follow-up deploys is described in “Deploying and updating”. After switching over, check what is running live: the header X-Generator of the response names the Sulu version.