[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 flixos90):

 @desrosj
 > Was there a specific reason for choosing to pass the `$before` and
 `$after` variables to `wp_get_update_php_annotation()`? I don't hate it,
 but I don't love it.

 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`.

 For `wp_get_update_php_annotation()`, I'd argue consistency here is more
 important than possibly more sanity (especially as the latter is
 arguable). Therefore I think it should also have `$before` and `$after`,
 and `wp_update_php_annotation( $before, $after )` shouldn't do anything
 more than `echo wp_get_update_php_annotation( $before, $after )`, passing
 through the parameters. That is also in line with many other core
 functions which have such two variants.

 @afragen
 > Return type is now documented as `string|null`. My preference is to
 return null.

 I strongly recommend returning an empty string as it's a best practice to
 have as little return types as necessary. Many programming languages even
 enforce this - I know WordPress doesn't respect such practices often, but
 I still advocate doing it where we can.

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