Sulu 3.0: Faster content storage, simplified dependencies, and a cleaner developer experience

When we first chose PHPCR (PHP Content Repository) for Sulu’s content storage, it wasn’t a mistake. PHPCR provided exactly what we needed: built-in support for hierarchical content, multilingual capabilities, versioning, and referencing. It solved complex content management problems out of the box.

But the web development landscape evolved. Database support for JSON fields matured. Doctrine ORM became more sophisticated. Most importantly, we realized that requiring developers to learn PHPCR’s SQL2 query language and unfamiliar concepts was creating unnecessary friction. Every new Symfony developer joining a Sulu project had to learn not just our CMS, but an entirely different way of thinking about data storage.

Our new content storage system uses JSON fields within your existing relational database, managed through Doctrine ORM entities. Instead of storing content in PHPCR’s XML-based format, everything now lives as structured JSON alongside your regular database tables.

Here’s what this means practically: Pages, articles, and snippets are now standard Doctrine entities. You can write regular SQL or DQL queries to analyze your content, debug issues by looking directly at database tables, and use the Doctrine tools you already know.

The new system introduces “dimensions” to handle the complexity of multilingual, versioned, and draftable content. Each piece of content can exist in multiple dimensions simultaneously—different languages, different publication stages, and different versions. The system automatically merges the right dimensions when rendering content, so a German page can inherit non-translatable data from the base dimension while displaying German-specific content.

For developers wanting deeper technical details, check out Alexander Schranz’s presentation From Translations to Multi-Dimension Entities, which walks through the architecture in detail.

The performance gains are substantial. Our benchmarks show roughly double the throughput and half the latency compared to PHPCR-based storage. But speed isn’t the only benefit: the developer experience has improved dramatically because everything uses familiar Doctrine patterns.

Debugging is now straightforward. When something goes wrong, you can examine the actual database tables, write test queries in SQL, and use standard database tools to understand what’s happening. Content structure and metadata live in your Git repository as XML configuration files, not buried in database schemas.

We’ve updated Flysystem from version 1 to version 3, which brings support for significantly more storage adapters. Previously, you were limited to local filesystem, AWS S3, Azure, and Google Cloud. Now you can use any adapter that Flysystem supports, including FTP, SFTP, WebDAV, MongoDB GridFS, and numerous third-party options like Dropbox, OneDrive, and various CDN providers.

This change eliminates a major deployment constraint. Whether you’re running on traditional hosting, cloud platforms, or hybrid environments, you can now store media files wherever makes sense for your infrastructure and budget.

All bundles that depended on PHPCR have been completely rewritten from scratch. This includes the Page, Article, Snippet, and CustomURL bundles. While this means more upgrade work for existing projects, it also means these bundles now follow modern Symfony practices and integrate seamlessly with the new storage system.

If you use classes from Jackalope, PHPCR Document Manager, or the old content bundles directly in your custom code, you’ll need to refactor those areas.

One of the most requested changes was making the Article bundle work without Elasticsearch. Previously, the bundle was built specifically for high-volume publishing scenarios where Elasticsearch was essential for performance. This made sense for the original use case, but it created a barrier for smaller projects or teams that didn’t want to manage an additional service.

The new Article bundle works perfectly with just your database. For projects that do need Elasticsearch’s advanced search capabilities, we’ve created the separate SuluArticleViewDocumentBundle that provides the same Elasticsearch integration as before.

We’ve replaced Sulu’s internal search system with SEAL (Search Engine Abstraction Layer), a collaborative project that provides unified access to multiple search engines. SEAL works similarly to how Doctrine abstracts databases or Flysystem abstracts file storage: it gives you one consistent API that works with Elasticsearch, Meilisearch, Algolia, Solr, and other search engines.

By default, Sulu 3.0 uses Loupe as the search adapter. Loupe is a PHP-only search engine that uses SQLite, created by Yanick Witschi (Toflar) from the Contao CMS project. It provides typo tolerance, phrase search, filtering, and geo support without requiring any additional services. For most Sulu installations, Loupe eliminates the need to run separate search infrastructure while still providing a much better search experience than basic SQL queries.

If your project outgrows Loupe’s capabilities (it handles up to about 50,000 documents efficiently), switching to Meilisearch, Elasticsearch, or other SEAL-supported engines requires only a configuration change.

With the release of Sulu 3.0, our version landscape has evolved. Sulu 1.6 has officially reached end of life, meaning it no longer receives any updates or security patches — if you’re still running a 1.x installation, now is the time to plan your migration path. 

Sulu 2.6 is now our long-term support release, receiving security updates and critical bug fixes until Sulu 4.0 arrives. This gives teams a stable, well-maintained foundation while they evaluate their timeline for moving to the new architecture. Sulu 3.0, meanwhile, is our actively maintained current version, receiving regular updates, new features, and ongoing improvements.

Upgrading to Sulu 3.0 requires more work than typical minor version updates, but we’ve built tools to handle the most complex parts automatically.

The Sulu PHPCR Migration Bundle handles converting your existing PHPCR content to the new storage format. This includes all your pages, articles, snippets, and custom URL data. The migration process preserves your content structure and translations.

The migration runs as a console command that you can test on development environments before running in production. It provides detailed logging so you can verify that all your content has transferred correctly.

For complex migrations or custom integrations, our development services team can help assess your specific situation and handle the upgrade process. We also offer architecture reviews and consulting to help plan your migration strategy.

Our community support channels remain active as always. Join our Slack channel for real-time help, or use GitHub Discussions for longer-form questions. The Sulu community has extensive experience with migrations and is eager to help fellow developers navigate the upgrade process.