entity_splitter

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