Backwards Compatibility Promise

Sulu is a stable software used in production. It is however still under heavy development and therefore a full backwards compatibility can not be guaranteed at the current stage.

We do our best to keep backwards compatibility for the most used extension points and services of Sulu. These are listed in this document.

The promises given in this document are only valid during a single major release. When a new major version is released, these promises might be broken.



The most important extension point is twig as its templates are used in any project using Sulu for content management. We guarantee that the variables passed to the twig template as described in Rendering Pages with Twig will keep their structure and that all the twig extensions as described in Twig Extensions will continue to work using the same calls.


There are several configuration files responsible for Sulu’s behaviour for which backwards compatibility is promised:


Using events for extending Sulu is quite common so we will keep backwards compatibility here. There might be new data added to some events but the current data will not be removed. The events are also guaranteed not to change names.


Using the Admin class together with its navigation is guaranteed not to break.

Content Types

It is safe to create custom content types by implementing the ContentTypeInterface or by inheriting one of the abstract SimpleContentType or ComplexContentType classes.

We also make sure that the content types delivered with Sulu will save the content in the same way so that there will not be any regressions with the content on an upgrade.

There will be migrations provided in case the structure of the content has to be changed in order to fix some bugs and the previous promise cannot be kept.

Sulu Classes and Interfaces

The following classes and interfaces are guaranteed to keep backwards compatibility:

  • DocumentManagerInterface

  • WebsiteController

  • RequestAnalyzerInterface

  • SecurityCheckerInterface

  • User

  • Contact

  • Category

  • Tag