[wp-trac] [WordPress Trac] #65079: block_core_navigation_get_inner_blocks_from_unstable_location() calls deprecated function; deprecated docblock references non-existent replacement

[WordPress Trac]

#65079: block_core_navigation_get_inner_blocks_from_unstable_location() calls
deprecated function; deprecated   docblock references non-existent
replacement
------------------------------------+-------------------------------------
 Reporter:  saratheonline           |      Owner:  saratheonline
     Type:  defect (bug)            |     Status:  assigned
 Priority:  normal                  |  Milestone:  Awaiting Review
Component:  Editor                  |    Version:  trunk
 Severity:  normal                  |   Keywords:  has-patch needs-testing
  Focuses:  docs, coding-standards  |
------------------------------------+-------------------------------------
 There are two related issues in src/wp-includes/blocks/navigation.php that
 were introduced when
   block_core_navigation_get_inner_blocks_from_unstable_location() was
 added in 6.5.0.
   \\**Issue 1** — Function added in 6.5.0 calls a function that was
 deprecated in 6.3.0
   block_core_navigation_get_inner_blocks_from_unstable_location() (added
 @since 6.5.0) calls
   block_core_navigation_parse_blocks_from_menu_items():
 {{{
 // src/wp-includes/blocks/navigation.php
   function block_core_navigation_get_inner_blocks_from_unstable_location(
 $attributes ) {
       $menu_items = block_core_navigation_get_menu_items_at_location(
 $attributes['__unstableLocation']);
       if ( empty( $menu_items ) ) {
           return new WP_Block_List( array(), $attributes );
       }

       $menu_items_by_parent_id =
 block_core_navigation_sort_menu_items_by_parent_id( $menu_items );
       $parsed_blocks           =
 block_core_navigation_parse_blocks_from_menu_items(
   $menu_items_by_parent_id[0], $menu_items_by_parent_id ); // <-- calls
 deprecated
       return new WP_Block_List( $parsed_blocks, $attributes );
   }
 }}}
   block_core_navigation_parse_blocks_from_menu_items() was deprecated in
 6.3.0 and triggers a
   _deprecated_function() notice:
 {{{
 // src/wp-includes/blocks/navigation.php
   function block_core_navigation_parse_blocks_from_menu_items(
 $menu_items, $menu_items_by_parent_id ) {
       _deprecated_function( __FUNCTION__, '6.3.0',
 'WP_Navigation_Fallback::parse_blocks_from_menu_items');
       ...
   }
 }}}
   This means on any site using a Navigation block with the
 `__unstableLocation attribute` (classic menu location fallback), every
 page render triggers a deprecated function notice when WP_DEBUG is
 enabled.
   \\**Issue 2** — The deprecated function's docblock points to a non-
 existent replacement
   The `@deprecated` tag on
 `block_core_navigation_parse_blocks_from_menu_items()` says:
 {{{
 @deprecated 6.3.0 Use
 WP_Navigation_Fallback::parse_blocks_from_menu_items() instead.
 }}}
   However, `WP_Navigation_Fallback` (introduced in 6.3.0, src/wp-includes
 /class-wp-navigation-fallback.php) has no method named
 `parse_blocks_from_menu_items`. The equivalent logic was moved to the
 private method `WP_Classic_To_Block_Menu_Converter::to_blocks()` in the
 same release.
   \\The incorrect docblock would mislead any developer following the
 deprecation notice trying to find the correct replacement.
   \\**Issue** 3 — Missing null-coalescing fallback on the same line
   The call accesses `$menu_items_by_parent_id[0]` directly without a null
 coalesce:
 {{{
 $parsed_blocks = block_core_navigation_parse_blocks_from_menu_items(
 $menu_items_by_parent_id[0], ...);
 }}}
   Compare this with the identical pattern at (inside the already-
 deprecated `block_core_navigation_get_classic_menu_fallback_blocks()`)
 which correctly guards the access:
 {{{
 $inner_blocks = block_core_navigation_parse_blocks_from_menu_items(
       $menu_items_by_parent_id[0] ?? array(),
       $menu_items_by_parent_id
   );
 }}}
   `block_core_navigation_sort_menu_items_by_parent_id()` groups items by
 menu_item_parent. If (through data corruption or an unusual data source)
 all items carry a non-zero parent ID, the 0 key will be absent and the
 direct access generates an undefined array key notice on PHP 8.x.
   \\**Steps to Reproduce** \\1. Enable WP_DEBUG and WP_DEBUG_LOG in wp-
 config.php. \\ 2. Create a Navigation block that uses a classic menu via
 the `__unstableLocation` attribute (i.e., a theme location fallback menu).
 \\3. Load any front-end page that renders the Navigation block. \\4. Check
 the debug log — a _deprecated_function notice for
 `block_core_navigation_parse_blocks_from_menu_items` appears on every
 request. \\\\**Expected Behavior** \\ - No deprecated function notices are
 triggered. \\-
 block_core_navigation_get_inner_blocks_from_unstable_location() uses the
 non-deprecated code path. \\- The deprecated function's docblock correctly
 identifies its replacement.\\\\**Actual Behavior** `_deprecated_function(
 'block_core_navigation_parse_blocks_from_menu_items', '6.3.0',
 'WP_Navigation_Fallback::parse_blocks_from_menu_items' )` is triggered on
 every page render where the Navigation block is present with
 `__unstableLocation`.
 \\**Proposed Fix** \\Step 1. Make
 `WP_Classic_To_Block_Menu_Converter::group_by_parent_id()` and
 `::to_blocks()` public (they are currently private), or add a new public
 static method that accepts $menu_items and returns parsed blocks —
 mirroring what `block_core_navigation_parse_blocks_from_menu_items()`
 does.
 \\Step 2. Update
 `block_core_navigation_get_inner_blocks_from_unstable_location()` to call
 the new public method with the null-coalesce guard:
 {{{
 function block_core_navigation_get_inner_blocks_from_unstable_location(
 $attributes ) {
       $menu_items = block_core_navigation_get_menu_items_at_location(
 $attributes['__unstableLocation'] );
       if ( empty( $menu_items ) ) {
           return new WP_Block_List( array(), $attributes );
       }

       $menu_items_by_parent_id =
 block_core_navigation_sort_menu_items_by_parent_id( $menu_items );
       $parsed_blocks           =
 WP_Classic_To_Block_Menu_Converter::to_blocks(
           $menu_items_by_parent_id[0] ?? array(),
           $menu_items_by_parent_id
       );
       return new WP_Block_List( $parsed_blocks, $attributes );
   }
 }}}
 \\Step 3. Correct the @deprecated docblock on
 `block_core_navigation_parse_blocks_from_menu_items()` to reference the
 actual replacement:
 {{{
 - * @deprecated 6.3.0 Use
 `WP_Navigation_Fallback::parse_blocks_from_menu_items()` instead.
 + * @deprecated 6.3.0 Use
 `WP_Classic_To_Block_Menu_Converter::to_blocks()` instead.
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65079>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform