WordPress.org

Make WordPress Core

#50261 closed defect (bug) (duplicate)

Walker_Nav_Menu doc block is wrong

Reported by: dingo_d Owned by:
Milestone: Priority: normal
Severity: normal Version:
Component: Menus Keywords:
Focuses: docs Cc:

Description

The docblock parameters of class Walker_Nav_Menu (https://developer.wordpress.org/reference/classes/walker_nav_menu/) should be compatible with Walker class (https://developer.wordpress.org/reference/classes/walker/)

For instance, we have in Walker_Nav_Menu

<?php
/**
     * Starts the list before the elements are added.
     *
     * @since 3.0.0
     *
     * @see Walker::start_lvl()
     *
     * @param string   $output Used to append additional content (passed by reference).
     * @param int      $depth  Depth of menu item. Used for padding.
     * @param stdClass $args   An object of wp_nav_menu() arguments.
     */
    public function start_lvl( &$output, $depth = 0, $args = null ) {

Whereas the Walker class has

<?php
/**
     * Starts the list before the elements are added.
     *
     * The $args parameter holds additional values that may be used with the child
     * class methods. This method is called at the start of the output list.
     *
     * @since 2.1.0
     * @abstract
     *
     * @param string $output Used to append additional content (passed by reference).
     * @param int    $depth  Depth of the item.
     * @param array  $args   An array of additional arguments.
     */
    public function start_lvl( &$output, $depth = 0, $args = array() ) {}

Notice the stdClass typehint in the Walker_Nav_Menu class in the third argument, that should be array.

This inconsistency throws tons of false-positive errors when running PHPStan analysis.

Other methods should be fixed as well, and any classes that extend the Walker class should be checked.

Change History (2)

#1 @SergeyBiryukov
17 months ago

Thanks for the ticket, just noting it's not as simple as a documentation change.

The mismatch of the $args parameter between Walker_Nav_Menu and Walker is currently a known long-standing issue that cannot be easily fixed due to backward compatibility problems.

See #24587, [38559], [45537], [47189] for more details.

Last edited 17 months ago by SergeyBiryukov (previous) (diff)

#2 @SergeyBiryukov
17 months ago

  • Keywords needs-patch removed
  • Milestone Awaiting Review deleted
  • Resolution set to duplicate
  • Status changed from new to closed

Since #24587 already has some patches for addressing the inconsistency, let's continue the discussion there.

Note: See TracTickets for help on using tickets.