Helper
A comprehensive development helper module providing utility services, Drush commands, and development tools for working with configuration, entities, menus, themes, Layout Builder, and more.
helper
Install
composer require 'drupal/helper:8.x-1.40'
composer require 'drupal/helper:8.x-1.39'
Overview
The Helper module provides a collection of utility services and development tools that simplify common Drupal development tasks. It offers a wide range of helper classes and services for working with configuration management, entity operations, menu building, theme management, Layout Builder, text formats, file handling, and more.
This module is particularly useful for developers who need reusable utility functions for batch updates of content entities, configuration import/export, install profile switching, plugin management, and various array/HTML/render element operations. It also provides additional Drush commands for cache management and module schema version control, as well as integration with Admin Toolbar Tools for quick cache clearing operations.
The module includes validation constraints for ensuring unique field values, a logging mail backend for development/testing, form elements for entity selection, and blocks for rendering node fields. It also adds theme inheritance features allowing sub-themes to inherit regions from their base themes.
Features
- Configuration helper service for importing, exporting, and managing both simple config and config entities with support for module and directory-based operations
- Content entity batch updater utility class for efficiently processing large numbers of entities in post-update hooks with error handling and progress tracking
- Install profile switching service with validation of dependencies, requirements, and extension availability before switching profiles
- Menu helper service for building menus programmatically, converting link fields to menu structures, and managing menu item attributes
- Theme helper service for checking active/default themes, managing base theme inheritance, and programmatically setting the default theme
- Layout Builder helper service for checking entity layout status, managing overridden layouts, and extracting layout plugins
- Text format helper service for adding/removing tags and attributes from filter_html restrictions
- File helper service for creating/reusing file entities and converting file URIs to data URIs
- Current entity service for detecting the current page entity from route matches including node previews, REST endpoints, and Layout Builder pages
- Entity type helper for generating entity options for select fields
- Plugin utility class for invoking plugin callbacks and generating plugin option lists
- Array helper with methods for value/key replacement, uniqueness checking, filtering, and even chunking
- Render element utilities for wrapping elements, attaching libraries, headers, feeds, and managing access
- HTML helper for removing HTML comments from markup
- Utility class for unique shutdown function registration, nested batch execution, and string CamelCase conversion
- Twig extension providing file_data_uri() function for embedding files as data URIs in templates
- Admin Toolbar Tools integration adding Flush PHP, Flush Libraries, and Flush Bootstrap menu items
- Drush commands for clearing libraries/bootstrap caches, switching install profiles, managing module schema versions, and resetting post-update hooks
- Node Field block for rendering any node field in block regions outside the content area
- Entity Select form element for creating select fields populated with entities of a specified type
- Validation constraints for ensuring unique values within entity fields
- Logger mail backend for capturing emails to the log instead of sending (useful for development/testing)
- JSON response classes for PSR-7 responses with automatic encoding
- JSON and Composer file helpers with caching support for reading/writing JSON data
- Config cache tag invalidator event subscriber for easy cache invalidation when config changes
- ValidatableConfigFormBase abstract class for creating config forms with typed config validation
- Sub-theme region inheritance feature allowing themes to inherit regions from base themes via inherit_regions flag
- Layout Builder inline block validation preventing inline blocks in default layouts to avoid content dependencies
- Core form HTML5 validation toggle for disabling novalidate attribute on forms
- Textarea widget enablement for text field types as an alternative to the textarea_widget_for_text module
- Core layout provider hiding for filtering out unwanted layout plugins by provider module
Use Cases
Batch update content entities in post_update hooks
Use ContentEntityUpdater to efficiently process large numbers of entities during database updates. The utility handles batching, error handling, and progress tracking automatically. Example: Updating all taxonomy term names to lowercase in a post_update function.
Programmatically import/export configuration
Use the helper.config service to import configuration from files or directories, export active configuration to files, or sync module configuration. Useful for deployment scripts, installation profiles, and configuration management workflows.
Switch install profiles without reinstalling
Use the install-profile:switch Drush command or helper.install_profile service to switch from one install profile to another. The validation ensures all dependencies are met and no extensions will be orphaned before switching.
Build menus from link fields
Use the helper.menu service to render link field values as navigational menus. This allows content editors to create menu-like navigation through link fields on entities.
Check and set the default theme programmatically
Use the helper.theme service in installation profiles or update hooks to check if a theme is active and programmatically set the default theme.
Modify text format allowed HTML tags
Use the helper.text_format service to programmatically add or remove allowed tags and attributes in text format configurations, useful during module installation or updates.
Create entity select form elements
Use the helper_entity_select form element to create select fields populated with entities of a specific type. Useful for configuration forms that need to reference entities.
Display node fields in block regions
Use the Node Field block to display any node field in block regions outside the normal content area. Useful for footer content, sidebars, or other regions that need to display node-specific data.
Sub-theme region inheritance
Add inherit_regions: true to a sub-theme's info.yml file to automatically inherit all regions from its base theme, avoiding the need to duplicate region definitions.
Development email logging
Configure the helper_logger mail plugin as the default mail backend to capture all emails to the database log instead of sending them. Useful for development and testing environments.
Reset post-update hooks for re-execution
Use the module:post-update:reset Drush command to reset a post-update hook that needs to run again. Useful for development and debugging update hooks.
Embed files as data URIs in Twig templates
Use the file_data_uri() Twig function to embed small files (like icons or logos) directly in templates as base64-encoded data URIs, reducing HTTP requests.
Tips
- Use ContentEntityUpdater for batch processing in post_update hooks - it handles batching, error recovery, and progress tracking automatically
- The helper.config service supports both simple config and config entities transparently - no need to handle them differently
- Set core_form_novalidate to true in helper.settings to disable HTML5 validation globally for easier debugging during development
- Use the helper_logger mail plugin during development to capture all emails to the log instead of sending them
- Add inherit_regions: true to sub-theme info.yml files to automatically inherit base theme regions
- The ContentEntityUpdater supports limiting to specific bundles using the format 'entity_type:bundle1:bundle2'
Technical Details
Admin Pages 3
/admin/flush/php
Clears PHP caches including opcache, APC cache, and file status cache. Only available when Admin Toolbar Tools module is installed.
/admin/flush/libraries
Clears the libraries cache and invalidates CSS/JS assets. Only available when Admin Toolbar Tools module is installed.
/admin/flush/bootstrap
Clears the Drupal bootstrap cache. Only available when Admin Toolbar Tools module is installed.
Hooks 1
hook_helper_current_entity_from_route_match_alter
Allows modules to alter the entity detected as the current page entity from the route match.
Drush Commands 8
drush cache:clear libraries
Clears the libraries cache and invalidates CSS/JS assets
drush cache:clear bootstrap
Clears the bootstrap cache
drush install-profile:switch
Switches the site from the current install profile to a new one. Validates dependencies and requirements before switching.
drush module:schema-version:get
Gets the current schema version for a module
drush module:schema-version:set
Sets the schema version for a module. Supports relative values like current+1 or current-3.
drush module:schema-version:delete
Deletes the schema version for a module. Useful for cleaning up leftover schemas of deleted modules.
drush module:schema-version:cleanup
Cleans up schema versions for modules that no longer exist
drush module:post-update:reset
Resets a post-update hook so it will run again on the next database update
Troubleshooting 3
Ensure all modules required by the new install profile are already installed before attempting to switch. Use the validateProfile() method to check requirements first.
This is a known issue with Drupal core for configuration entities. See https://www.drupal.org/project/drupal/issues/3367492 for a patch to resolve this.
The Flush PHP, Flush Libraries, and Flush Bootstrap routes only appear when the Admin Toolbar Tools module is installed and enabled.
Security Notes 3
- The install profile switch functionality should only be used by administrators with full system access
- The helper_logger mail plugin should only be used in development/testing environments as it exposes email content in logs
- The Composer file helper includes an exec() method that runs shell commands - ensure proper input escaping when using it