restruct / silverstripe-admintweaks
Small CMS and developer improvements for Silverstripe 6: a system switcher with environment badge, page-type icons, permission codes, ModelAdmin and form-field opt-ins, template helpers, deduplicated error mails and asset repair tasks
Package info
github.com/restruct/silverstripe-admintweaks
Type:silverstripe-vendormodule
pkg:composer/restruct/silverstripe-admintweaks
Requires
- php: ^8.3
- guzzlehttp/guzzle: ^7.0
- silverstripe/framework: ^6
- silverstripe/vendor-plugin: ^3
Requires (Dev)
Suggests
- axllent/silverstripe-cms-tweaks: Some complemental tweaks by Axllent
- restruct/silverstripe-favicons: Generates favicon, touch icon and web manifest variants from one PNG (falls back to the admintweaks FavIcon)
- restruct/silverstripe-login-branding: Reduce Silverstripe branding of the admin login and make it easily configurable
- silverstripe/htmleditor-tinymce: The TinyMCE HTML editor (separate from framework since Silverstripe 6); needed for the minimal editor config
- silverstripe/lumberjack: Needed for SelectiveLumberjack and GridFieldSiteTreeAddNewButton
- symbiote/silverstripe-gridfieldextensions: Needed for GridFieldConfigs, GridFieldConfig_VersionedOrderable and the editable GridField fixes
- symbiote/silverstripe-grouped-cms-menu: Group CMS menu items into nested lists
- symbiote/silverstripe-multivaluefield: Needed for MultivalueSortField (a sort-only MultiValueDropdownField)
- wedevelopnl/silverstripe-webp-images: WEBP image support (output resized jpeg/png images as webp, GD with WEBP required; no Silverstripe 6 release yet as of 2026-10)
Provides
None
Conflicts
None
Replaces
- micschk/silverstripe-cmstweaks: 1.*
- restruct/silverstripe-cmstweaks: *
- dev-main
- 4.12.1
- 4.12.0
- 4.11.0
- 4.10.0
- 4.9.1
- 4.9.0
- 4.8.0
- 4.7.2
- 4.7.1
- 4.7.0
- 4.6.0
- 4.5.0
- 4.4.2
- 4.4.1
- 4.4.0
- 4.3.2
- 4.3.1
- 4.3.0
- 4.2.1
- 4.2.0
- 4.1.3
- 4.1.2
- 4.1.1
- 4.1.0
- 4.0.2
- 4.0.1
- 4.0.0
- v3.x-dev
- 3.31.1
- 3.31.0
- 3.30.0
- 3.29.0
- 3.28.1
- 3.28.0
- 3.27.0
- 3.26.2
- 3.26.1
- 3.26.0
- 3.25.0
- 3.24.0
- 3.23.2
- 3.23.1
- 3.23.0
- 3.22.1
- 3.22.0
- 3.21.1
- 3.21.0
- 3.20.8
- 3.20.7
- 3.20.6
- 3.20.5
- 3.20.4
- 3.20.3
- 3.20.2
- 3.20.1
- 3.20.0
- 3.19.0
- 3.18.0
- 3.17.1
- 3.17.0
- 3.16.0
- 3.15.0
- 3.14.0
- 3.13.0
- 3.12.0
- 3.11.1
- 3.11.0
- 3.10.0
- 3.9.0
- 3.8.1
- 3.8.0
- 3.7.1
- 3.7.0
- 3.6.3
- 3.6.2
- 3.6.1
- 3.6.0
- 3.5.0
- 3.4.2
- 3.4.1
- 3.4.0
- 3.3.2
- 3.3.1
- 3.3.0
- 3.2.0
- 3.1.0
- 3.0.x-dev
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- v2.x-dev
- 2.4.0
- 2.3.3
- 2.3.2
- 2.3.1
- 2.2.16
- 2.2.15
- 2.2.14
- 2.2.13
- 2.2.12
- 2.2.11
- 2.2.10
- 2.2.9
- 2.2.8
- 2.2.7
- 2.2.6
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2
- 2.1.15
- 2.1.14
- 2.1.13
- 2.1.12
- 2.1.11
- 2.1.10
- 2.1.9
- 2.1.8
- 2.1.7
- 2.1.6
- 2.1.5
- 2.1.4
- 2.1.3
- 1.2
- 1.1
- 1.0
- dev-docs/error-email-env
- dev-archive/ss6-attempt-2025-10
This package is auto-updated.
Last update: 2026-11-19 16:00:25 UTC
README
The small CMS and developer improvements most Silverstripe projects end up writing for themselves, in one module: a switcher that names the CMS and environment you are in and links to your other CMSes, page-type icons in the site tree, permission codes next to every permission checkbox, compact editable GridFields, a toggle switch for checkboxes, a breached-password check, opt-in ModelAdmin and form-field tweaks, template helpers, deduplicated error mails, and repair tasks for a migrated asset store. A few sensible defaults apply on install; everything else is switched on per project. For Silverstripe 6 (the 3.x line covers Silverstripe 4 and 5).
Maintained by Restruct. If this module saves you time, you can support ongoing maintenance.
Namespace: Restruct\Silverstripe\AdminTweaks
Contents
- Requirements and versions
- Installation
- Features at a glance
- CMS interface
- GridField
- Form fields
- Security
- Email and error mails
- Templates, SiteConfig and helpers
- Assets and images
- Tasks
- QueuedJobs
- Configuration reference
- Building the front-end assets
- Tests
Requirements and versions
| Branch | Module version | Silverstripe | PHP | Status |
|---|---|---|---|---|
main |
4.x |
6 | 8.3+ | active development |
v3 |
3.x |
4, 5 | as Silverstripe requires | security and bug fixes until Silverstripe 5 EOL (April 2027) |
3.0 |
3.0 to 3.11.1 |
4, 5 | as Silverstripe requires | legacy, unmaintained: superseded by v3 from 3.12.0 |
v2 |
2.x |
4 | as Silverstripe requires | legacy, unmaintained: last release 2.4.0 |
composer.json on each branch is the source of truth for exact constraints. Upgrading from 3.x?
See UPGRADING.md: the CMS menu behaviour and the task invocations both changed.
Release history: CHANGELOG.md.
Some features build on other modules, which this module does not require. Install the ones you use:
| Module | Needed for |
|---|---|
symbiote/silverstripe-gridfieldextensions |
GridFieldConfigs, versioned ordering, the editable GridField fixes |
silverstripe/lumberjack |
SelectiveLumberjack, GridFieldSiteTreeAddNewButton |
silverstripe/htmleditor-tinymce |
the minimal HTML editor config |
symbiote/silverstripe-multivaluefield |
MultivalueSortField |
symbiote/silverstripe-queuedjobs |
the queued-job report recipient and job context in error mails |
Installation
composer require restruct/silverstripe-admintweaks:^4 # Silverstripe 6 composer require restruct/silverstripe-admintweaks:^3 # Silverstripe 4 / 5
Then flush and build the database (sake db:build --flush). The defaults
apply from then on; the rest is switched on in your project's config.
Features at a glance
| Area | Feature | On by default? | Details |
|---|---|---|---|
| CMS interface | System switcher between your CMSes, with an environment badge | no, configure | System switcher |
| Page-type icons in the site tree | yes | Icons | |
| Permission codes in the Security admin | yes | ||
| ModelAdmin: search open on load, CSV buttons and import off | no | ||
| Hide Reports and Campaigns | no | ||
| Bootstrap Icon classes for buttons | when a page type uses one | Icons | |
| Menu grouping under "Advanced Config" | with grouped-cms-menu | ||
| GridField | One record count, no empty title row | yes | GridField |
| Editable GridFields: compact rows, row click, unchecked boxes saved | yes | GridField | |
| Ready-made configs and components | no | GridField | |
| Form fields | Toggle switch for checkboxes | no | Form fields |
| CopyTextField with a copy button | no | Form fields | |
minimal HTML editor config |
no | Form fields | |
| More fields and extensions | no | Form fields | |
| Security | Password policy | yes | Security |
| Breached passwords refused (Have I Been Pwned) | on live | Security | |
EnforceCMSPermission trait |
no | Security | |
| Error mails with request details and deduplication | when env vars are set | Email and error mails | |
| Templates | Template helpers, iterators, image placeholders | yes | Template helpers |
| SiteConfig fields | no | SiteConfig | |
| Cached HTTP requests | no | Caching and helpers | |
| Assets | File::getLocalPath(), image method fallbacks |
yes | Asset path resolution |
| Tasks | Repair a migrated asset store, query the ORM | run by hand | Tasks |
CMS interface
System switcher
For organisations running several Silverstripe CMSes side by side: the admin menu header names the
CMS you are in, with a badge for the environment, and opens a dropdown with links to the other
CMSes (screenshot at the top). Off until systems is configured:
Restruct\Silverstripe\AdminTweaks\SystemSwitcher: current: site systems: site: { display: 'Example SITE', url: 'https://www.example.org/admin' } docs: { display: 'Example DOCS', url: 'https://docs.example.org/admin' }
Per-environment URLs, the badge, initials in the collapsed menu and the browser tab title: System switcher.
Page icons
Every page type gets an icon in the site tree and the "Add page" picker: icons for common page types (Bootstrap Icons as inline SVG, no font files), and a default page icon for every other type. A page type can pick any Bootstrap Icon itself:
App\Pages\FooPortal: cms_icon_class: 'bi-briefcase'
On by default; SilverStripe\Admin\LeftAndMain.page_icons: false keeps core's page icons. The list
of page types, custom SVG icons and the Silverstripe 5 to 6 rename of icon_class:
Icons.
Permission badges
In the Security admin, every permission checkbox on a group shows its permission code, so similarly named permissions can be told apart. Always on.
ModelAdmin: search open, CSV buttons off
Two opt-in settings on any ModelAdmin subclass:
class ProductAdmin extends ModelAdmin { // Open the GridField search bar on load instead of hiding it behind the magnifier icon private static bool $auto_expand_gridfield_search = true; // Hide the scaffolded Export to CSV, Print and Import CSV buttons, and switch the import off private static bool $hide_scaffolded_csv_buttons = true; }
The scaffolded export just dumps the summary fields, and the default CsvBulkLoader import is a
data-integrity risk on synced or managed models. hide_scaffolded_csv_buttons also switches the
CSV import itself off ($showImportForm = false), not only its button: without that, ModelAdmin
keeps accepting a hand-built import POST. To apply it to every ModelAdmin:
SilverStripe\Admin\ModelAdmin: hide_scaffolded_csv_buttons: true # SecurityAdmin is a ModelAdmin too; keep its member/group CSV import if you use it SilverStripe\Admin\SecurityAdmin: hide_scaffolded_csv_buttons: false
Hide the Reports and Campaigns sections
Opt-in since 4.1 (#54), and
applied at runtime, so no After: ordering is needed to override it:
SilverStripe\Admin\LeftAndMain: hide_rarely_used_menu_sections: true
The sections keep working at their URLs; only the menu items go. While the setting is unset, dev
environments log a one-off notice about the change from 3.x; set it to false to keep the sections
and silence the notice. See UPGRADING.md.
Bootstrap Icon classes
Standard bi bi-* classes for buttons and other admin UI, mirroring core's .font-icon-*
pattern. The Bootstrap Icons stylesheet loads from a CDN by itself once a page type uses a bi-*
icon class; include_bootstrap_icons: true always loads it, false never does:
SilverStripe\Admin\LeftAndMain: include_bootstrap_icons: true
FormAction::create('add', 'Add Item')->addExtraClass('bi bi-plus-circle');
The CDN URL and icon-only buttons: Icons.
Menu grouping
With symbiote/silverstripe-grouped-cms-menu installed, the configuration sections (Settings,
Archive, Redirects, Subsites, Queued Jobs and restruct/silverstripe-blockbase's blocks admin, those
that are installed) are grouped under "Advanced Config" in the menu. Nothing to configure.
Smaller fixes
Always on, CSS only unless noted:
- Uploaded images with transparency show on a light checkerboard in upload fields.
- Form inputs use near-black text instead of the admin's grey.
- Elemental blocks lose the faux "stacked" layout, and Elemental's popover is wide enough.
- A JavaScript workaround stops the admin's entwine layer from aborting on HTML comments in pjax-loaded forms, which could leave some fields (HTML editors, for example) uninitialised.
GridField
In every GridField
GridFieldPageCount is removed from the GridField configs, so "View 1-3 of 3" shows once, in the
footer, and the title row that held it is hidden while it is empty. Checkbox sets in the "Search
options" popover no longer overlap, and long option lists scroll. Details:
GridField.
Editable GridFields
For GridFields with gridfieldextensions' GridFieldEditableColumns, on install:
- Compact rows: fields no longer bring Bootstrap's form spacing into the row, and cells line up on their first line.
- A click on the row opens the record, as in any other GridField; a click inside a field's cell stays with the field.
- Unticking a checkbox is saved: an unticked box posts an empty value instead of nothing.
How each works, and a toggle switch in a column: GridField.
GridField configs and components
use Restruct\Silverstripe\AdminTweaks\Forms\GridFieldConfigs; // Inline editing with drag-and-drop ordering $config = GridFieldConfigs::editable_orderable(); // Sorting, filtering and ordering, with the usual detail form $config = GridFieldConfigs::filterable_orderable_recordeditor();
Also: GridFieldConfig_VersionedOrderable (ordering of versioned records written to live at
once), SelectiveLumberjack (hide only the child page types you list from the site tree),
GridFieldSiteTreeAddNewButton and SortableExtension. All in GridField.
Form fields
Toggle switch
Draws a checkbox as a switch like the admin's own. CSS only: the checkbox stays a checkbox for the keyboard, screen readers and the form value.
CheckboxField::create('Active')->setToggleSwitch(); CheckboxSetField::create('Channels', 'Channels', $options)->setToggleSwitch();
setToggleSwitch() is a shorthand for addExtraClass('toggle-switch'). Disabled switches are
faded. setToggleSwitchInverted() shows the switch ON while the box is unchecked, for a stored
negative flag ("Hidden"); display only, so screen readers still announce the real state. In an editable GridField column, read-only behaviour and the CSS custom properties for size
and colour: Form fields.
CopyTextField
A read-only field with a copy-to-clipboard button, which turns green with a check for two seconds after copying.
use Restruct\Silverstripe\AdminTweaks\FormFields\CopyTextField; CopyTextField::create('ApiKey', 'API Key', $apiKey)->setButtonLabel('Copy');
All options: Form fields.
Minimal HTML editor config
An HTML editor config named minimal for short rich-text fields: one toolbar line with bold,
italic, bullet and numbered lists, links and "clear formatting". It is a copy of the cms config,
so the link dialogs work. Needs silverstripe/htmleditor-tinymce.
use Restruct\Silverstripe\AdminTweaks\Forms\MinimalEditorConfig; HTMLEditorField::create('Answer')->setEditorConfig(MinimalEditorConfig::get());
Changing the toolbar and allowing more HTML: Form fields.
More form fields
- MultivalueSortField: drag-and-drop sorting of a fixed set of options (needs
symbiote/silverstripe-multivaluefield). - IpAddressField: a text field that only accepts an IPv4 or IPv6 address.
- FormFieldBootstrapExtension (opt-in): Bootstrap's
form-control,form-selectandform-checkclasses on front-end form fields. - FormFieldTweaksExtension (opt-in): attributes on a field's holder, Bootstrap validation classes, and a floating-label holder template.
All in Form fields.
Security
Password policy
Core's RulesPasswordValidator with minimum length 12, a history of 6 and a minimum test score of
3 on live; minimum length 5 and no history check on dev and test, so a local admin:admin works.
How to change it: Security.
Breached passwords
On live, a new password that occurs in the Have I Been Pwned breach data is refused. Only the first 5 characters of the password's SHA-1 hash are sent (k-anonymity), and when the lookup fails the password is accepted and a warning logged. Off on dev and test. Opt in to also expire a breached password a member logs in with, so they must choose a new one:
Restruct\Silverstripe\AdminTweaks\Security\BreachedPasswords: expire_on_login: true
All settings: Security.
EnforceCMSPermission
A trait that ties a DataObject's canView, canEdit, canDelete and canCreate to Pages
section access (CMS_ACCESS_CMSMain) of the current user:
class MyDataObject extends DataObject { use \Restruct\Silverstripe\AdminTweaks\Traits\EnforceCMSPermission; }
Note that it ignores the $member argument: Security.
Email and error mails
Set in .env; each part switches on only when its variables are set.
# Default sender (Email.admin_email), when the project has not set one APP_SYSTEM_EMAIL_SENDER="My App" APP_SYSTEM_EMAIL_ADDRESS="noreply@example.com" # Error mails, only when all four are set: leave them out on dev and test APP_LOG_MAIL_RECIPIENT="admin@example.com" APP_LOG_MAIL_SUBJECT="Error on MyApp" APP_LOG_MAIL_SENDER="noreply@example.com" APP_LOG_MAIL_LEVEL="error"
Error mails carry the request and server details. The same error is mailed once per 5 minutes and
at most 20 error mails go out per hour, so an outage does not flood the inbox. SMTP is configured
with Symfony Mailer's MAILER_DSN; the APP_SMTP_* variables of the 3.x line do nothing here.
Formatter, limits and troubleshooting: Email and error mails.
Templates, SiteConfig and helpers
Template helpers
Available in every template, on install:
<% if $IsDev %>Debug mode<% end_if %> <% include ImagePlaceholder W=180, H=50, Label='logo' %> <video src="{$themeDirResourceURL('my-theme')}/video.mp4"></video> <% loop $Items %> <div class="col-{$GroupSize}-of-4">$Title</div> <% end_loop %>
Page helpers, iterators, date and time formatting, shortcodes: Template helpers.
SiteConfig fields
Opt-in fields for contact details, social media, a browser theme colour, raw HTML in head and body, logos and theme settings:
SilverStripe\SiteConfig\SiteConfig: extensions: - Restruct\Silverstripe\AdminTweaks\Extensions\SiteConfigExtension enable_contact_social_media_fields: true enable_raw_head_body_fields: true
Every option: SiteConfig.
Cached HTTP requests
use Restruct\Silverstripe\AdminTweaks\Helpers\CacheHelpers; $data = CacheHelpers::cached_json_request('https://api.example.com/data', 'GET', [], 3600); $jsonLdBlocks = CacheHelpers::cached_jsonLD_request('https://example.com/product');
More, including GeneralHelpers: Caching and helpers.
Assets and images
$file->getLocalPath(): the absolute path of a file on a local disk (for command-line tools such aspdftotext), found the way the framework itself finds the file, protected store first. Returnsnullfor a file that is not on a local disk. Asset path resolution.- Image method fallbacks: while the FocusPoint module or Restruct's image cropper is not
installed, their template methods (
FocusFillMax,CroppedFocusedImageand others) fall back to core manipulations, and some Silverstripe 3 names (SetWidth,PaddedImage) still work. Caching and helpers. - Image quality 90; WEBP output and MIME upload validation switch on with their modules (see Applied on install).
GeneralHelpers::import_file_asset(): stores a downloaded URL or a local file as a File or Image. URLs go through the outbound URL checks; a local path orfile:URL is read only when the caller names the directory it must be in. Caching and helpers.
Tasks
Three dry-run-by-default tasks that repair asset artifacts left behind by a migration from Silverstripe 3 or 4 (folders that break the Files section, images stored as plain files, missing CMS thumbnails), and two developer tools:
sake tasks:fix-folder-filefilename --apply sake tasks:fix-misclassified-images --apply sake tasks:generate-cms-thumbnails --apply sake tasks:orm-query --class=Member --limit=5 sake tasks:focuspoint-invert-yaxis
What each fixes, the order to run them in, and the options: Tasks.
QueuedJobs
ScheduledMethodCall, the cleanup-broken-jobs task and the qjob-profile task moved to
restruct/silverstripe-queuedjobs-enhancements.
What this module still does for symbiote/silverstripe-queuedjobs: fill
Email.queued_job_admin_email from APP_LOG_MAIL_RECIPIENT when the project has not set it, and
name the running job in error mails from the queue runner
(Email and error mails).
Configuration reference
Applied on install
Session.cookie_secure: true: session cookies over HTTPS only.- UserDefinedForm submissions are not stored by default (
DisableSaveSubmissions), for GDPR. - Image backend quality 90 (
Image_Backend.Quality). - URL segments:
&becomes-et-instead of core's-and-(no other replacement changed). - The password policy and the breached-password check.
- Cache lifetimes:
cacheblock(template<% cached %>) 24 hours;appcacheandadminCache1 hour. - The page icons, permission badges, GridField and editable GridField changes described above.
- From env, only when the project has not set them:
Email.admin_emailandEmail.queued_job_admin_email(see Email and error mails).
With other modules installed
| Module | What happens |
|---|---|
symbiote/silverstripe-grouped-cms-menu |
Admin sections grouped under "Advanced Config" |
symbiote/silverstripe-queuedjobs |
Job context in error mails; report recipient from env |
wilr/silverstripe-googlesitemaps |
Sitemap enabled: 1000 objects per sitemap, Google and Bing notification on, honours ShowInSearch |
silverstripe/mimevalidator |
MIME upload validation active |
wedevelopnl/silverstripe-webp-images |
WEBP output at quality 80 (no Silverstripe 6 release of that module yet) |
restruct/silverstripe-shortcodable |
[currentyear] and [featuredimage] shortcodes registered |
Settings
| Class | Setting | Default | See |
|---|---|---|---|
SilverStripe\Admin\LeftAndMain |
page_icons |
true |
Page icons |
include_bootstrap_icons |
unset: when a page type uses a bi-* class |
Bootstrap Icon classes | |
bootstrap_icons_cdn_url |
jsDelivr, bootstrap-icons 1.13.1 | Icons | |
hide_rarely_used_menu_sections |
unset: shown, with a dev notice | Hide Reports and Campaigns | |
SilverStripe\Admin\ModelAdmin |
auto_expand_gridfield_search |
false |
ModelAdmin |
hide_scaffolded_csv_buttons |
false |
ModelAdmin | |
Restruct\Silverstripe\AdminTweaks\SystemSwitcher |
current, systems, environment_suffixes |
off until systems is set |
System switcher |
Restruct\Silverstripe\AdminTweaks\Security\BreachedPasswords |
enabled |
true on live, false elsewhere |
Security |
min_breach_count |
1 |
Security | |
expire_on_login |
false |
Security | |
Restruct\Silverstripe\AdminTweaks\Forms\MinimalEditorConfig |
minimal_buttons, minimal_options |
one toolbar line | Form fields |
Restruct\Silverstripe\AdminTweaks\Logging\DedupSymfonyMailerHandler |
dedup_time, max_emails_per_window, rate_window |
300, 20, 3600 |
Email and error mails |
Restruct\Silverstripe\AdminTweaks\Logging\EnhancedErrorFormatter |
format_mode, server_vars |
html, a list of request keys |
Email and error mails |
SilverStripe\SiteConfig\SiteConfig |
enable_* and theme settings |
off | SiteConfig |
Building the front-end assets
The built CSS and JS in client/dist/ are committed, so installing the module needs no Node
tooling. To change them, edit client/src/ and rebuild with Vite, from a
checkout of the module (Node ^20.19 or >=22.12; the lockfile is yarn.lock):
yarn install yarn build # minified, what gets committed yarn dev # unminified, with inline source maps yarn watch # as dev, rebuilding on every change
build-assets.mjs holds the build configuration. The output names (client/dist/css/admintweaks.css,
client/dist/css/admintweaks-page-icons.css, client/dist/css/multivaluesortfield.css,
client/dist/js/admintweaks.js, and the FontAwesome webfonts in client/dist/fonts/) are fixed,
because the YAML config and the PHP load them by path. Commit client/src and client/dist
together, built with yarn build.
Tests
The PHPUnit suite in tests/ needs a Silverstripe 6 host project with
silverstripe/recipe-testing; .github/workflows/ci.yml builds one and is the reference.
Browser tests (Playwright, against a real CMS) live in tests/browser/ and run in
.github/workflows/browser-tests.yml. The screenshots in this README and in docs/ are generated
from the same fixtures; see tests/browser/screenshots/README.md
to regenerate them.
License
MIT, see LICENSE.





