Series 5: Sulu for developers Chapter 16 of 16

From Sulu 2 to Sulu 3

Development
Applies to: every Sulu website As of Sulu 3.0

In short

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.

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:

  1. Install the latest 2.x versions of Sulu and its bundles and run all PHPCR migrations: php bin/adminconsole phpcr:migrations:migrate.
  2. 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.
  3. If you have the sulu/article-bundle, update it to the latest version first and make sure the migration Version202407111600 has run. Then remove the bundle with composer remove sulu/article-bundle --no-scripts. Flex may delete config/templates/articles/* in the process; restore the files from version control.
  4. Clean up the PHPCR repository: php bin/adminconsole sulu:document:phpcr-cleanup.

Installing Sulu 3

Then come the new packages and the data migration:

From UPGRADE-3.x.md, in the order of the guide bash
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_locator and route are now always route and carry the name url. The title needs the tag sulu.rlp.part so that the admin suggests the address, and the address field needs the tag sulu.rlp. Make it a required field.
  • Article types become groups. What used to be in sulu_article.types is now in the element <group> of the template (see “Articles in Sulu 3”).
  • Twig functions. sulu_content_load is split into sulu_page_load and sulu_article_load, and the parameter properties is required. Navigation is called sulu_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”).
Address field of a template, following UPGRADE-3.x.md html
<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 DatePropertyResolver accepts only the format Y-m-d for the field type date. If the value held a timestamp such as 2022-10-24T00:00:00+00:00, it returned null. 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 idUsersCreator and idUsersChanger, while the bundle expected creator_id and changer_id. The admin showed the error “Unknown column 't0.creator_id'”. A targeted Doctrine migration solved it, not schema:update.
  • Empty legacy blocks. A page with empty blocks of the old type heading-and-text threw an exception in the BlockPropertyResolver. We only removed the empty blocks, after a backup.
  • Old Composer script. The script massive:search:init was still in the auto-scripts of the composer.json. It should be removed, because the MassiveSearchBundle no longer exists.
  • Schema differences. After the move, doctrine:schema:update --dump-sql listed 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.

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.

More on this

Official documentation