Sulu Webspace XML Compatibility: Upgrading from 2.5 to 3.2

Question

When moving a production Sulu instance from 2.5 to 3.2, the team must preserve the existing multi‑site configuration that lives in the webspace.xml files. These files define the base URL, supported locales, and theme mapping for each webspace.

In 3.2 the XML schema for locales and themes has been updated to support new features such as locale fallbacks and theme inheritance. The current configuration uses the legacy <locale> tags and a flat <theme> element, which may no longer be accepted by the new parser.

To avoid breaking the site, the team needs to understand:

Which parts of the XML structure are still valid in 3.2?
What concrete changes are required for the <locale> elements and theme definitions?
Is there an automated migration tool or script provided by Sulu to convert legacy webspace.xml files to the 3.2 format?

Tasadduq Burney · Answer

AnswerThe root element and its attributes (name, baseUrl, defaultLocale) remain unchanged and are fully supported in Sulu 3.2. Sections such as , , and can be copied as‑is.Confirmed factsLocale definitions must be wrapped in a collection.Each locale is expressed as ; the fallback attribute is optional and defaults to an empty string.Theme definitions shift from a flat element to a collection where each theme is ; the inherit attribute is optional and defaults to false.Likely explanationThe schema update introduces wrappers and attributes to support locale fallbacks and theme inheritance. Legacy flat tags are no longer recognized by the XML parser, so the structure must be adjusted while preserving the original values.Steps needed for this caseBackup the existing config/webspaces/ directory.Run the provided upgrade command: bin/adminconsole sulu:webspace:upgradeThis converts legacy files to the 3.2 format, adding the required wrappers and attributes.Clear the Symfony cache: bin/adminconsole cache:clearVerify the upgrade by inspecting a sample file for and wrappers and checking that attribute values match the original locale codes and theme names.Optionally validate the XML against the 3.2 XSD: xmllint --noout --schema vendor/sulu/sulu/resources/config/schema/webspace-3.2.xsd config/webspaces/your‑webspace.xmlFinally, use the admin console to list webspaces and confirm locales/themes appear correctly: bin/adminconsole sulu:webspace:list

Sulu Webspace XML Compatibility: Upgrading from 2.5 to 3.2

1 answer

Answer

Confirmed facts

Likely explanation

Steps needed for this case

Your perspective belongs here.

0 question comments