$response var in comments not an array but an object

[davidmosterd]

In the file wp-admin/includes/update.php there is an action do_action( "in_plugin_update_message-{$file}", $plugin_data, $response ); . The comments declares $response as an array but its and object containing the plugin data. The list of plugin data also seems somewhat incomplete. But I'm unsure if all fields I see are always present. The property "tested" seems useful to add at least.

[davidmosterd]

A Git to SVN patch that I hoped that worked :)

[SergeyBiryukov]

Hi there, welcome to WordPress Trac!

Thanks for the ticket, sorry it took so long for someone to get back to you.

Setting the version to 3.8, as the documentation was added in [26540] / #26252.

The in_plugin_update_message-{$file} action itself was added in [11193] / #9553.

A corresponding in_theme_update_message-{$theme_key} action for themes was added in [16141] / #14897.

It looks like the $response parameter here is an object for plugins, but is indeed an array for themes. I think it's worth discussing whether we want to make it consistent for both, i.e. make it an array for plugins too, to match the documented value.

On second thought, since the action was added more than 12 years ago, changing the parameter type now would break any custom code relying on it being an object, so perhaps we should just accept the inconsistency and correct the documentation as suggested in 40006.diff​. A brief ​search in the Plugin Directory shows that the action is used in quite a few plugins.

[audrasjb]

Indeed, the first step is to update the DocBlock to reflect the actual parameter type.

Then it would also be useful to add the missing parameters available in the $response object. But I think it's better to separate those two steps.

[audrasjb]

Upgrade/Install: Docs: Correct the documentation of the $response parameter in the in_plugin_update_message-{$file} action.

[SergeyBiryukov]

In 51733:

Docs: Correct documentation for the in_plugin_update_message-{$file} filter.

The $response parameter is an object, not an array.

This is a minor inconsistency with the corresponding in_theme_update_message-{$theme_key} action for themes, where the $response parameter is an array.

For backward compatibility, it is safer not to change the parameter type at this point, but to make sure the documentation is correct.

Follow-up to [11193], [16141], [26540].

Props davidmosterd, audrasjb, SergeyBiryukov.
See #40006.

[SergeyBiryukov]

Replying to audrasjb:

Then it would also be useful to add the missing parameters available in the $response object.

Keeping the ticket open for this :)

[audrasjb]

Docs: Add missing parameters available in the in_plugin_update_message-{$file} filter. Follow-up to [51733].

[audrasjb]

Just added the missing parameters :)

[costdev]

@type string $requires Required WordPress version.
@type string $tested Higher WordPress version the plugin has been tested with.

For consistency with another docblock in core (see src/wp-admin/includes/plugin.php:33), I suggest:

@type string $requires Specify the minimum required WordPress version.
@type string $tested Specify the latest version of WordPress that the plugin has been tested with.

Trac ticket: https://core.trac.wordpress.org/ticket/40006

[audrasjb]

Thanks @costdev, I added them in the new PR. Self-assigning for commit.

[audrasjb]

In 52212:

Docs: Add missing parameters in in_plugin_update_message-{$file} filter.

Follow-up to [51733].

Props costdev, audrasjb, SergeyBiryukov.
Fixes #40006.

Committed in https://core.trac.wordpress.org/changeset/52212

[SergeyBiryukov]

It looks like [52212] accidentally reverts [51733], will commit a fix shortly.

Replying to costdev:

@type string $requires Required WordPress version.
@type string $tested Higher WordPress version the plugin has been tested with.

For consistency with another docblock in core (see src/wp-admin/includes/plugin.php:33), I suggest:

@type string $requires Specify the minimum required WordPress version.
@type string $tested Specify the latest version of WordPress that the plugin has been tested with.

Thanks! Consistency is great, but that DocBlock is an example of plugin headers, which is why it says "specify". Since we're dealing with a do_action() call here, this is not the place to specify these values, we can only work with whatever values are already passed in the $response object. So I think in this case it would be better to follow the DocBlock for the return result of get_plugin_data(), or the DocBlock for the update_plugins_{$hostname} filter, which documents pretty much the same values.

[SergeyBiryukov]

In 52224:

Docs: Restore [51733], accidentally reverted in [52212].

Document some more $response values in the in_plugin_update_message-{$file} filter:

• banners_rtl
• requires_php

Follow-up to [51733], [52212].

Fixes #40006.