"Regenerate Url Rewrites" extension

A Magento 2 CLI extension that regenerates URL Rewrites for products and categories — across all
stores, a single store view, or a specific ID/range — with options to preserve old URLs, delete
orphaned rewrites, change the URL suffix, and more.

Extension homepage: https://github.com/olegkoval/magento2-regenerate_url_rewrites
Changelog: CHANGELOG.md

Table of Contents

• Requirements
• Installation
• Quick Start
• CLI Options Reference
• Notes & Caveats
• Combining Options
• Deprecated Options
• More Examples
• Use From Code
• Support Me
• Contacts
• License

REQUIREMENTS

composer.json declares "php": ">=8.2". PHP compatibility otherwise follows whatever your
Magento version itself requires — the extension doesn't impose a narrower floor than Magento does.
2.4.6 and older are treated as legacy/best-effort only (no longer patched upstream by Adobe).

INSTALLATION

COMPOSER INSTALLATION

• run composer command:

$> composer require olegkoval/magento2-regenerate-url-rewrites

MANUAL INSTALLATION

• extract files from an archive

• deploy files into Magento2 folder app/code/OlegKoval/RegenerateUrlRewrites

ENABLE EXTENSION

• enable extension (use Magento 2 command line interface):

$> php bin/magento module:enable OlegKoval_RegenerateUrlRewrites

• to make sure that the enabled module is properly registered, run 'setup:upgrade':

$> php bin/magento setup:upgrade

• [if needed] re-compile code and re-deploy static view files:

$> php bin/magento setup:di:compile
$> php bin/magento setup:static-content:deploy

QUICK START

• regenerate Url Rewrites for all products, in all stores (product is the default entity type, so it can be omitted):

$> php bin/magento ok:urlrewrites:regenerate

• regenerate Url Rewrites for all categories, in all stores:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=category

• regenerate Url Rewrites for one product (ID 122), in one store (ID 2):

$> php bin/magento ok:urlrewrites:regenerate --product-id=122 --store-id=2

Keep reading for the full options reference, or jump to More Examples.

CLI OPTIONS REFERENCE

General

Product targeting & options

Category targeting & options

NOTES & CAVEATS

• --skip-products only has an effect when the "Use Category Path for Product URLs" setting
  (Stores > Configuration > Catalog > Catalog > Search Engine Optimization, config path
  catalog/seo/product_use_categories) is enabled — that setting is what makes category
  regeneration cascade into product URLs in the first place. If it's disabled, category
  regeneration never touches product URLs, with or without --skip-products.

• --set-product-suffix / --set-category-suffix are applied to Default Config and every
  store view, or only to the store given via --store-id, using the same write path Magento's own
  config:set CLI command uses — so validation (e.g. rejecting # or //) and Magento's own
  automatic suffix swap on existing URL Rewrites both run. A suffix locked in app/etc/config.php is
  reported before anything is saved; if either suffix value fails validation, the whole command aborts
  before any regeneration runs. Since the config is written before
  regeneration, in the same command, you get a clean
  /categorya/oldname.html -> /categorya/newname.html redirect instead of a two-step chain.

• Failures and exit code: if any product/category (or a cleanup, reindex or cache step) fails, the run
  continues with the rest, then prints a [FAILURES] summary (counts per type plus up to 20 of the
  failures) and exits with code 1 — after reindex and cache refresh have still run. Earlier versions always exited
  0, so cron jobs or scripts that check the exit code may start reporting failures that used to be
  hidden.

• --exact-categories: by default a category run also processes every subcategory of the given
  categories (a subcategory's URL path is built from its parents'). With this option only the given
  categories are processed — their subcategories only if a given category's URL path changed, and then
  without regenerating the subcategories' url_key (so --regen-url-key touches only the given
  categories). Products are regenerated only for the processed categories.

