Support a parent_path setting in hook_menu(). / hook_menu_link_alter() should not touch the plid.

Three suggested steps to clean up (and speed up) _menu_navigation_links_rebuild():

1. Support a parent_path setting in hook_menu(), to determine the parent.
2. Do NOT allow changing of plid, menu_name (and thus, depth) in hook_menu_link_alter(). At the time this hook fires, we should already know the position in the tree. The ticket is bought, there is no trip cancellation insurance. See below why.
3. Rewrite _menu_navigation_links_rebuild() accordingly.

Benefits:
- faster rebuild.
- more robust and predictable rebuild.

How much of that is going to survive in Symfony land, or backported to D7?
I don't know. I want to get this in before hook_menu() officially dies.

I am working on a patch.
But it would be great to have some feedback on the suggested API change.

From #1830234: commerce_kickstart_menus_menu_link_alter() should not change the plid of customized items. (adapted):

Longer explanation:
I came through this while trying to rewrite _menu_navigation_links_rebuild() for performance sake.
#1010480-64: Optimize _menu_navigation_links_rebuild()

During this work I bumped into hook_menu_link_alter().
This is a beast of a hook. I will explain why.

Where is hook_menu_link_alter() invoked?

http://drupalcontrib.org/api/drupal/drupal%21modules%21system%21system.a...

The hook is fired during menu_link_save(). This is called in multiple occasions:

• During _menu_navigation_links_rebuild(), for "non-customized" (*) links that are being reset to the newest state from menu_router.
• During _menu_navigation_links_rebuild(), for "customized" links that are moved around because the parent has changed or disappeared.
• On form submission, for then "customized" links, when the user wants to update this link.
• On form submission, for any links, when the user has modified a parent, and the children need to be moved around.

Maybe I missed some.

(*): A "customized" link is something a user has edited. During _menu_navigation_links_rebuild(), non-customized links are updated with data from menu_router: They get an updated title, etc. Customized links are not updated from menu_router, except for the router path.

What happens in hook_menu_link_alter() implementations?

I would classify the implementations of hook_menu_link_alter() into these two classes:

• Implementations that look at plid, depth and menu_name, and adjust other values.
• Implementations that change the plid and menu_name (and thus the depth):
  commerce_kickstart_menus
  page_manager (that's disabled and tagged as "concept code")
  user (setting the plid to 0 - only for non-customized items).

Having both of these in one hook makes for a perfect chicken-and-egg problem.
(This alone could be solved by proper sorting of those hook implementations.)

Besides, this makes it really hard to work on _menu_navigation_links_rebuild():
- It is hard to predict where a menu item will end up in the tree, if in the last moment some module can send it somewhere else.
- We don't want modules to do select queries on a half-broken or out-of-date menu_links table.

If I were to decide that for core:
- hook_menu_link_alter() should be forbidden to set plid.
- Instead, core _menu_navigation_links_rebuild() should respect a 'parent_path' setting in menu_router. This can be set to FALSE, to set the plid to 0.