Abstract class for displaying hierarchical tree structures.

Since: 2.1.0
Source: wp-includes/class-wp-walker.php

Class Synopsis

#[AllowDynamicProperties]
class Walker {
    // Properties
    public string   $tree_type;
    public string[] $db_fields;
    public int      $max_pages = 1;
    public bool     $has_children;
    
    // Abstract methods (override in child classes)
    public function start_lvl( &$output, $depth = 0, $args = [] );
    public function end_lvl( &$output, $depth = 0, $args = [] );
    public function start_el( &$output, $data_object, $depth = 0, $args = [], $current_object_id = 0 );
    public function end_el( &$output, $data_object, $depth = 0, $args = [] );
    
    // Traversal methods
    public function walk( $elements, $max_depth, ...$args ): string;
    public function paged_walk( $elements, $max_depth, $page_num, $per_page, ...$args ): string;
    public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output );
    public function get_number_of_root_elements( $elements ): int;
    public function unset_children( $element, &$children_elements );
}

Properties

$tree_type

public string $tree_type;

Identifies what type of data this walker handles. Examples: 'category', 'page', 'comment'.

$db_fields

public string[] $db_fields;

Maps the element’s ID and parent fields:

public $db_fields = [
    'parent' => 'parent',    // Field name containing parent ID
    'id'     => 'term_id',   // Field name containing element ID
];

$max_pages

public int $max_pages = 1;

Set by paged_walk() after traversal. Contains the total number of pages for the element set.

$has_children

public bool $has_children;

Since: 4.0.0

Set before calling start_el(). Indicates whether the current element has children. Useful for adding CSS classes like 'has-children'.

Abstract Methods

These methods are empty in the base class. Override them to generate output.

start_lvl()

public function start_lvl( &$output, $depth = 0, $args = [] )

Called before outputting child elements. Typically opens a <ul> or similar container.

end_lvl()

public function end_lvl( &$output, $depth = 0, $args = [] )

Called after outputting child elements. Closes the container opened by start_lvl().

start_el()

public function start_el( &$output, $data_object, $depth = 0, $args = [], $current_object_id = 0 )

Outputs the beginning of an element.

Note: Parameter was renamed from $object to $data_object in WP 5.9.0 for PHP 8 named parameter support.

end_el()

public function end_el( &$output, $data_object, $depth = 0, $args = [] )

Outputs the end of an element. Typically closes tags opened in start_el().

Traversal Methods

walk()

public function walk( $elements, $max_depth, ...$args ): string

Main entry point. Traverses elements and returns HTML output.

Returns: string — The generated HTML.

Depth Values:

paged_walk()

public function paged_walk( $elements, $max_depth, $page_num, $per_page, ...$args ): string

Since: 2.7.0

Produces a single page of nested elements. Used for paginated displays like threaded comments.

Returns: string — HTML for the requested page.

After calling, $this->max_pages contains the total page count.

Special args:

• $args[0]['reverse_top_level'] — Reverse root element order
• $args[0]['reverse_children'] — Reverse child element order

display_element()

public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output )

Recursive method that renders a single element and its descendants. Called internally by walk().

Flow:

1. Sets $this->has_children
2. Calls start_el()
3. If depth allows and children exist:
   • Calls start_lvl()
   • Recursively processes children
   • Removes processed children from $children_elements
   • Calls end_lvl()
4. Calls end_el()

get_number_of_root_elements()

public function get_number_of_root_elements( $elements ): int

Since: 2.7.0

Counts elements with an empty parent field.

unset_children()

public function unset_children( $element, &$children_elements )

Since: 2.7.0

Recursively removes an element’s descendants from $children_elements. Used by paged_walk() to prevent orphans from appearing on wrong pages.

Usage Example

// Using with wp_list_categories()
$walker = new Walker_Category();
$output = $walker->walk(
    get_terms( [ 'taxonomy' => 'category', 'hide_empty' => false ] ),
    0,  // Unlimited depth
    [ 'style' => 'list', 'show_count' => true ]
);

// Custom walker
class Simple_Walker extends Walker {
    public $tree_type = 'item';
    public $db_fields = [ 'parent' => 'parent_id', 'id' => 'id' ];
    
    public function start_el( &$output, $item, $depth = 0, $args = [], $current = 0 ) {
        $indent = str_repeat( '  ', $depth );
        $output .= $indent . "- {$item->name}n";
    }
}

Implementation Notes

1. Pass by reference — Output is built by appending to $output reference, not by returning values
2. Orphan recovery — If no root elements exist, the first element’s parent is treated as the root level
3. Dynamic properties — The #[AllowDynamicProperties] attribute allows child classes to add custom properties
4. Backward compatibility — $args[0]['has_children'] is set for back-compat with older walker implementations