Sulu 2.6.0 Release
Allow us to introduce you to the highly anticipated release of Sulu CMS 2.6! This update comes with an array of exciting features to enhance your experience. From enhanced authentication measures, to intuitive content management tools, to improving both user and developer experiences alike.
This Sulu release includes an impressive 100+ merged pull requests from 22 different contributors. A huge thank you to each and every one of them for their hard work in making Sulu an even better platform for building web applications and websites.
We love feedback! Feel free to contact us via GitHub, Slack, or the contact form on our website to chat with us about this release.
Reference Bundle
Let’s dive directly into the brand-new ReferenceBundle. As of 2.6, the bundle is an integral part of the Sulu core repository.
The goal of the new ReferenceBundle, as the name hints, is to automatically save references regarding where and how entities are used in Sulu. Currently, the bundle tracks the usage of Snippets and Media.
Media, as well as Snippet entities, have received a new References tab in their detail view. To avoid overloading the current tab bar, the References and Activities are grouped together on the Insights tab.
The References are displayed in a tree-table. You can easily navigate to the referenced entity, such as a page. Furthermore, you can see via the Context column whether the reference is only in draft or already published on the website. Additionally, the PropertyPath is displayed to quickly identify which block or content type is referencing it.
Sulu 2.6 also ships with a new console command to either initially scan your project for references, or refresh them if something gets out of sync.
sulu:reference:refresh
This command depends heavily on context, so you have to run it twice: via the adminconsole and also via the websiteconsole.
OIDC / OpenId Integration
This feature will be of particular interest for agencies that manage a lot of different Sulu instances. Via the new OpenId integration into the Sulu Admin, you can now use your Google Business, Azure AD, AWS Identity, or even a self hosted Keycloak as a Single SignOn provider. You can enable this new feature with the following configuration:
# config/packages/security.yaml
security:
firewalls:
# ...
admin:
# ...
access_token:
token_handler: sulu_security.single_sign_on_token_handler
token_extractors: sulu_security.single_sign_on_token_extractor
# config/packages/sulu_security.yaml
sulu_security:
single_sign_on:
providers:
'example.org':
dsn: 'openid://CLIENT_ID:CLIENT_SECRET@example.com/realms/master/.well-known/openid-configuration?no-tls=true' # no-tls = http instead of https
default_role_key: User
In the above example, all users with an email address ending with `@example.org` will automatically be redirected to the configured OpenId provider. You can define which role users will get on their first login via the default_role_key settings. For agencies and companies with a lot of Sulu websites, this feature is really recommended because you can disable and create users in a central Single SignOn provider and no longer need to manage users in all installations separately.
Global Blocks
Global blocks define a set of properties that can be used as a type inside of a block or any other property. This is useful if you want to reuse a block type in multiple templates.
To define a global block, you have to create a new XML file in the config/templates/blocks directory. The following file is an example and defines a global block with the name text_block:
<?xml version="1.0" ?>
<template xmlns="http://schemas.sulu.io/template/template"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">
<key>text_block</key>
<meta>
<title lang="en">Text Block</title>
<title lang="de">Text Block</title>
</meta>
<properties>
<property name="title" type="text_line" mandatory="true">
<meta>
<title lang="en">Title</title>
<title lang="de">Titel</title>
</meta>
</property>
<property name="description" type="text_editor">
<meta>
<title lang="en">Description</title>
<title lang="de">Beschreibung</title>
</meta>
</property>
</properties>
</template>
This block can be used in any other template by using the <block> or <property> element within the type node and the ref attribute:
<block name="blocks" default-type="text_block" minOccurs="0">
<types>
<!-- using global blocks and only referencing the block -->
<type ref="text_block" />
<!-- default definition of a block type without using global blocks -->
<type name="editor">
<meta>
<title lang="en">Editor</title>
<title lang="de">Editor</title>
</meta>
<properties>
<property name="text_editor" type="text_editor">
<meta>
<title lang="en">Text Editor</title>
<title lang="de">Texteditor</title>
</meta>
</property>
</properties>
</type>
</types>
</block>
PHPCR Cleanup Command
Initially proposed by mamazu on GitHub, the PHPCR Cleanup Command is expressly designed to optimize Sulu's content-repository. The command works by detecting and removing outdated properties that remain in the repository due to changes, refactors, or alterations to templates and block types.
To execute this command:
bin/console sulu:document:phpcr-cleanup
Remember, the PHPCR Cleanup Command is a powerful optimization tool that requires careful handling. The command has several important factors to note:
Optimization: It identifies and removes outdated properties resulting from alterations to templates and block types. This process helps to maintain an optimized and up-to-date content-repository.
Risk Management: Given the command's purpose to delete outdated properties, it's crucial that you perform a backup of the repository before using this command. This ensures protection against any unintended data loss.
Execution Time: The command is comprehensive and may require a significant amount of time to complete, depending on the extent of changes and the size of the repository.
Default snippet-area cache invalidation
Prior to Sulu 2.6, cache invalidation was not properly triggered when a snippet, serving as a default snippet for an area, was modified. Consequently, users were often compelled to either manually republish the specific site or initiate a full cache clear. To address this issue, Sulu 2.6 introduces a refined cache invalidation mechanism for snippet-areas when snippets are altered.
Additionally, a new property has been added to the snippet-area configuration. By default, cache invalidation is enabled for all explicitly configured snippet-areas. However, snippet-areas that are auto-generated by Sulu are not invalidated by default.
<areas>
<area key="menu_social_media_links" cache-invalidation="true">
<meta>
<title lang="en">Menu Social Media Links</title>
</meta>
</area>
<area key="footer_social_media_links" cache-invalidation="false">
<meta>
<title lang="en">Footer Social Media Links</title>
</meta>
</area>
</areas>
Please note that utilizing a default snippet in a base Twig template may lead to a complete cache invalidation of the website when either the snippet or the area is modified.
View Debug Command for SuluAdmin
The View Debug Command was added by TheCadien to enhance the development experience (Sulu/sulu#7283).
This command can be used to debug Sulu Admin Views:
bin/console sulu:admin:debug-view
To debug a single view, the name of the view can also be passed as an argument:
bin/console sulu:admin:debug-view sulu_page.page_edit_form.setting
Upgrade instructions
Upgrade to the latest version of Sulu 2.6.0 today! Here’s how to upgrade:
- Upgrade your project to PHP 8.2 (possibly using Rector)
- Upgrade your database to create the new schema for references,and register the new SuluReferenceBundle in the config/bundles.php with the new routes
- Now follow our Upgrading Sulu 2.x documentation to update your project to Sulu 2.6
- Fix any conflicting return types
- Change the PhpCRMigration namespace from DTL\Bundle\PhpcrMigrations to PHPCR\PhpcrMigrationsBundle
- Optional but recommended: Update to Symfony 6.4
- Optional but recommended: Update to Jackalope 2