• --include-not-visible makes the run process "Not Visible Individually" products too — e.g. their
  url_key is regenerated with --regen-url-key — but it can't give them URL rewrites: Magento's own
  generator creates none for a product that isn't visible in any store view. (Since Magento 2.4.7 a product
  hidden by default but visible in some store view does get rewrites for that store view — every run
  includes it there anyway; --store-id=0 runs need this option for it.)

• --regen-url-key inverted its default behavior in 1.8.0: url_key is no longer regenerated
  automatically. Pass --regen-url-key explicitly whenever you want it regenerated too — see
  Deprecated Options if you're upgrading from an older version.

COMBINING OPTIONS

Most options combine freely, e.g.:

$> php bin/magento ok:urlrewrites:regenerate --store-id=2 --save-old-urls --regen-url-key --no-reindex

These combinations are not allowed:

• --entity-type=product together with --category-id / --categories-range
• --entity-type=category together with --product-id / --products-range
• --category-id and/or --categories-range together with --product-id and/or --products-range

DEPRECATED OPTIONS

• --check-use-category-in-product-url — obsolete. The extension now uses Magento's built-in URL
  Rewrite generator, which already checks the "Use Category Path for Product URLs" config on its
  own, so this manual flag is no longer needed.
• --no-regen-url-key — removed in 1.8.0 (not just deprecated — passing it now causes an
  "unrecognized option" error). url_key regeneration behavior was inverted: it is now skipped by
  default and only runs when you explicitly pass --regen-url-key. If you relied on the old
  default (url_key regenerated automatically), add --regen-url-key to your existing
  commands/scripts/cron jobs after upgrading to 1.8.0.

MORE EXAMPLES

• Regenerate Url Rewrites for product with ID 38 in store with ID 3:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=product --store-id=3 --product-id=38

or

$> php bin/magento ok:urlrewrites:regenerate --store-id=3 --product-id=38

• Regenerate Url Rewrites for products with IDs 5,6,7,8,9,10,11,12 in store with ID 2 and skip the full reindex:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=product --store-id=2 --products-range=5-12 --no-reindex

• Regenerate Url Rewrites for category with ID 22 in all stores and save current Url Rewrites:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=category --category-id=22 --save-old-urls

• Regenerate Url Rewrites for categories with IDs 21,22,23,24,25 in store with ID 2:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=category --categories-range=21-25 --store-id=2

• Set the category URL suffix to .html and regenerate all category URLs in one step:

$> php bin/magento ok:urlrewrites:regenerate --entity-type=category --set-category-suffix=.html

USE FROM CODE

The same run is available as a service (@api), e.g. for cron jobs, queue consumers or integrations —
inject OlegKoval\RegenerateUrlRewrites\Api\RegenerateServiceInterface:

$options = $this->runOptionsBuilder // OlegKoval\RegenerateUrlRewrites\Model\RunOptionsBuilder
    ->setEntityType('product')
    ->setStoreIds([2])          // empty (default): all stores
    ->setProductIds([38, 39])   // empty (default): all products
    ->setSaveOldUrls(true)
    ->setReindex(false)         // reindex and cache refresh are on by default, as in the CLI
    ->create();

$problems = $this->regenerateService->validate($options); // string[]; run() throws InputException for these
$result = $this->regenerateService->run($options);
if ($result->hasFailures()) {
    // $result->getFailureCounts(), $result->getFailures()
}

run() accepts an optional Api\ProgressReporterInterface to receive progress; without one nothing is
printed. To stop a run, throw from the reporter's advance() or message(): the run stops after the current
entity (whose rewrites stay saved), skips the remaining stores and the reindex/cache steps, restores the current
store and rethrows your exception unchanged. The same goes for an exception from the change listener below.

To track the run's changes to URL rewrites and url_key/url_path values (e.g. to log, audit or undo a run),
pass an Api\ChangeListenerInterface as the third argument of run(): its onChange() receives an Api\Data\ChangeInterface per saved change —
rewrite_added / rewrite_removed / rewrite_updated (with the full old/new url_rewrite rows) and
url_key_changed / url_path_changed (with the store of the attribute row written, 0 = default scope, and
hasOldRow()/hasNewRow(), since such a row can exist and hold NULL). A rolled-back save reports nothing; without a
listener no extra queries run. The reports are complete enough to undo a run — except URL suffix changes
(setProductUrlSuffix()/setCategoryUrlSuffix()) and the suffix swap Magento then applies to existing rewrites,
which aren't reported.

$result->getProcessedCounts() has the entities the run went through (entity type → store ID → count).
$options->toArray() / $builder->fromArray($array) log and replay a run; an unknown key or a value of the wrong
type makes fromArray() throw \InvalidArgumentException, so a typo can't widen a run to e.g. all products.

Backward compatibility

This extension follows Semantic Versioning. Within 1.x:

• Nothing marked @api is removed or renamed, and neither is any public or protected member of the command
  classes (Console\Command\RegenerateUrlRewrites, RegenerateUrlRewritesAbstract), the command name or the
  INPUT_KEY_* constant values; constructors only gain optional trailing arguments.
• Interfaces you implement (Api\ProgressReporterInterface, Api\ChangeListenerInterface) never gain methods —
  new hooks come as new interfaces. Interfaces only this extension implements (Api\RegenerateServiceInterface,
  Api\Data\RunOptionsInterface, Api\Data\RunResultInterface, Api\Data\ChangeInterface) may gain methods
  or optional parameters in minor releases, so don't implement them yourself (a plugin on the service is fine).
  The keys of the rewrite arrays in ChangeInterface stay the same.
• The models (Model\Regenerate*Rewrites) are internal: use the service instead.

SUPPORT ME

• Ko-fi
• PayPal
• Patreon

CONTACTS

• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/oleg-koval-85bb2314/
• Issues & feature requests: GitHub Issues

LICENSE

Dual-licensed, same as Magento itself:

• Open Software License (OSL-3.0)
• Academic Free License (AFL-3.0)

Enjoy!

Best regards,
Oleg Koval

"Regenerate Url Rewrites" Change Log

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[1.11.0] - 2026-09-30

Added

• a public service API to run the regeneration from code (cron jobs, queue consumers, integrations):
  Api\RegenerateServiceInterface (validate(), run()), run options built with Model\RunOptionsBuilder,
  a RunResultInterface with failure counts/details, and an optional ProgressReporterInterface. The CLI
  command now runs through it; its options and output are unchanged (except the new summary line below). See "Use
  From Code" in the README.
  Also: a documented way to stop a run (throw from the reporter), processed counts in the result,
  toArray()/RunOptionsBuilder::fromArray() to log and replay a run's options, and an
  Api\ChangeListenerInterface that receives a run's changes (rewrites added/removed/updated with full rows,
  url_key/url_path changes with their scope; not URL suffix config) — groundwork for a verbose output (#91)
• new option --exact-categories: with --category-id/--categories-range, process only the given categories —
  their subcategories only when a given category's URL path changed, and then without regenerating their
  url_key, so --regen-url-key stays on the given categories. Useful for precise fixes on large category trees
• the command prints a summary before "Finished", e.g. Processed: 38 category(ies), 2040 product(s) in 3 store(s)
• a backward-compatibility policy (README "Backward compatibility"): semantic versioning, what stays stable within
  1.x and which interfaces may grow

Changed

• reindex and cache refresh after a run now happen in the same PHP process through Magento's indexer and
  cache services instead of spawning bin/magento indexer:reindex / cache:clean / cache:flush: they
  use the run's own memory limit (e.g. php -d memory_limit=-1 bin/magento ...), which the spawned processes
  didn't inherit, and a failing or locked indexer is now reported in the [FAILURES] summary (exit code 1)
  instead of being ignored
• --include-not-visible help and README now say what the option does: "Not Visible Individually" products are
  processed too (e.g. url_key regeneration), but Magento creates no URL rewrites for a product that isn't
  visible in any store view — the option never could add those
• category runs that regenerate their products (Use Categories Path for Product URLs) now show a progress bar for
  that product phase too, instead of nothing until it ends
• a --set-product-suffix/--set-category-suffix value locked in app/etc/config.php is now reported before
  anything is saved; before, the other suffix was still saved and then the run aborted
• for code extending the command or the models: the command's protected _runReindexation(), _runClearCache()
  and _setSeoUrlSuffixes() moved into the service, and the models' _showProgress() / progressBarProgress /
  progressBarTotal were replaced by the progress reporter; the command's constructor gained an optional 9th
  argument (8-argument subclasses keep working). The backward-compatibility policy applies from this release on

Fixed

• --regen-url-key for a store view left a stale store-level url_key in place when the regenerated key was
  the same as the default one (it only skipped writing a redundant copy, see #92): the rewrite used the new key
  but the product/category kept the old one, and the next run without --regen-url-key switched the URL back.
  The store-level value is now removed, so the store view inherits the default

[1.10.0] - 2026-09-26

Changed

• the command now reports failures instead of silently skipping them: products/categories whose URL
  rewrites couldn't be generated or saved (and failed cleanup steps) are listed in an end-of-run summary —
  counts per entity type plus up to 20 of the failures — and the command exits with code 1. Reindex and
  cache refresh still run first. Previously it always exited 0, so cron jobs/scripts that check the exit
  code may now start alerting on failures that used to be hidden.
• all-stores runs no longer regenerate every store view twice: the store 0 (default scope) pass now only
  updates default-scope url_key/url_path, and each store view is generated once — with identical
  results; on a two-store-view sample catalog full runs were ~15–30% faster, and the saving grows with the
  number of store views
• category runs with "Use Categories Path for Product URLs" enabled regenerate each affected product once,
  after all categories are done, instead of once per ancestor category (plus a full scan of the
  product/category rewrite table after every category) — identical results; on the sample catalog a full
  category run went from ~22s to ~5s

Fixed

• --store-id=0 (global scope) runs dropped the product rewrites of every store view after the first
  (identical paths in different store views were treated as duplicates) and didn't replace the store views'
  current rewrites, so old URLs kept serving pages and --save-old-urls redirects were lost
• --save-old-urls now actually creates 301 redirects: when a URL changes, the old URL redirects to the
  new one. Before, the old URL kept serving the page as an ordinary rewrite (duplicate content) and the
  redirect Magento generated was silently dropped when saving (#174, #142). This includes switching to
  --add-sku-to-url with --save-old-urls: the old unsuffixed URL now redirects to the SKU URL
• --add-sku-to-url (and path clean-up/de-duplication in general) no longer alters custom URL
  rewrites: admin-created rewrites, and old-URL redirects kept by --save-old-urls, keep their exact
  request path. Before, --add-sku-to-url appended the SKU to them too, so a custom URL like
  promo/sale became promo/sale-<sku> and the original URL stopped working.
• with --add-sku-to-url, custom redirects (and --save-old-urls redirects) pointing at a product's URL
  now follow it to the SKU-suffixed URL; before, they kept pointing at the old unsuffixed URL, which no
  longer existed (redirect to a 404)
• a product/category whose generated URL paths were all empty no longer has its existing rewrites
  touched (nothing to write, so the current rewrites are kept)

[1.9.1] - 2026-08-26

Added

• new options --set-product-suffix / --set-category-suffix — set the product/category URL suffix
  (e.g. .html) before regenerating, via the same write path Magento's own config:set CLI command
  uses, so validation and the automatic suffix swap on existing url_rewrite rows both run. Applied to
  Default Config and every store view, or only the store given via --store-id. If either suffix value
  fails Magento's validation, the whole command aborts before any regeneration runs.

Fixed

• category url_path was not recalculated per store view: when a category's url_path had only ever
  been saved at the default (store 0) scope, Magento's CategoryUrlPathGenerator short-circuited and
  handed back that inherited value instead of building a new one from the store-scoped url_key,
  because the category object's still-populated url_path made its dataHasChangedFor() checks look
  unchanged. Now url_path is cleared on the category object before generation, matching the pattern
  already used on the product side. (#184)

[1.9.0] - 2026-08-11

Added

• new option --skip-products — skip regenerating associated product URLs when regenerating categories (useful on large catalogs when "Use Category Path for Product URLs" is enabled)
• new option --skip-existing — skip an entity entirely if it already has any url_rewrite for the current store, instead of always deleting + regenerating
• new option --include-not-visible — also regenerate URLs for products with visibility "Not Visible Individually" (e.g. configurable child products), excluded by default since 1.6.2
• new option --add-sku-to-url — append the product's SKU as a URL segment in generated product Url Rewrites, e.g. screws.html -> screws-2244000004.html

Fixed

• guard against writing a blank url_key when Magento's own transliteration can't handle the product/category title (e.g. Arabic/other non-Latin scripts)

[1.8.0] - 2026-08-10

Changed

• BREAKING: inverted url_key regeneration default — url_key is no longer regenerated automatically; use the new --regen-url-key option to opt in. The old --no-regen-url-key option is removed entirely (not deprecated) — update any existing scripts/cron jobs that relied on the previous default.
• fixed data loss risk in saveUrlRewrites(): deleting existing rewrites and inserting new ones now happen in a single transaction, so a failed insert can no longer leave an entity with its rewrites deleted and nothing to replace them
• fixed category URL rewrite regeneration to process every category (top level down to the deepest child) instead of only top-level categories, so child categories' own url_key/url_path are regenerated too
• skip writing a redundant per-store url_key override when the regenerated value is identical to the default-scope value

Added

• new option --delete-orphaned-rewrites — deletes url_rewrite rows (for the given --entity-type) whose product/category no longer exists

[1.7.3] - 2026-08-09

Changed

• fixed deprecated non-canonical (double) type cast for PHP 8.5 compatibility
• use the current PHP executable (PHP_BINARY) instead of a hardcoded "php" command for reindex/cache calls
• fixed category URL rewrite regeneration stopping entirely when a single broken/orphaned category is encountered
• added missing type hint and defensive casting in a couple of helper methods
• declared minimum supported PHP version (>=8.2) in composer.json

[1.7.2] - 2026-03-31

Changed

• fixed deprecated functionality: ctype_digit()
• improved SQL safety in URL rewrite regeneration queries
• fixed SQL escaping in URL rewrite cleanup logic
• fixed _clearRequestPath() to correctly handle multiple consecutive slashes
• removed dead code from category URL rewrite model
• display validation errors before command failure
• display a completed progress bar for empty product/category collections
• normalized line endings to LF

[1.7.1] - 2025-05-30

Changed

• adapted for compatibility with PHP 8.4 (deprecated implicitly nullable types)

[1.7.0] - 2025-04-15

Changed

• adapted for compatibility with Magento 2.4.7-p4
• adapted the composer.json file to be compatible with Composer 2

[1.6.2] - 2023-10-10

Changed

• fixed Symfony Command constant issue
• exclude non visible products from url regeneration

[1.6.1] - 2023-08-24

Changed

• fixed compatibility with Symfony Console 5 and Magento 2.4.6
• updated contact email to Gmail email (my own domain olegkoval.com was stolen)

[1.6.0] - 2021-01-27

Changed

• adapted to Magento 2.3.5
• fixed incorrect generation when URL suffix is slash

[1.5.6] - 2020-04-13

Changed

• updated logic of "cleaning" of Url Rewrites and duplications check

[1.5.5] - 2020-04-02

Changed

• updated logic of Url Rewrite regeneration via category entity
• fixed compilation issue in helper

[1.5.4] - 2020-03-21

Changed

• fixed issue of non-empty/non-false "request_path" of product entity.
• modified logic of Url Rewrite db table updates

[1.5.3] - 2020-03-20

Changed

• updated Url Rewrite preparing function
• updated logic of Url Rewrite regeneration via category entity
• updated save logic

[1.5.2] - 2020-03-18

Changed

• updated logic of Url Rewrite regeneration via category entity
• CLI options logic optimized (for category entity)

[1.5.1] - 2020-03-08

Changed

• fixed issue of url_key and url rewrites regeneration based on product name value

[1.5.0] - 2020-02-26

Changed

• revised and restructured code
• modified functional logic of extension
• removed option "--check-use-category-in-product-url"

[1.4.3] - 2019-05-12

Added

• new option "no-regen-url-key"

Changed

• fixed a "typo" issue

[1.4.2] - 2019-04-04

Added

• new option "--check-use-category-in-product-url"
• info into log about conflicted URL Rewrites

Changed

• fixed logical issues in url_key regeneration
• a fix for category/products rewrites for multistore
• fixed issue of division by zero in progress bar
• update the url_key regeneration behavior to use UrlPathGenerators
• modified logic of displaying console messages (notifications, errors, exceptions...)

[1.4.1] - 2019-02-20

Changed

• fixed the issue of removing previously added URL rewrites of product when the same URL key exists;
• modified progress bar

[1.4.0] - 2019-02-11

Added

• new option "--entity-type"
• new option "--products-range"
• new option "--product-id"
• new option "--category-range"
• new option "--category-id"

Changed

• revised and restructured code
• modified logic of url rewrites regeneration
• removed "--clean-url-key"

[1.3.1] - 2018-11-14

Changed

• fixed issue of empty product URL keys
• fixed double slashes issue
• update category attributes via resource saveAttribute()
• use proxy for CategoryUrlPathGenerator

[1.3.0] - 2018-10-29

Added

• new option "--no-cache-clean"
• new option "--no-cache-flush"
• new option "--no-progress"
• new option "--no-clean-url-key"

Changed

• optimized code
• modified logic of url rewrites regeneration
• fixed issue of store filter in a category collection

[1.2.3] - 2018-10-03

Added

• display additional debug information for "URL key for specified store already exists" error

Changed

• modified logic of url rewrites regeneration

[1.2.2] - 2018-10-02

Changed

• fixed setStoreId() on null error

[1.2.1] - 2018-09-25

Changed

• fixed compilation issues

[1.2.0] - 2018-09-25

Changed

• added proxies to CLI commands
• modified logic of url rewrites regeneration
• updated a composer file
• fixed issue of a compatibility with new Magento Commerce versions

[1.1.1] - 2018-09-10

Changed

• fix composer file format issue

[1.1.0] - 2018-09-09

Added

• added feature to add a Pro features through a "Layer" class

Changed

• fix issue when optional arguments require value
• updated a code structure

[1.0.6] - 2018-07-26

Added

• new option to run URL rewrite generation without running full reindex

Changed

• update help notice to show INPUT_KEY_SAVE_REWRITES_HISTORY and INPUT_KEY_NO_REINDEX

[1.0.5] - 2018-05-13

Added

• new option to save current URL rewrites

Changed

• improve the store ID arguments workflow

[1.0.4] - 2017-11-13

Added

• additional checks of storeId argument

[1.0.3] - 2017-10-25

Added

• check if area code is set

[1.0.2] - 2017-10-20

Fixed

• fix "Area code not set" issue

[1.0.1] - 2017-10-10

Fixed

• fix store id issue in collection filter

[1.0.0] - 2017-09-29

Release of Magento 2 "Regenerate Url Rewrites" extension