[wp-trac] [WordPress Trac] #61738: Docs: Improve docs to include recommendations for changing existing admin bar menu items (was: admin_bar_menu node my-account returns null)

[WordPress Trac]

#61738: Docs: Improve docs to include recommendations for changing existing admin
bar menu items
-------------------------------------------------+-------------------------
 Reporter:  michaelwp85                          |       Owner:
                                                 |  hellofromTonya
     Type:  defect (bug)                         |      Status:  closed
 Priority:  normal                               |   Milestone:  6.6.2
Component:  Toolbar                              |     Version:  6.6.1
 Severity:  normal                               |  Resolution:  fixed
 Keywords:  needs-dev-note has-patch commit      |     Focuses:  docs
  fixed-major dev-reviewed fixed-minor           |
-------------------------------------------------+-------------------------

Old description:

> Getting admin bar node "my-account" returns null after updating to 6.6.1
>
> {{{#!php
> <?php
> add_action('admin_bar_menu', function (WP_Admin_Bar $adminBar):
> WP_Admin_Bar {
>   var_dump($adminBar->get_node('my-account'));
> }
> }}}
>
> **6.6.0:**
>
> {{{
> $adminBar->get_node('my-account'))
> }}}
>

> {{{
> {#3866 ▼
>   +"id": "my-account"
>   +"title": "Howdy, <span class="display-name">__ACCOUNT__</span><img
> alt=''
> src='https://secure.gravatar.com/avatar/....?s=26&d=mm&r=g' ▶"
>   +"parent": "top-secondary"
>   +"href": "https://core.test/wp/wp-admin/profile.php"
>   +"group": false
>   +"meta": array:3 [▶]
> }
> }}}
>

> {{{
> $adminBar
> }}}
>

> {{{
> WP_Admin_Bar {#3349 ▼
>   -nodes: array:4 [▼
>     "user-actions" => {#3362 ▶}
>     "user-info" => {#3546 ▶}
>     "logout" => {#3545 ▶}
>     "my-account" => {#3893 ▶}
>   ]
>   -bound: false
>   +user: {#3348 ▶}
>   +menu: []
> }
> }}}
>
> **6.6.1:**
>
> {{{
> $adminBar->get_node('my-account'))
> }}}
>
> {{{
> null
> }}}
>
> {{{
> $adminBar
> }}}
>
> {{{
> WP_Admin_Bar {#3352 ▼
>   -nodes: array:3 [▼
>     "user-actions" => {#3365 ▶}
>     "user-info" => {#3549 ▶}
>     "logout" => {#3548 ▶}
>   ]
>   -bound: false
>   +user: {#3351 ▶}
>   +menu: []
> }
> }}}

New description:

 == Scope of this ticket

 Improve docs to add recommendations for customizing / changing existing
 items

 This is necessary as [58748] changeset moved the user menu to a higher
 priority level (of 9991) to achieve:

 >so nodes added with higher priorities will still be shown visually before
 the user and recovery menu items, as they were prior to [58215].

 When hooking into `'admin_bar_menu'` with a priority level less than 9991
 and attempting to get the `'my-account'` node, null is returned. While the
 preferred approach is to hook into `'wp_before_admin_bar_render'`, the
 documentation of the `'admin_bar_menu'` action is misleading.

 This ticket aims to provide clear recommendations to help guide
 developers.

 == Original report that drove this change

 Getting admin bar node "my-account" returns null after updating to 6.6.1

 {{{#!php
 <?php
 add_action('admin_bar_menu', function (WP_Admin_Bar $adminBar):
 WP_Admin_Bar {
   var_dump($adminBar->get_node('my-account'));
 }
 }}}

 **6.6.0:**

 {{{
 $adminBar->get_node('my-account'))
 }}}


 {{{
 {#3866 ▼
   +"id": "my-account"
   +"title": "Howdy, <span class="display-name">__ACCOUNT__</span><img
 alt=''
 src='https://secure.gravatar.com/avatar/....?s=26&d=mm&r=g' ▶"
   +"parent": "top-secondary"
   +"href": "https://core.test/wp/wp-admin/profile.php"
   +"group": false
   +"meta": array:3 [▶]
 }
 }}}


 {{{
 $adminBar
 }}}


 {{{
 WP_Admin_Bar {#3349 ▼
   -nodes: array:4 [▼
     "user-actions" => {#3362 ▶}
     "user-info" => {#3546 ▶}
     "logout" => {#3545 ▶}
     "my-account" => {#3893 ▶}
   ]
   -bound: false
   +user: {#3348 ▶}
   +menu: []
 }
 }}}

 **6.6.1:**

 {{{
 $adminBar->get_node('my-account'))
 }}}

 {{{
 null
 }}}

 {{{
 $adminBar
 }}}

 {{{
 WP_Admin_Bar {#3352 ▼
   -nodes: array:3 [▼
     "user-actions" => {#3365 ▶}
     "user-info" => {#3549 ▶}
     "logout" => {#3548 ▶}
   ]
   -bound: false
   +user: {#3351 ▶}
   +menu: []
 }
 }}}

--

Comment (by hellofromTonya):

 Modifying the Summary of this ticket to reflect the scope of agreed to
 changes.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/61738#comment:37>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform