README

Export and import the Magento url_rewrite table as CSV from the admin, with safety backups.

What it does

Export — one click downloads the entire url_rewrite table as url_rewrite_YYYY_MM_DD_HHmmss.csv. CSV columns mirror the database columns exactly (read live from the schema, never hardcoded). Streamed row-by-row, so memory stays flat on large tables. No queues.
Import — upload a CSV previously exported by this tool. Before any row is written:
- the CSV header is validated against the live database columns; an unknown column aborts the import;
- a safety backup of the current table is always written to var/rewrites/url_rewrite_<timestamp>.csv;
- if you did not export a backup through this tool first, you are warned.
Import options (admin-selectable, echoed back in the result for debug reports):
- Import mode — Upsert / Skip duplicates / Fail on duplicate.
- ID handling — Preserve url_rewrite_id from the CSV, or auto-assign new IDs.
- Truncate — optional checkbox to empty the table first; requires an extra JS confirmation.
Duplicate generated rewrite guard — after every import, the table is checked for entities holding more than one is_autogenerated = 1 rewrite in a store, and the superseded rows are turned into 301 redirects to the surviving path. See below for why.
Result table — after import, shows rows in file / imported / skipped (duplicates) / failed / demoted to 301, plus the exact options used.

Admin page: System → Tools → URL Rewrite Import / Export.

Why the duplicate generated rewrite guard exists

url_rewrite is unique on (request_path, store_id) only. Nothing in the schema stops two rows from claiming is_autogenerated = 1 for the same (entity_type, entity_id, store_id) — for example a path generated before a url_key change plus the current one. Magento normally avoids that because UrlPersist::replace() deletes an entity's superseded rows, but this tool writes with raw inserts, so a CSV holding an old generated path can reintroduce one.

The consequence is not limited to a stale URL. Magento\Catalog\Model\ResourceModel\Category\Collection::joinUrlRewrite() (and the product equivalent) LEFT JOINs url_rewrite on entity_id and then indexes the loaded entities by id, so a second generated row returns a second result row and the collection throws:

Exception: Item (Magento\Catalog\Model\Category\Interceptor) with the same ID "4147" already exists.

That kills every consumer of those collections in one go — main menu, top navigation and the Amasty HTML/XML sitemaps — with a 500 on the storefront, and the frontend category collection is cached, so it stays broken until the cache is flushed.

After an import, DuplicateAutogeneratedFixer therefore enforces one generated rewrite per entity per store across the whole table: the highest url_rewrite_id wins (the most recently generated path, i.e. the one matching the entity's current url_key) and the losers become is_autogenerated = 0, redirect_type = 301 pointing at the winner — the same shape core produces on a url_key change, so old inbound links keep working. Because it runs against the finished table rather than individual CSV rows, the outcome does not depend on CSV row order, and rows that were already duplicated before the import are repaired too.

Install

This module ships as a standalone Composer package, deployecommerce/module-url-rewrite-import-export.

Via a VCS / Packagist repository (deploy)

composer require deployecommerce/module-url-rewrite-import-export:^1.0
bin/magento module:enable DeployEcommerce_UrlRewriteImportExport
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Via a local path repository (development)

Add a path repository pointing at this checkout and require it as @dev:

"repositories": {
    "local-url-rewrite-import-export": {
        "type": "path",
        "url": "packages/module-url-rewrite-import-export",
        "options": { "symlink": true }
    }
}

composer require deployecommerce/module-url-rewrite-import-export:@dev

In a Docker setup whose vendor/ is a named volume, the path-repo target must be visible inside the container — mount this checkout into the project, e.g. /path/to/module:/var/www/html/packages/module-url-rewrite-import-export.

league/csv:^9.28 is a hard dependency (declared in this module's composer.json) and is pulled in automatically by Composer.

Tests (PEST)

The framework-free service classes (HeaderValidator, FilenameGenerator) are unit-tested with PEST. The harness is isolated under tests/ with its own composer.json because Pest 2 ships PHPUnit 10, which conflicts with Magento's bundled PHPUnit 9 — keeping it separate avoids the clash and never boots Magento.

cd tests
composer install
./vendor/bin/pest

Database-touching classes (Exporter, Importer, BackupWriter) are integration territory and are intentionally out of the pure-unit harness.

deployecommerce / module-url-rewrite-import-export

Maintainers

Package info

Statistics

Security