wp_update_nav_menu_item

Save the properties of a menu item or create a new one.

Description

(int|WP_Error) wp_update_nav_menu_item( (int) $menu_id = 0, (int) $menu_item_db_id = 0, (array) $menu_item_data = array() ); 

The menu-item-title, menu-item-description, and menu-item-attr-title are expected to be pre-slashed since they are passed directly into wp_insert_post()..

Returns (int|WP_Error)

The menu item's database ID or WP_Error object on failure.

Parameters (3)

0. $menu_id — Optional. (int)
The ID of the menu. Required. If 0,, makes the menu item a draft orphan.
1. $menu_item_db_id — Optional. (int)
The ID of the menu item. If 0,, creates a new menu item.
2. $menu_item_data — Optional. (array) => array()
The menu item's data.

Usage

  1. if ( !function_exists( 'wp_update_nav_menu_item' ) ) { 
  2. require_once ABSPATH . WPINC . '/nav-menu.php'; 
  3.  
  4. // The ID of the menu. Required. If "0", makes the menu item a draft orphan. 
  5. $menu_id = -1; 
  6.  
  7. // The ID of the menu item. If "0", creates a new menu item. 
  8. $menu_item_db_id = -1; 
  9.  
  10. // The menu item's data. 
  11. $menu_item_data = array(); 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = wp_update_nav_menu_item($menu_id, $menu_item_db_id, $menu_item_data); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/nav-menu.php  
  1. function wp_update_nav_menu_item( $menu_id = 0, $menu_item_db_id = 0, $menu_item_data = array() ) { 
  2. $menu_id = (int) $menu_id; 
  3. $menu_item_db_id = (int) $menu_item_db_id; 
  4.  
  5. // make sure that we don't convert non-nav_menu_item objects into nav_menu_item objects 
  6. if ( ! empty( $menu_item_db_id ) && ! is_nav_menu_item( $menu_item_db_id ) ) 
  7. return new WP_Error( 'update_nav_menu_item_failed', __( 'The given object ID is not that of a menu item.' ) ); 
  8.  
  9. $menu = wp_get_nav_menu_object( $menu_id ); 
  10.  
  11. if ( ! $menu && 0 !== $menu_id ) { 
  12. return new WP_Error( 'invalid_menu_id', __( 'Invalid menu ID.' ) ); 
  13.  
  14. if ( is_wp_error( $menu ) ) { 
  15. return $menu; 
  16.  
  17. $defaults = array( 
  18. 'menu-item-db-id' => $menu_item_db_id,  
  19. 'menu-item-object-id' => 0,  
  20. 'menu-item-object' => '',  
  21. 'menu-item-parent-id' => 0,  
  22. 'menu-item-position' => 0,  
  23. 'menu-item-type' => 'custom',  
  24. 'menu-item-title' => '',  
  25. 'menu-item-url' => '',  
  26. 'menu-item-description' => '',  
  27. 'menu-item-attr-title' => '',  
  28. 'menu-item-target' => '',  
  29. 'menu-item-classes' => '',  
  30. 'menu-item-xfn' => '',  
  31. 'menu-item-status' => '',  
  32. ); 
  33.  
  34. $args = wp_parse_args( $menu_item_data, $defaults ); 
  35.  
  36. if ( 0 == $menu_id ) { 
  37. $args['menu-item-position'] = 1; 
  38. } elseif ( 0 == (int) $args['menu-item-position'] ) { 
  39. $menu_items = 0 == $menu_id ? array() : (array) wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'publish, draft' ) ); 
  40. $last_item = array_pop( $menu_items ); 
  41. $args['menu-item-position'] = ( $last_item && isset( $last_item->menu_order ) ) ? 1 + $last_item->menu_order : count( $menu_items ); 
  42.  
  43. $original_parent = 0 < $menu_item_db_id ? get_post_field( 'post_parent', $menu_item_db_id ) : 0; 
  44.  
  45. if ( 'custom' != $args['menu-item-type'] ) { 
  46. /** if non-custom menu item, then: 
  47. * use original object's URL 
  48. * blank default title to sync with original object's 
  49. */ 
  50.  
  51. $args['menu-item-url'] = ''; 
  52.  
  53. $original_title = ''; 
  54. if ( 'taxonomy' == $args['menu-item-type'] ) { 
  55. $original_parent = get_term_field( 'parent', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' ); 
  56. $original_title = get_term_field( 'name', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' ); 
  57. } elseif ( 'post_type' == $args['menu-item-type'] ) { 
  58.  
  59. $original_object = get_post( $args['menu-item-object-id'] ); 
  60. $original_parent = (int) $original_object->post_parent; 
  61. $original_title = $original_object->post_title; 
  62. } elseif ( 'post_type_archive' == $args['menu-item-type'] ) { 
  63. $original_object = get_post_type_object( $args['menu-item-object'] ); 
  64. if ( $original_object ) { 
  65. $original_title = $original_object->labels->archives; 
  66.  
  67. if ( $args['menu-item-title'] == $original_title ) 
  68. $args['menu-item-title'] = ''; 
  69.  
  70. // hack to getwpto create a post object when too many properties are empty 
  71. if ( '' == $args['menu-item-title'] && '' == $args['menu-item-description'] ) 
  72. $args['menu-item-description'] = ' '; 
  73.  
  74. // Populate the menu item object 
  75. $post = array( 
  76. 'menu_order' => $args['menu-item-position'],  
  77. 'ping_status' => 0,  
  78. 'post_content' => $args['menu-item-description'],  
  79. 'post_excerpt' => $args['menu-item-attr-title'],  
  80. 'post_parent' => $original_parent,  
  81. 'post_title' => $args['menu-item-title'],  
  82. 'post_type' => 'nav_menu_item',  
  83. ); 
  84.  
  85. $update = 0 != $menu_item_db_id; 
  86.  
  87. // New menu item. Default is draft status 
  88. if ( ! $update ) { 
  89. $post['ID'] = 0; 
  90. $post['post_status'] = 'publish' == $args['menu-item-status'] ? 'publish' : 'draft'; 
  91. $menu_item_db_id = wp_insert_post( $post ); 
  92. if ( ! $menu_item_db_id || is_wp_error( $menu_item_db_id ) ) 
  93. return $menu_item_db_id; 
  94.  
  95. /** 
  96. * Fires immediately after a new navigation menu item has been added. 
  97. * @since 4.4.0 
  98. * @see wp_update_nav_menu_item() 
  99. * @param int $menu_id ID of the updated menu. 
  100. * @param int $menu_item_db_id ID of the new menu item. 
  101. * @param array $args An array of arguments used to update/add the menu item. 
  102. */ 
  103. do_action( 'wp_add_nav_menu_item', $menu_id, $menu_item_db_id, $args ); 
  104.  
  105. // Associate the menu item with the menu term 
  106. // Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms() 
  107. if ( $menu_id && ( ! $update || ! is_object_in_term( $menu_item_db_id, 'nav_menu', (int) $menu->term_id ) ) ) { 
  108. wp_set_object_terms( $menu_item_db_id, array( $menu->term_id ), 'nav_menu' ); 
  109.  
  110. if ( 'custom' == $args['menu-item-type'] ) { 
  111. $args['menu-item-object-id'] = $menu_item_db_id; 
  112. $args['menu-item-object'] = 'custom'; 
  113.  
  114. $menu_item_db_id = (int) $menu_item_db_id; 
  115.  
  116. update_post_meta( $menu_item_db_id, '_menu_item_type', sanitize_key($args['menu-item-type']) ); 
  117. update_post_meta( $menu_item_db_id, '_menu_item_menu_item_parent', strval( (int) $args['menu-item-parent-id'] ) ); 
  118. update_post_meta( $menu_item_db_id, '_menu_item_object_id', strval( (int) $args['menu-item-object-id'] ) ); 
  119. update_post_meta( $menu_item_db_id, '_menu_item_object', sanitize_key($args['menu-item-object']) ); 
  120. update_post_meta( $menu_item_db_id, '_menu_item_target', sanitize_key($args['menu-item-target']) ); 
  121.  
  122. $args['menu-item-classes'] = array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-classes'] ) ); 
  123. $args['menu-item-xfn'] = implode( ' ', array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-xfn'] ) ) ); 
  124. update_post_meta( $menu_item_db_id, '_menu_item_classes', $args['menu-item-classes'] ); 
  125. update_post_meta( $menu_item_db_id, '_menu_item_xfn', $args['menu-item-xfn'] ); 
  126. update_post_meta( $menu_item_db_id, '_menu_item_url', esc_url_raw($args['menu-item-url']) ); 
  127.  
  128. if ( 0 == $menu_id ) 
  129. update_post_meta( $menu_item_db_id, '_menu_item_orphaned', (string) time() ); 
  130. elseif ( get_post_meta( $menu_item_db_id, '_menu_item_orphaned' ) ) 
  131. delete_post_meta( $menu_item_db_id, '_menu_item_orphaned' ); 
  132.  
  133. // Update existing menu item. Default is publish status 
  134. if ( $update ) { 
  135. $post['ID'] = $menu_item_db_id; 
  136. $post['post_status'] = 'draft' == $args['menu-item-status'] ? 'draft' : 'publish'; 
  137. wp_update_post( $post ); 
  138.  
  139. /** 
  140. * Fires after a navigation menu item has been updated. 
  141. * @since 3.0.0 
  142. * @see wp_update_nav_menu_item() 
  143. * @param int $menu_id ID of the updated menu. 
  144. * @param int $menu_item_db_id ID of the updated menu item. 
  145. * @param array $args An array of arguments used to update a menu item. 
  146. */ 
  147. do_action( 'wp_update_nav_menu_item', $menu_id, $menu_item_db_id, $args ); 
  148.  
  149. return $menu_item_db_id;