This project is not covered by Drupal’s security advisory policy.

Facets Migrate

Facets Migrate provides a set of safe, deterministic Drush commands that help site builders migrate legacy Facets 2.x configuration to Facets 3.x, where the recommended approach is to expose facets as Views exposed filters (via the facets_exposed_filters submodule) rather than as separate facet blocks.

The module is read-only by default. Every command runs in dry-run mode, prints a deterministic plan, and only writes configuration when an explicit --apply flag is passed. No facets.facet.* configuration is ever deleted, no Layout Builder placements are touched, and no Views are saved unless at least one valid change is queued for them.

Table of contents

  • Why this module?
  • Requirements
  • Installation
  • Recommended workflow
  • Drush commands
  • Migration semantics
  • Safety guarantees
  • What the module does NOT do
  • Architecture
  • Troubleshooting
  • Maintainers

Why this module?

Facets 3.x recommends that facets backed by Views exposed filters use the facets_filter Views filter plugin shipped by the facets_exposed_filters submodule. That filter integrates Facets processors, widgets, query operators and cache contexts directly into the Views render pipeline.

Manually replacing dozens (or, on multisite platforms, hundreds) of facet configurations with the correct exposed filter definition is error-prone. Facets Migrate inspects active configuration, parses Facets 2.x source IDs, matches each facet to a real Views display, validates the target, and generates filter definitions that match the schema shipped by facets_exposed_filters.

Requirements

Install with Composer (recommended):

composer require drupal/facets_migrate
drush en facets_migrate facets_exposed_filters -y

Or enable from a manual download:
drush en facets_migrate facets_exposed_filters -y
The module has no UI and no configuration form. Once enabled, all functionality is exposed via Drush.

Recommended workflow

  1. Take a backup of the site's database and configuration directory.
  2. Enable facets_exposed_filters.
  3. Run the audit and inspect the legacy facet inventory: drush facets-migrate:audit
  4. Validate which facets can be mapped to a Views display: drush facets-migrate:map
  5. Review the dry-run plan and export it to JSON: drush facets-migrate:views-filters --output=/tmp/facets-migrate-plan.json
  6. Apply the changes: drush facets-migrate:views-filters --apply
  7. Export configuration and review the diff before committing: drush cex -y && git diff config/
  8. Re-run drush facets-migrate:views-filters --apply — it must report every previously-applied filter as skipped_existing.

Project information

Releases