Sulu Webspace Settings Bundle Laravel Package

Getting Started

The only required step after upgrading to v1.0.2 is rebuilding the admin frontend:

composer update
bin/adminconsole sulu:admin:update-build

Skipping the rebuild is the most common cause of "the fix didn't apply" reports — the PHP side is updated but the admin JS bundle still serves the old toolbar behaviour.

Where to look first:

1. Settings → toolbar — open any settings area and confirm two things: the dropdown marks the currently open area, and the area's group is highlighted in the toolbar. This is the visible feature of this release and the easiest smoke test.
2. Your settings templates — grep your Twig templates for setting lookups that traverse into a related object (e.g. setting.content.title, setting.media.url). These are the calls affected by the null resolution change.
3. Your PHP callers — the same applies anywhere you call a settings accessor (get(...)) and immediately dereference the result.

A good first use case: pick the settings area you use most (snippets, contacts, or whatever your app stores per-locale), open it, switch locale, re-select the same area, and confirm the locale sticks and no "copy from another locale" dialog is triggered.

Implementation Patterns

Treat the admin rebuild as part of deploy, not part of local setup. Add sulu:admin:update-build to your release/deploy script (after composer install --no-dev) so CI and production never drift from the PHP code. Locally, run it whenever you composer update and touch anything admin-facing.

Null-guard settings that point at content. With v1.0.2 a setting referencing deleted content resolves to null rather than a broken object. Make that explicit rather than accidental:

{% set content = setting('hero_content') %}
{% if content is not null %}
    <h1>{{ content.title }}</h1>
{% endif %}

In PHP, check before chaining:

$content = $this->settings->get('hero_content');

return $content?->getTitle();

Where a fallback is reasonable, prefer Twig's default filter for scalars, but keep the null check for objects — default will not stop a null dereference on a property access chain.

Area + locale is the unit of work, not area alone. Because a setting is effectively scoped by area and locale, keep any custom code that reads settings locale-aware: pass the current locale explicitly instead of relying on the ambient admin state, especially in background jobs, console commands, and API endpoints where there is no admin session.

Group your areas consistently. The new toolbar highlights the group the open area belongs to, so grouping is now user-visible navigation rather than internal metadata. When registering areas, keep group names stable and human-readable; renaming a group is a cosmetic-looking change that users will notice in the toolbar and in the dropdown.

Rebuild-and-verify workflow for UI changes. When touching settings templates or area configuration, run the update-build command, then verify in the browser with a hard reload. Do not trust a stale tab.

Gotchas and Tips

• The null change is behavioural, not cosmetic. Anything that assumed a settings reference always returned an object — a Twig property access, a get() chain, a type hint like ContentInterface $content — can now blow up where it previously "worked" with stale data. Search for non-nullable parameters and return types around settings resolution.
• Failures surface as Twig errors, not settings errors. A null dereference in a settings template typically manifests as a Twig runtime error on a page you did not touch. When debugging an unexpected template error after this update, check whether a setting points at deleted content before hunting in the template itself.
• Deleting referenced content leaves dangling settings. The new behaviour makes dangling references survivable but does not clean them up. Consider a periodic audit listing settings whose values resolve to null so editors can repoint or clear them deliberately.
• Locale loss on re-selection is fixed — test for the regression. Because re-selecting the open area previously dropped the locale and triggered the "copy from another locale" dialog, it is worth a quick manual check (and an acceptance test if you have one) that re-selecting the open area preserves the locale and shows no dialog. It is easy to reintroduce if you customise area switching.
• Cache. After settings or area configuration changes, clear the application cache alongside the admin rebuild; the toolbar's area/group metadata can otherwise appear out of date.
• Extension points. Area registration and its group assignment is the supported place to hook in custom settings screens — prefer registering a proper area over patching toolbar templates, so the highlight and dropdown markers keep working for your custom screens for free.
• Version pinning. Pin to ^1.0.2 as a floor if you rely on the null-safe resolution; code written against it is fine on older versions only if you already guard manually, and the toolbar behaviour will simply differ.