README

Keep Magento persistently configured from version-controlled files. Define your store configuration (websites, attributes, categories, CMS, tax, customers, …) as YAML/CSV, commit it, and apply it to any environment with a single command.

Originally created by CTI Digital; this is Magebit's v2 line — a modernised, self-owned fork under the Magebit\Configurator namespace (Magebit_Configurator).

Why

• Stand up a store from scratch with its important DB-backed configuration ready.
• Share and version configuration alongside your code.
• Apply environment-specific configuration (local / stage / live).
• Re-run safely: components are idempotent and a --dry-run previews changes.

Requirements

• Magento Open Source / Adobe Commerce 2.4.7 – 2.4.9 (all currently non-EOL)
• PHP 8.1 – 8.5 (the union supported across those Magento versions)
• firegento/fastsimpleimport ^2.0

What's new in v2

• Magebit\Configurator namespace / Magebit_Configurator module.
• Typed component contract — execute(ComponentContext): ComponentResult (replacing the untyped execute($data)); strict_types, promoted readonly constructors throughout.
• --dry-run — preview what each component would create/update/skip without persisting anything (raw SQL, imports and saves are all guarded).
• Meaningful exit codes — configurator:run returns non-zero when any component reports an error, and prints a run summary (created N, updated N, skipped N, removed N, errors N). A single failing component no longer aborts the whole run.
• Uniform reconciliation — every component honors create/maintain mode and per-entity / per-component versioning through one shared gate (see below), so create mode is safe on production.
• New capabilities — MSI: inventory_sources (sources/stocks) + a products msi_sources column; widget layout placement via page_groups; optional Hyvä Commerce CMS components (hyva_pages / hyva_blocks); opt-in entity removal via remove: true across the entity components (CMS, config, widgets, rewrites, categories, attributes, tax rules, …) — see docs/schema/.
• Documented config contract — every component's source format is in docs/schema/.

Upgrading from the CtiDigital v1 module? See docs/UPGRADE.md — your config files keep working, but the package/module names, PHP/Magento support and reconciliation behaviour changed.

Getting started

1. Install: composer require magebit/module-magento2-configurator:^2.0 (from your configured composer repository).
2. Create app/etc/master.yaml (see Samples/master.yaml). Source paths are resolved relative to the Magento base dir, e.g. app/etc/configurator/Attributes/attributes.yaml.
3. Enable the modules: bin/magento module:enable Magebit_Configurator FireGento_FastSimpleImport then bin/magento setup:upgrade.
4. Apply: bin/magento configurator:run --env="<environment>"

Usage

bin/magento configurator:list                                   # list components
bin/magento configurator:run --env="local"                      # run all
bin/magento configurator:run --env="local" --component="config" # run one (repeatable)
bin/magento configurator:run --env="local" --dry-run            # preview, no writes
bin/magento configurator:run --env="local" -i                   # ignore missing source files
bin/magento configurator:run --env="local" -v                   # verbose logging

Syncing from the database

The reverse of configurator:run — read the current DB state and write it back into the source files, so changes made in the admin can be captured into git. Components opt in by implementing ExportableComponentInterface.

Supported: config, blocks, pages, widgets, websites, customergroups, adminroles, adminusers (no passwords), apiintegrations (no tokens), order_statuses, review_rating, taxrates, taxrules, catalog_price_rules, rewrites (non-autogenerated only), shippingtablerates, inventory_sources, hyva_pages, hyva_blocks, attributes (incl. options & swatches), customer_attributes, attribute_sets (groups + user-defined attributes), categories (full tree). Not supported (bulk/imperative — use Magento's own export for products/ customers): products, customers, sql, sequence, media.

# Refresh the values of the config paths you already track, in place:
bin/magento configurator:sync-from-db --component=config
bin/magento configurator:sync-from-db --component=config --dry-run   # preview

# Full export of everything in scope, optionally filtered and to a chosen file:
bin/magento configurator:sync-from-db --component=config --all --path="web/" --output="app/etc/configurator/Config/web.yaml"

• Default mode refreshes only the entries already present in the source files (low-noise); --all dumps everything in scope, --path= filters by prefix.
• For pages/blocks entries that reference an external source: file, the current DB content is written into that file (created if missing), not inlined into the YAML — so template-sourced content round-trips.
• Encrypted config values are never written out, so secrets stay out of git.
• Only values actually stored in core_config_data are pulled (defaults from config.xml/env.php are left as-is).
• A component that fails to export is logged and skipped; the rest still run and the command exits non-zero.

Reconciliation: modes & versioning

Every component now applies the same rule for how config reconciles against existing data, via a shared ReconciliationGate:

Set the mode per environment in master.yaml:

config:
  enabled: 1
  sources: [ ../configurator/Config/config.yaml ]
  env:
    production: { mode: create }    # safe: only new entities + version bumps
    staging:    { mode: maintain }  # reconcile drift

When no mode is set the default is create.

Versioning forces an update even in create mode:

• Per-entity — add version: <n> to an entity in its source file (supported where the data shape has per-entity nodes: config values, blocks, pages, widgets, attributes, …). Bump it to push that one change to production.
• Per-component — add version: <n> at the component level in master.yaml to run the whole component once per version (ideal for sql, sequence, media, and bulk importers like tiered_prices / shippingtablerates).

⚠ Upgrade behavior change (v2 reconciliation): components that previously overwrote existing entities on every run (widgets, attributes, websites, rewrites, product links, catalog price rules, admin roles, review ratings, …) now honor mode uniformly. In create mode they protect existing entities. If you relied on always-overwrite, set mode: maintain for those components. Bulk importers (products, customers, taxrates) skip rows whose key already exists in create mode; they do not diff individual attributes, so maintain re-imports every row.

Configuration reference

See docs/schema/ for the source format of every component (fields, behaviour, create/maintain semantics). This is the stable public contract for the v2 line.

Testing

• Unit tests (phpunit.xml.dist) — run from within a Magento install:

  ../../../vendor/bin/phpunit -c phpunit.xml.dist

• Conformance harness (Test/Conformance/) — runs every component through the shipped Samples/ in --dry-run against a real Magento and fails on any component crash. This is the primary integration check.
• Static analysis — phpcs (Magento2 standard, see phpcs.xml.dist) + phpmd.

Components

All 30 components are implemented and execute-verified on Magento 2.4.7. Each links to its schema page. Every component honors create/maintain mode and the versioning levers described above — the notes below only call out extras.

Background

Lightning talk by Raj Chevli at Mage Titans Manchester on YouTube.

License

MIT — see LICENSE. Copyright © 2016 CTI Digital; portions copyright © 2026 Magebit, Ltd.