Configuration Split
Allows splitting site configuration into separate sets that can be exported to different directories, merged during import, and activated/deactivated per environment.
config_split
Install
composer require 'drupal/config_split:^2.0'
Overview
Configuration Split extends Drupal's configuration management system by allowing you to define sets of configuration that will be exported to separate storage locations (directories, collections, or database) when exporting, and merged together when importing. This enables environment-specific configuration management where development modules like Devel can be enabled on local environments but excluded from production deployments.
The module provides two types of splitting: Complete Split where configuration is entirely moved to the split storage and removed from the sync directory, and Partial Split where configuration remains in sync but differences are stored as patches in the split storage. Splits can be activated or deactivated via settings.php overrides or Drupal state, allowing flexible environment-specific behavior without modifying exported configuration.
Configuration Split integrates seamlessly with Drush commands for command-line operations and hooks into Drupal's configuration import/export events to transparently handle splitting and merging during standard config sync operations.
Features
- Complete split: Move configuration entirely to split storage, removing it from the main sync directory during export
- Partial split: Keep configuration in sync directory while storing only the differences as patches in split storage
- Multiple storage backends: Store split configuration in filesystem folders, config collections, or database tables
- Environment-specific activation: Enable/disable splits via settings.php overrides or Drupal state for per-environment control
- Module filtering: Automatically split all configuration related to specified modules, including dependent config
- Theme filtering: Split theme-specific configuration (currently limited)
- Wildcard support: Use wildcards (e.g., views.view.*) to match multiple configuration items for splitting
- Stackable splits: Create layered splits where higher-weight splits can modify configuration from lower-weight splits
- Config patching: Automatically update dependent configuration when modules are split off
- Drush integration: Full command-line support for export, import, activate, deactivate, and status override operations
- UI-based management: Web interface for creating, editing, and managing splits with preview capabilities
- Diff viewing: View differences between active configuration and split configuration before importing
- Integration with config_readonly: Automatic whitelisting of database split entries for config_readonly module
Use Cases
Development Module Management
Keep development modules like Devel, Kint, or Stage File Proxy enabled locally but excluded from production. Create a 'development' split, add these modules to the complete split, and activate the split via settings.php on development environments: $config['config_split.config_split.development']['status'] = TRUE;
Production-Only Configuration
Maintain production-specific settings like CDN integration, caching policies, or analytics configuration separate from development. Create a 'production' split with production-only config in complete split, disable by default, and activate only on production servers.
Multi-Site Configuration Sharing
Share a common configuration base across multiple sites while allowing site-specific overrides. Use collection storage for splits that should travel with the main config, making it easy to deploy the same configuration package to different sites with environment-specific variations.
Feature Branch Configuration
Use partial splits to manage configuration changes during feature development. The base configuration remains in sync while feature-specific changes are stored as patches that can be easily reviewed, merged, or discarded.
Configuration for Different Environments
Create separate splits for development, staging, and production environments. Use weight to control processing order, and stackable splits to layer environment-specific changes on top of shared configuration. Example folder structure: ../config/sync, ../config/dev, ../config/staging, ../config/production
Local Development Overrides
Use the 'Activate locally only' feature to enable splits on individual development machines without committing status changes. This uses Drupal state instead of config, so each developer can have their own active splits.
Tips
- Always use folder paths outside the sync directory. Nested directories cause conflicts during config sync.
- Use collection storage when splits should be included in config exports/archives (e.g., for distribution).
- Use database storage for local-only configuration that shouldn't be shared between environments.
- Set split priority in settings.php for predictable ordering: $settings['config_split_priorities'] = ['production' => 100, 'development' => -100];
- Use wildcards in complete/partial lists for flexible matching: views.view.*, system.*, block.block.bartik_*
- The 'Activate locally only' option is useful for testing splits without affecting the shared configuration.
- When using stackable splits, remember that higher-weight splits can modify the exported content of lower-weight splits.
- Review the View page for each split to see Preview (what would be exported) vs Exported (what's currently stored).
- For CI/CD pipelines, use drush config-split:export after drush cex, or rely on the post-command hook that runs automatically.
- Partial splits are ideal for configuration that should exist in sync but needs environment-specific values (like API endpoints).
Technical Details
Admin Pages 8
/admin/config/development/configuration/config-split
Lists all configuration split settings with their current status, default status, and available operations. Shows whether status is overridden via settings.php or state.
/admin/config/development/configuration/config-split/add
Create a new configuration split definition with storage location, modules/themes to split, and specific configuration items.
/admin/config/development/configuration/config-split/{config_split}
View the split configuration including a preview of what would be exported and what is currently in the split storage.
/admin/config/development/configuration/config-split/{config_split}/edit
Modify an existing split configuration. Same form as Add page with current values populated.
/admin/config/development/configuration/config-split/{config_split}/activate
Activate an inactive split by importing its configuration from the active storage. Shows a diff of changes that will be made.
/admin/config/development/configuration/config-split/{config_split}/deactivate
Deactivate an active split by removing its configuration from the active storage. Shows a diff of changes.
/admin/config/development/configuration/config-split/{config_split}/import
Import configuration from the split storage to the active configuration. For inactive splits, optionally activates.
/admin/config/development/configuration/config-split/{config_split}/export
Export current configuration to the split storage. Shows differences between current preview and existing storage.
Permissions 1
Hooks 1
hook_config_readonly_whitelist_patterns
Provides patterns to whitelist for the config_readonly module. Config Split automatically adds entries from active database splits to the whitelist.
Drush Commands 5
drush config-split:export <split>
Export only the specified split configuration to its storage. The split must be active.
drush config-split:import <split>
Import configuration from a split's storage to the active configuration.
drush config-split:activate <split>
Activate a split by importing its configuration from the active storage and setting it as active.
drush config-split:deactivate <split>
Deactivate a split by removing its configuration from active storage.
drush config-split:status-override <split> [status]
Get or set the status override for a split via Drupal state. Useful for runtime activation without config changes.
Troubleshooting 7
Create the directory manually with appropriate permissions. Ensure the path is OUTSIDE the sync directory. Use a sibling directory structure like ../config/sync and ../config/dev.
Verify the split is active (check current status on the list page). If overridden in settings.php, ensure the override sets status to TRUE. Clear caches after changing settings.php.
Clear all caches with drush cr after modifying settings.php overrides. The config override system requires cache clearing to take effect.
This occurs when importing configuration from a different Drupal installation. Ensure your sync and split directories contain configuration from the same site installation.
Check the 'Exported' view on the split page to see what's in the split storage. Use the diff view on import/export forms to preview all changes before applying them.
For partial splits, differences are calculated against the sync storage (or composed storage for stackable splits). Ensure the base configuration in sync is what you expect. Export to sync first if needed.
Adjust the weight values on splits. Lower weights process first on export and last on import. For explicit control, set $settings['config_split_priorities'] in settings.php.
Security Notes 5
- The 'administer configuration split' permission is marked as 'restrict access' and should only be granted to trusted administrators, as it allows significant site configuration changes.
- Database storage splits are included in database dumps. Be cautious about storing sensitive configuration (API keys, credentials) in database splits.
- Split folders are automatically protected with .htaccess files (Apache) when created. Ensure your web server properly restricts access to config directories.
- When using folder storage, ensure the directory has appropriate filesystem permissions and is not web-accessible.
- Configuration overrides in settings.php take precedence over state overrides, providing a secure way to enforce split status in production.