Download the PHP package eekes/sulu-webspace-settings-bundle without Composer

Sulu Webspace Settings Bundle

Compose per-webspace settings in Sulu 3 the way you compose page templates.

Declare a settings area — a PHP attribute plus a template XML — and editors get a form under Webspaces in the admin.

Requirements

• PHP 8.2+
• Sulu 3.0

Installation

Register the bundle in config/bundles.php:

Import the admin API routes in config/routes/sulu_admin.yaml:

Add the admin JavaScript to assets/admin/package.json:

Load it in assets/admin/app.js:

Rebuild the admin:

Create the database tables:

doctrine:migrations:diff writes a migration for every difference it finds, not just this bundle's two tables, so read the generated file before running it.

Reference rows are written on save, so existing records have none until they are saved. Run bin/adminconsole sulu:reference:refresh once after installing or upgrading, otherwise the HTTP cache is not invalidated when a setting changes.

Declaring an area

An area is one settings screen. The class is both the declaration and the typed read model.

The fields live in template XML, the same dialect page and snippet templates use, so every content type works unchanged:

That is the whole registration. No YAML, no service definition, no Doctrine entity.

Every unique group becomes one dropdown in the settings toolbar; areas that name none share a single Settings dropdown. icon is declared per area but drawn on the dropdown, so the first area of a group wins.

#[AsSettingsArea] is found through Symfony's attribute autoconfiguration, which only sees classes registered as services. In a stock Sulu project everything under src/ is — but an area under a path excluded from services.yaml, or in a bundle with autoconfigure: false, is silently never registered. If a new area does not show up, check that first, then clear the admin cache.

An area shipped inside a reusable bundle points at its own template directory from that bundle's prependExtension():

Reading settings

Reach for the typed model. raw() exists for tooling — migration, validation, diffing — and resolved() for templates that predate a typed model.

Inside a request the webspace and locale come from the request. Outside one — a command, a messenger handler — name the webspace yourself:

forWebspace() is mandatory outside a request: the bundle never falls back to "the first configured webspace", which would quietly serve another webspace's settings.

get() maps resolved values onto the constructor by parameter name, snake_case to camelCase. Giving a parameter a default makes the setting optional; leaving it required and never filling it in raises MissingSettingValueException. A value that does not fit the parameter's type raises SettingValueTypeMismatchException.

Twig

settings() is lazy: an area is resolved on the first property a template touches, once, and a template that never mentions an area costs nothing.

Four names are taken by methods on the returned object: get, view, all and count. A template property with one of those names still wins, but if no such property exists the method answers instead of null. Use settings('social')['count'] where that matters.

Reads are memoised for the process. Saving an area empties the memo for it, and kernel.reset empties it entirely, so messenger workers and worker runtimes pick up changes made elsewhere.

Translated and shared fields

Every field is stored per locale unless it opts out with Sulu's own multilingual attribute:

Such a property is stored once and read back in every locale. Mark every field of a template and the whole area is shared; mark none and it is fully translated; mix them and each field behaves as declared. Whether the admin shows a locale select is read from the template — an area counts as localized as soon as one of its fields is still multilingual.

Changing the attribute later does not move values that are already stored: they stay in the dimension they were written to until the area is saved again.

Permissions

Every webspace gets a sulu.webspaces.<webspace>.settings context, which gates the REST endpoints.

By default, as soon as a project declares more than one area, each area also gets sulu.webspaces.<webspace>.settings_<area>, so a client can be allowed to edit Social but not Integrations.

Going from one area to two changes the shape of the permission set. Roles that only carry the webspace context lose access on the deploy that adds the second area, until an administrator grants the new per-area permissions. If a project is likely to grow past one area, set permissions.per_area: always from the start and the set never moves.

Configuration

The bundle needs no configuration. These two things are configurable:

A bundle that ships its own areas adds a template directory through prependExtensionConfig('sulu_admin', ...), as shown above, rather than changing this one.

Maintenance

An area lives in code and a webspace in XML, so neither disappearing is something the bundle can notice — the records stay behind, invisible in the admin and still in the database:

License

MIT. See LICENSE.