entity_io

Entity I/O is a powerful Drupal module that allows you to export and import entities as JSON files, making it easier than ever to migrate or synchronize content between environments or websites.

When exporting an entity, the process will go as deep as possible, including all fields and related entities.
Upon import, all associated data will also be restored — including referenced entities such as users, taxonomy terms, paragraphs, and other content.

You can fully customize which fields are exported and how deeply related entities are included — from simple field values to deeply nested entity references. For example, when exporting an article with comments, Entity I/O ensures that all related entities (comments, referenced nodes, taxonomy terms, and media) are also included, preserving relationships and data integrity on import.

Each entity type includes a dedicated tab that provides quick access to export operations.
For entities that support revisions, an additional export option is also available in the revision overview dropdown, allowing you to export specific revisions directly from the revision list.

Entity I/O supports Drush commands for quick CLI-based exports and imports and lets you choose between public or private file storage for your JSON exports. Every export generates a structured, portable JSON file that can be easily versioned, shared, or imported into another Drupal instance.

Core Features

• Export and import any Drupal entity (Node, Taxonomy, User, Block, Comment, Paragraph) as JSON.
• Control field-level export depth and related entity inclusion.
• Support for both manual and automated (via Drush or Webhooks) workflows.
• Public or private file system integration.
• Fully extensible architecture with multiple submodules.
• Visual Diff on Import: When importing an entity that already exists, Entity I/O displays a side-by-side diff screen showing the differences between the existing data and the new imported version — allowing you to review and confirm changes before applying them
• Export multiple entities at once directly through the administrative interface.
• Configuration to generate new revisions when importing and set a user as the author of the change.

Drush Commands

• Export sample entities or all entities and save JSON files
  • drush entity-io:export
  • drush entity-io:export --all
  • drush entity-io:export --entity-type=node --all
  • drush entity-io:export --entity-type=node --id=123
• Import all exported JSON entities
  • drush entity-io:import
  • drush entity-io:import --user=1
  • drush entity-io:import --user=username
  • drush entity-io:import --entity-type=node
• Lists the exported files
  • drush entity-io:list
  • drush entity-io:list --entity-type=node
• Import JSON files from a folder
  • drush entity-io:import-folder [/path/to/json or public://entity_io_exports]
• Clear exported JSON files
  • drush entity-io:clear-exports
  • drush entity-io:clear-exports --entity-type=node

Submodules

• Entity I/O Queue (entity_io_queue)– Enables queued entity export/import, ideal for large-scale data operations.

  Includes an authenticated endpoint (/entity-io/queue/import/add-item) that allows adding import tasks programmatically using Basic Auth.
  This makes it possible for external systems or scripts to push new import jobs directly into the Drupal queue securely.

• Entity I/O Webhooks (entity_io_webhooks)– Adds automation through webhooks triggered by
  • create, update, delete, or content moderation events:
  • Send the exported JSON via HTTP POST to an external endpoint.
  • Send the exported JSON as an email attachment (requires SMTP module).
  • Upload the exported JSON file via FTP.
• Entity I/O Push (entity_io_push) – Adds a “Push to Server” tab on entity pages, allowing you to push content and all related entities to another configured Drupal site. Perfect for multi-environment synchronization.
• Entity I/O Purge (entity_io_purge)– Provides Drush commands and a user interface to clean up exported JSON files.

Hooks for other modules

The Entity IO module provides a set of hooks that allow other modules to alter, adjust, or validate field values during the entity export and import processes. These hooks give developers full flexibility to customize how specific field types are processed, including controlling recursion depth, field structures, and how each value is represented in exported or imported data.

Below are the hooks exposed by the module, with detailed explanations of their purpose and usage.

• hook_entity_io_export_FIELD_TYPE_alter

function hook_entity_io_export_FIELD_TYPE_alter(&$value, $field_name, $field_type, $target_type, &$field, &$depth, &$max_depth) {
  // Custom export logic.
}

Description
This hook is triggered during entity export and allows modules to alter the exported field value before it is written into the output JSON.

It is invoked per field type based on the convention FIELD_TYPE in the hook name. This enables developers to implement custom logic for handling specific field types such as string, entity_reference, image, paragraph, etc.

Parameters

• &$value The final value that will be exported. You can override this to customize how the field should appear in the exported data.
• $field_name The machine name of the field being exported.
• $field_type The Drupal field type (plugin ID), for example: entity_reference, string, image, etc.
• $target_type The referenced entity type, when applicable (e.g., node, file, taxonomy_term).
• &$field The field instance (FieldItemListInterface), giving access to metadata, raw values, and full item objects.
• &$depth The current recursion depth. Useful for nested structures like Paragraphs.
• &$max_depth The maximum allowed recursion depth. Helps prevent infinite loops or overly deep exports

Use cases

• Transform or restructure complex field data before exporting.
• Export only specific properties of a field.
• Resolve referenced entities into custom formats.
• Prevent recursive export loops of deeply nested structures

• hook_entity_io_import_FIELD_TYPE_alter

function hook_entity_io_import_FIELD_TYPE_alter(&$value, $field_name, $field_type) {
  // Custom import logic.
}

Description
This hook is triggered during the import process and allows modules to alter the raw field value before it is applied to the entity.

Just like the export hook, the FIELD_TYPE convention allows logic to be applied specifically to each field type.

Parameters

• &$value The value received from the JSON file. You may transform, normalize, sanitize, or resolve references here.
• $field_name The field machine name.
• $field_type The Drupal field type.

Use cases

• Convert imported data formats into Drupal-compatible values.
• Resolve entity references (e.g., UUID → local ID).
• Normalize dates, text formats, or list values.
• Clean or modify data before saving it.

• hook_entity_io_validate_FIELD_TYPE_alter

function hook_entity_io_validate_FIELD_TYPE_alter(&$isValid, &$errorMessage, $value, $field_name, $field_type, $delta) {
  // Custom validation logic.
}

Description
This hook allows modules to validate field values during import before the field is saved.
If validation fails, the Entity IO process stops and returns the provided error message.

This is particularly useful for ensuring data consistency and avoiding the import of malformed or unsupported values.

Parameters

• &$isValid Set to FALSE to block the import of the field item.
• &$errorMessage A custom message explaining why validation failed.
• $value The raw imported value.
• $field_name The field machine name.
• $field_type The Drupal field type.
• $delta The item index for multi-value fields.

Use cases

• Enforce strict formats (JSON, IDs, URLs, dates, etc.).
• Prevent imports referencing invalid or missing entities.
• Validate numerical or text limits.
• Enforce allowed list values or taxonomy terms

Entity I/O was built with flexibility and automation in mind, designed for developers and site builders who need reliable, repeatable ways to move complex Drupal entities across environments without losing relationships or data consistency.

Donation Support

This project took significant time to develop. If it has helped you save time in your work or business, feel free to contribute any amount you consider fair to support its continued development