dynamic_sidebar( int|string $index = 1 ): bool
- Since
- 2.2.0
- Source
wp-includes/widgets.php:697
Description
By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or 'name' parameter for its registered sidebars you can pass an ID or name as the $index parameter.
Otherwise, you can pass in a numerical index to display the sidebar at that index.
Compatibility
- WordPress
- since 2.2.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$indexint|stringoptional- Index, name or ID of dynamic sidebar. Default 1.Default:
1
Return value
bool- True, if widget sidebar was found and called. False if not found or not called.
Performance profile
How much work a call to dynamic_sidebar() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Heavy
- Scaling
- Scales with input
- Instructions
- 28–79
- Plugin surface
- 5 hooks
- Called by
- 2
Reads stored settings via get_option(), cached per request but not free on a cold cache.
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 175.
Third-party callbacks on 'dynamic_sidebar_before', 'dynamic_sidebar_after', 'dynamic_sidebar_has_widgets' run inside this call, and their cost is not bounded by anything here.
2 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
do_action()called directly - optionoption read or write
get_option()one call below dynamic_sidebar()
Further down the call graph this can also reach cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 6 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost dynamic_sidebar() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
is_int($index) | 28–33 | wp_get_sidebars_widgets(), do_action(), do_action(), apply_filters() |
!is_int($index) | 33–39 | sanitize_title(), wp_get_sidebars_widgets(), do_action(), do_action(), apply_filters() |
!is_int($index) && !$wp_registered_sidebars && $index === false | 43–48 | sanitize_title(), sanitize_title(), wp_get_sidebars_widgets(), do_action(), do_action(), apply_filters() |
is_int($index) && !empty($wp_registered_sidebars[$index]) && !empty($sidebars_widgets[$index]) | 55–64 | wp_get_sidebars_widgets(), sprintf(), do_action(), is_admin(), is_admin(), do_action(), apply_filters() |
!is_int($index) && !empty($wp_registered_sidebars[$index]) && !empty($sidebars_widgets[$index]) | 60–70 | sanitize_title(), wp_get_sidebars_widgets(), sprintf(), do_action(), is_admin(), is_admin(), do_action(), apply_filters() |
!is_int($index) && !$wp_registered_sidebars && $index === false && !empty($wp_registered_sidebars[$index]) && !empty($sidebars_widgets[$index]) | 70–79 | sanitize_title(), sanitize_title(), wp_get_sidebars_widgets(), sprintf(), do_action(), is_admin(), is_admin(), do_action(), apply_filters() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 175 | 28–79 | 19 | |
| 8.5 | 175 | 28–79 | 19 | |
| 8.4 | 175 | 28–79 | 19 | 3 fewer instructions than PHP 8.3 |
| 8.3 | 178 | 28–79 | 19 | |
| 8.2 | 178 | 28–79 | 19 | |
| 8.1 | 178 | 28–79 | 19 | 1 more instruction than PHP 7.4 |
| 7.4 | 177 | 28–79 | 19 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 8
8 hooks fire while dynamic_sidebar() runs, in this order:
- do_action( dynamic_sidebar_before )actionline 715 (+18 into the body)
Fires before widgets are rendered in a dynamic sidebar.
- do_action( dynamic_sidebar_after )actionline 717 (+20 into the body)
Fires after widgets are rendered in a dynamic sidebar.
- apply_filters( dynamic_sidebar_has_widgets )filterline 719 (+22 into the body)
Filters whether a sidebar has widgets.
- do_action( dynamic_sidebar_before )actionline 738 (+41 into the body)
Fires before widgets are rendered in a dynamic sidebar.
- apply_filters( dynamic_sidebar_params )filterline 813 (+116 into the body)
Filters the parameters passed to a widget's display callback.
- do_action( dynamic_sidebar )actionline 842 (+145 into the body)
Fires before a widget's display callback is called.
- do_action( dynamic_sidebar_after )actionline 866 (+169 into the body)
Fires after widgets are rendered in a dynamic sidebar.
- apply_filters( dynamic_sidebar_has_widgets )filterline 880 (+183 into the body)
Filters whether a sidebar has widgets.
Uses · 5
- sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
- wp_get_sidebars_widgets()Retrieves the full list of sidebars and their widget instance IDs.
- do_action()Calls the callback functions that have been added to an action hook.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- is_admin()Determines whether the current request is for an administrative interface page.
Used by · 2
- WP_Customize_Widgets::render_widget_partial()Renders a specific widget using the supplied sidebar arguments.
- wp_list_widget_controls()Show the widgets and their settings for a sidebar.
Source code
function dynamic_sidebar( $index = 1 ) { global $wp_registered_sidebars, $wp_registered_widgets; if ( is_int( $index ) ) { $index = "sidebar-$index"; } else { $index = sanitize_title( $index ); foreach ( (array) $wp_registered_sidebars as $key => $value ) { if ( sanitize_title( $value['name'] ) === $index ) { $index = $key; break; } } } $sidebars_widgets = wp_get_sidebars_widgets(); if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { /** This action is documented in wp-includes/widget.php */ do_action( 'dynamic_sidebar_before', $index, false ); /** This action is documented in wp-includes/widget.php */ do_action( 'dynamic_sidebar_after', $index, false ); /** This filter is documented in wp-includes/widget.php */ return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); } $sidebar = $wp_registered_sidebars[ $index ]; $sidebar['before_sidebar'] = sprintf( $sidebar['before_sidebar'], $sidebar['id'], $sidebar['class'] ); /** * Fires before widgets are rendered in a dynamic sidebar. * * Note: The action also fires for empty sidebars, and on both the front end * and back end, including the Inactive Widgets sidebar on the Widgets screen. * * @since 3.9.0 * * @param int|string $index Index, name, or ID of the dynamic sidebar. * @param bool $has_widgets Whether the sidebar is populated with widgets. * Default true. */ do_action( 'dynamic_sidebar_before', $index, true ); if ( ! is_admin() && ! empty( $sidebar['before_sidebar'] ) ) { echo $sidebar['before_sidebar']; } $did_one = false; foreach ( (array) $sidebars_widgets[ $index ] as $id ) { if ( ! isset( $wp_registered_widgets[ $id ] ) ) { continue; } $params = array_merge( array( array_merge( $sidebar, array( 'widget_id' => $id, 'widget_name' => $wp_registered_widgets[ $id ]['name'], ) ), ), (array) $wp_registered_widgets[ $id ]['params'] ); // Substitute HTML `id` and `class` attributes into `before_widget`. $classname_ = ''; foreach ( (array) $wp_registered_widgets[ $id ]['classname'] as $cn ) { if ( is_string( $cn ) ) { $classname_ .= '_' . $cn; } elseif ( is_object( $cn ) ) { $classname_ .= '_' . get_class( $cn ); } } $classname_ = ltrim( $classname_, '_' ); $params[0]['before_widget'] = sprintf( $params[0]['before_widget'],Changelog
Introduced in 2.2.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 6.8.8 tag, from
src/wp-includes/widgets.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.