Entity Splitter refactors large entities into smaller, focused sub-entities by automating the creation of target fields, source-to-target references, and form modes. It then migrates data from the source entity to these new sub-entities, offering flexibility through YAML mapping or existing field groups and controllable via Drush commands.
Split large entities into focused sub-entities. Automate target field creation, source→target references, form modes, and data migration from a source entity into your pre-created sub-entities via Drush.
Introduction
Entity Splitter helps you refactor large, monolithic entities into smaller, focused sub-entities. It automates creating target-side fields, reference fields on the source entity, form modes, and migrating field data from the source to your pre-existing sub-entities.
Features
- Split entities via plugins: Provide an `@EntitySplitter` plugin that defines the source entity type/bundle and target entity type/bundle(s). The module runs the split for you.
- Two-phase workflow:
- Structure migration: Create target fields/config, create source→target reference fields, optionally hide or remove original source fields, and create per-target form modes.
- Data migration: Copy/move field content from the source entity into the sub-entities and write the references back.
- Flexible mapping sources:
- YAML mapping file: Pass a path to a YAML file describing how fields/groups should map to target bundles.
- Field Group mapping: If you use the `field_group` module, Entity Splitter can build a mapping scaffold from your existing form display groups and components.
- Drush-first UX: Run and iterate splits from the CLI with clear summaries and counters.
- Queueable migrations: Optionally process data via a queue worker to avoid timeouts on large datasets.
- Safety controls: `--dry-run` for structure operations, options to hide or remove fields, and to clear existing references during data migration.
When and why to use it
- Content model refactoring: You started with one content type and now want to split it into multiple sub-entities (e.g., moving grouped fields into dedicated sub-entities), without hand-creating dozens of fields and tedious copy/paste of data.
- Gradual modernization: Prepare target entities/bundles and evolve your site incrementally, first shaping configuration, then migrating live data.
Typical use cases
- Splitting a `node` type with many field groups into multiple target bundles, each becoming a dedicated sub-entity referenced from the original node.
- Preparing custom entities that will be edited via Inline Entity Form, creating matching form modes automatically for a cleaner editorial UI.
Post-Installation
This module is primarily operated via Drush and custom plugins; it does not create new UI pages by itself.
Quick command reference
bash
# List plugins
drush es:list
# Migrate structure (YAML mapping)
drush es:ms <plugin_id> --mapping-file=/path/to/mapping.yml --create-fields --create-reference-fields
# Migrate structure (field groups)
drush es:ms <plugin_id> --use-field-groups --form-mode=default --create-fields
# Migrate data (all or one)
drush es:md <plugin_id> --process-all
drush es:md <plugin_id> --entity-id=123
# Use the queue for data migration
drush es:md <plugin_id> --use-queue