[wp-trac] [WordPress Trac] #46044: Add `wp_get_update_php_annotation()` to return the Update PHP annotation

[WordPress Trac]

#46044: Add `wp_get_update_php_annotation()` to return the Update PHP annotation
-----------------------------------------------+---------------------
 Reporter:  afragen                            |       Owner:  (none)
     Type:  defect (bug)                       |      Status:  new
 Priority:  normal                             |   Milestone:  5.2
Component:  Plugins                            |     Version:  5.1
 Severity:  normal                             |  Resolution:
 Keywords:  has-patch servehappy dev-feedback  |     Focuses:
-----------------------------------------------+---------------------

Comment (by desrosj):

 I misread @flixos90's last message. I should have double checked before
 responding on mobile earlier.

 > Frankly, we coded ourselves into a corner here a little bit, as
 wp_update_php_annotation() (already released) outputs markup. Maybe it
 would have been better if it hadn't, but that is now a point of no return.
 For that function we need to stay backward-compatible in printing the p
 tags by default, but now it became obvious that needs to be adjustable,
 therefore that function needs $before and $after.

 The markup is currently output by the `wp_update_php_annotation()`, but
 not accepted as parameters. What I am suggesting is:
 - `wp_update_php_annotation()` accepts `$before` and `$after` parameters
 and continues to output markup (`<p>` by default).
 - `wp_get_update_php_annotation()` only returns the text annotation, with
 a default of an empty string.

 [attachment:"46044.7.diff"] has this.

 I looked at other functions in core that have this pattern
 (`$before`/`$after`), there was not a lot of consistency.
 - `the_title()` accepts before and after markup and does not pass them to
 `get_the_title()`.
 - `get_the_term_list()` accepts before and after markup and does not pass
 them to `get_the_terms()`.
 - `comment_author_url_link()` accepts before and after and passes them to
 `get_comment_author_url_link()`.
 - `the_archive_title()` accepts before and after, but does not pass them
 to `get_the_archive_title()`.
 - `the_archive_description()` accepts before and after, but does not pass
 them to `get_the_archive_description()`.
 - `the_date()` accepts before and after, but does not pass them to
 `get_the_date()`.
 - `the_modified_date()` accepts before and after, but does not pass them
 to `get_the_modified_date()`.

 I think there is more of a pattern for not passing the markup down to the
 `get_*` functions. I don't feel particularly strong either way, but just
 wanted to detail my thought process of why I proposed that. What I
 proposed feels more natural to me.

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