Rebuild Drupal Pathauto aliases when a menu link moves
If your Pathauto pattern builds a page's URL from its menu parent, such as [node:menu-link:parent:url:path]/[node:title], the alias is only generated when the node itself is saved. Adding the page to a menu, or dragging it under a different parent on the menu screen, leaves the old URL in place. The fix is to regenerate the alias yourself from hook_menu_link_content_insert() and hook_menu_link_content_update(), cascade the change to child pages from hook_path_alias_update(), and push the deeper levels onto a queue so a large section doesn't rebuild in one request.
Why menu-based aliases go stale
On a decoupled Drupal site I work on, basic pages and department pages take their address from where they sit in the main menu. For example, a page called "Permits" under "Planning" would live at /planning/permits. Editors expect that to follow the menu: move the link, and the URL moves with it.
Pathauto doesn't work that way. It generates aliases in response to entity saves of the entity being aliased. A menu link is a separate entity (menu_link_content), so saving it on the menu admin screen never reaches Pathauto. The page keeps its old address until someone happens to edit and save the node, at which point the URL suddenly changes for a reason nobody connects to the menu edit from weeks before.
There's a second layer of the same problem. Children build their addresses from their parent's address, so renaming "Planning" to "Planning and zoning" should move every page beneath it. Pathauto has no idea those pages depend on their parent's alias.
How to regenerate the alias from a menu change
Pathauto exposes its generator as a service, so you can ask it to rebuild a node's alias at any time with updateEntityAlias($node, 'update'). The work is deciding when to call it, and remembering one cache that will otherwise hand you the old answer.
use Drupal\menu_link_content\MenuLinkContentInterface;
use Drupal\node\Entity\Node;
use Drupal\node\NodeInterface;
function mymodule_menu_link_content_insert(MenuLinkContentInterface $link): void {
mymodule_rebuild_alias_for_link($link);
}
function mymodule_menu_link_content_update(MenuLinkContentInterface $link): void {
// Only a new parent changes a menu-based address.
$original = $link->getOriginal();
if ($original && $original->getParentId() === $link->getParentId()) {
return;
}
mymodule_rebuild_alias_for_link($link);
}
function mymodule_rebuild_alias_for_link(MenuLinkContentInterface $link): void {
$url = $link->getUrlObject();
if (!$url->isRouted() || $url->getRouteName() !== 'entity.node.canonical') {
return;
}
$node = Node::load($url->getRouteParameters()['node']);
if ($node) {
mymodule_rebuild_alias($node);
}
}
function mymodule_rebuild_alias(NodeInterface $node): void {
// Token caches each link's parents for the rest of the request.
drupal_static_reset('token_menu_link_load_all_parents');
\Drupal::service('pathauto.generator')->updateEntityAlias($node, 'update');
}
The drupal_static_reset() line is the easy one to miss. The Token module looks up a link's menu parents once and keeps them in a static for the rest of the request. If anything earlier in the request already resolved that page's parents, Pathauto gets the old parent and rebuilds exactly the alias you already had.
getOriginal() is the Drupal 11.2+ accessor; on older versions use the ->original property.
Notice the update hook only reacts to a change of parent. The first version also rebuilt when the link's target changed, which turned out to be the wrong call: pointing an existing menu item at a different page shouldn't rename that page. Rebuild on the thing the pattern actually reads.
How to cascade a renamed section to its children
When a page's alias changes, every page under it in the menu is now wrong. hook_path_alias_update() fires when any alias changes, including the one you just rebuilt, so that's where the cascade goes: find the menu links pointing at the node, load their child links, and rebuild each child's alias. Each child's rebuild changes its alias, which fires the hook again for its own children.
That recursion is fine for a small menu and a problem for a big one. Renaming a top-level section on a large site can touch a large share of the site inside the editor's save request. The approach that worked: rebuild the direct children immediately, so the editor sees the obvious effect at once, and send every level below that to a Drupal queue. A QueueWorker plugin with a cron time limit works through it, and each item it processes queues its own children in turn.
The switch between "rebuild now" and "queue it" is a static flag. It's set while a direct child is being rebuilt, so any alias change that happens inside that rebuild queues its children instead of recursing. The queue worker sets the same flag around its own work. A try/finally around the rebuild makes sure a failure doesn't leave the flag on for the rest of the request.
Two settings make the cascade safe to run. Pathauto skips nodes whose alias was set by hand (unchecked "Generate automatic URL alias"), so custom addresses survive. And the Redirect module, with automatic redirects turned on, adds a redirect from each old alias to the new one, so links people bookmarked keep working.
Watch for a redirect that points a page at itself
Automatic redirects have one trap. Move a page away and then back, and there's now a redirect whose source is the page's current address. The Redirect module normally deletes a redirect that matches a new alias, but only for the alias's language. A redirect stored without a language survived, and sent the page to itself.
The fix was one line in the alias update hook: delete any redirect whose source is the new alias, regardless of language, before doing anything else. If you rely on automatic redirects and editors reorganise menus often, it's worth checking for this even if you never cascade aliases.
What a decoupled front end needs on top
On a traditional Drupal site, a new alias is visible on the next request. On a decoupled site, the front end has cached the old path lookup and every page that links to the moved one. So whenever a rebuild actually changes the alias, two more things happen: the node's cache tags are invalidated, so Drupal's own cached route lookups stop resolving the old address, and the front end is told the node changed, exactly as a node save would. With the Next.js module for Drupal (drupal/next) that's an entity action event for the node.
The same gap showed up for publishing. Menus leave out links to unpublished pages, but publishing or unpublishing a page only revalidated that page, so the header and sidebars kept showing, or kept missing, its link. Re-saving the node's menu links, unchanged, when its published state flips was enough to make the menus revalidate the same way a menu edit does. Comparing the published flag against the original keeps that from running on every ordinary edit.
Key takeaways
- Pathauto only regenerates an alias when the aliased entity is saved, so menu-based patterns need hooks on menu link insert and update.
- Reset Token's static cache of menu parents before regenerating, or Pathauto can rebuild the old alias within the same request.
- Cascade alias changes to child pages from hook_path_alias_update(), rebuilding direct children at once and queueing deeper levels for cron.
- Delete any redirect whose source matches a page's new alias, whatever its language, or moving a page back can make it redirect to itself.
- On a decoupled site, invalidate the node's cache tags and notify the front end whenever a rebuild changes an alias or a page's published state.