Make WordPress Core

Changeset 52227


Ignore:
Timestamp:
11/20/2021 02:21:15 AM (5 years ago)
Author:
SergeyBiryukov
Message:

Docs: Update documentation for the $plugin_data parameter of various hooks:

  • Document the structure of the $plugin_data array passed to the plugin_row_meta filter.
  • Document some missing values returned by get_plugin_data():
    • PluginURI
    • AuthorName
  • Link to get_plugin_data() and the plugin_row_meta filter as the canonical sources in other various filters and actions which receive the $plugin_data parameter:
    • network_admin_plugin_action_links
    • network_admin_plugin_action_links_{$plugin_file}
    • plugin_action_links
    • plugin_action_links_{$plugin_file}
    • plugin_auto_update_setting_html
    • manage_plugins_custom_column
    • after_plugin_row
    • after_plugin_row_{$plugin_file}
    • in_plugin_update_message-{$file}
  • Update documentation for the $response parameter of the in_plugin_update_message-{$file} filter:
    • Correct type for the id value. It contains a string like w.org/plugins/[plugin-name], not a numeric ID.
    • Update $icons, $banners, and $banners_rtl values to use typed array notation.

Follow-up to [8367], [8402], [12976], [16758], [26540], [30544], [34818], [51733], [52212], [52224].

See #53399.

Location:
trunk/src/wp-admin/includes
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/class-wp-plugins-list-table.php

    r51795 r52227  
    900900                         * @since 3.1.0
    901901                         *
    902                          * @param string[] $actions     An array of plugin action links. By default this can include 'activate',
    903                          *                              'deactivate', and 'delete'.
     902                         * @param string[] $actions     An array of plugin action links. By default this can include
     903                         *                              'activate', 'deactivate', and 'delete'.
    904904                         * @param string   $plugin_file Path to the plugin file relative to the plugins directory.
    905                          * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`.
    906                          * @param string   $context     The plugin context. By default this can include 'all', 'active', 'inactive',
    907                          *                              'recently_activated', 'upgrade', 'mustuse', 'dropins', and 'search'.
     905                         * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`
     906                         *                              and the {@see 'plugin_row_meta'} filter for the list
     907                         *                              of possible values.
     908                         * @param string   $context     The plugin context. By default this can include 'all',
     909                         *                              'active', 'inactive', 'recently_activated', 'upgrade',
     910                         *                              'mustuse', 'dropins', and 'search'.
    908911                         */
    909912                        $actions = apply_filters( 'network_admin_plugin_action_links', $actions, $plugin_file, $plugin_data, $context );
     
    917920                         * @since 3.1.0
    918921                         *
    919                          * @param string[] $actions     An array of plugin action links. By default this can include 'activate',
    920                          *                              'deactivate', and 'delete'.
     922                         * @param string[] $actions     An array of plugin action links. By default this can include
     923                         *                              'activate', 'deactivate', and 'delete'.
    921924                         * @param string   $plugin_file Path to the plugin file relative to the plugins directory.
    922                          * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`.
    923                          * @param string   $context     The plugin context. By default this can include 'all', 'active', 'inactive',
    924                          *                              'recently_activated', 'upgrade', 'mustuse', 'dropins', and 'search'.
     925                         * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`
     926                         *                              and the {@see 'plugin_row_meta'} filter for the list
     927                         *                              of possible values.
     928                         * @param string   $context     The plugin context. By default this can include 'all',
     929                         *                              'active', 'inactive', 'recently_activated', 'upgrade',
     930                         *                              'mustuse', 'dropins', and 'search'.
    925931                         */
    926932                        $actions = apply_filters( "network_admin_plugin_action_links_{$plugin_file}", $actions, $plugin_file, $plugin_data, $context );
     
    935941                         * @since 4.9.0 The 'Edit' link was removed from the list of action links.
    936942                         *
    937                          * @param string[] $actions     An array of plugin action links. By default this can include 'activate',
    938                          *                              'deactivate', and 'delete'. With Multisite active this can also include
    939                          *                              'network_active' and 'network_only' items.
     943                         * @param string[] $actions     An array of plugin action links. By default this can include
     944                         *                              'activate', 'deactivate', and 'delete'. With Multisite active
     945                         *                              this can also include 'network_active' and 'network_only' items.
    940946                         * @param string   $plugin_file Path to the plugin file relative to the plugins directory.
    941                          * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`.
    942                          * @param string   $context     The plugin context. By default this can include 'all', 'active', 'inactive',
    943                          *                              'recently_activated', 'upgrade', 'mustuse', 'dropins', and 'search'.
     947                         * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`
     948                         *                              and the {@see 'plugin_row_meta'} filter for the list
     949                         *                              of possible values.
     950                         * @param string   $context     The plugin context. By default this can include 'all',
     951                         *                              'active', 'inactive', 'recently_activated', 'upgrade',
     952                         *                              'mustuse', 'dropins', and 'search'.
    944953                         */
    945954                        $actions = apply_filters( 'plugin_action_links', $actions, $plugin_file, $plugin_data, $context );
     
    954963                         * @since 4.9.0 The 'Edit' link was removed from the list of action links.
    955964                         *
    956                          * @param string[] $actions     An array of plugin action links. By default this can include 'activate',
    957                          *                              'deactivate', and 'delete'. With Multisite active this can also include
    958                          *                              'network_active' and 'network_only' items.
     965                         * @param string[] $actions     An array of plugin action links. By default this can include
     966                         *                              'activate', 'deactivate', and 'delete'. With Multisite active
     967                         *                              this can also include 'network_active' and 'network_only' items.
    959968                         * @param string   $plugin_file Path to the plugin file relative to the plugins directory.
    960                          * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`.
    961                          * @param string   $context     The plugin context. By default this can include 'all', 'active', 'inactive',
    962                          *                              'recently_activated', 'upgrade', 'mustuse', 'dropins', and 'search'.
     969                         * @param array    $plugin_data An array of plugin data. See `get_plugin_data()`
     970                         *                              and the {@see 'plugin_row_meta'} filter for the list
     971                         *                              of possible values.
     972                         * @param string   $context     The plugin context. By default this can include 'all',
     973                         *                              'active', 'inactive', 'recently_activated', 'upgrade',
     974                         *                              'mustuse', 'dropins', and 'search'.
    963975                         */
    964976                        $actions = apply_filters( "plugin_action_links_{$plugin_file}", $actions, $plugin_file, $plugin_data, $context );
     
    10861098                                         *                              the version, author, author URI, and plugin URI.
    10871099                                         * @param string   $plugin_file Path to the plugin file relative to the plugins directory.
    1088                                          * @param array    $plugin_data An array of plugin data.
     1100                                         * @param array    $plugin_data {
     1101                                         *     An array of plugin data.
     1102                                         *
     1103                                         *     @type string   $id               Plugin ID, e.g. `w.org/plugins/[plugin-name]`.
     1104                                         *     @type string   $slug             Plugin slug.
     1105                                         *     @type string   $plugin           Plugin basename.
     1106                                         *     @type string   $new_version      New plugin version.
     1107                                         *     @type string   $url              Plugin URL.
     1108                                         *     @type string   $package          Plugin update package URL.
     1109                                         *     @type string[] $icons            An array of plugin icon URLs.
     1110                                         *     @type string[] $banners          An array of plugin banner URLs.
     1111                                         *     @type string[] $banners_rtl      An array of plugin RTL banner URLs.
     1112                                         *     @type string   $requires         The version of WordPress which the plugin requires.
     1113                                         *     @type string   $tested           The version of WordPress the plugin is tested against.
     1114                                         *     @type string   $requires_php     The version of PHP which the plugin requires.
     1115                                         *     @type string   $upgrade_notice   The upgrade notice for the new plugin version.
     1116                                         *     @type bool     $update-supported Whether the plugin supports updates.
     1117                                         *     @type string   $Name             The human-readable name of the plugin.
     1118                                         *     @type string   $PluginURI        Plugin URI.
     1119                                         *     @type string   $Version          Plugin version.
     1120                                         *     @type string   $Description      Plugin description.
     1121                                         *     @type string   $Author           Plugin author.
     1122                                         *     @type string   $AuthorURI        Plugin author URI.
     1123                                         *     @type string   $TextDomain       Plugin textdomain.
     1124                                         *     @type string   $DomainPath       Relative path to the plugin's .mo file(s).
     1125                                         *     @type bool     $Network          Whether the plugin can only be activated network-wide.
     1126                                         *     @type string   $RequiresWP       The version of WordPress which the plugin requires.
     1127                                         *     @type string   $RequiresPHP      The version of PHP which the plugin requires.
     1128                                         *     @type string   $UpdateURI        ID of the plugin for update purposes, should be a URI.
     1129                                         *     @type string   $Title            The human-readable title of the plugin.
     1130                                         *     @type string   $AuthorName       Plugin author's name.
     1131                                         *     @type bool     $update           Whether there's an available update. Default null.
     1132                                         * }
    10891133                                         * @param string   $status      Status filter currently applied to the plugin list. Possible
    10901134                                         *                              values are: 'all', 'active', 'inactive', 'recently_activated',
     
    11821226                                         * @since 5.5.0
    11831227                                         *
    1184                                          * @param string $html        The HTML of the plugin's auto-update column content, including
    1185                                          *                            toggle auto-update action links and time to next update.
     1228                                         * @param string $html        The HTML of the plugin's auto-update column content,
     1229                                         *                            including toggle auto-update action links and
     1230                                         *                            time to next update.
    11861231                                         * @param string $plugin_file Path to the plugin file relative to the plugins directory.
    1187                                          * @param array  $plugin_data An array of plugin data.
     1232                                         * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`
     1233                                         *                            and the {@see 'plugin_row_meta'} filter for the list
     1234                                         *                            of possible values.
    11881235                                         */
    11891236                                        echo apply_filters( 'plugin_auto_update_setting_html', $html, $plugin_file, $plugin_data );
     
    12051252                                         * @param string $column_name Name of the column.
    12061253                                         * @param string $plugin_file Path to the plugin file relative to the plugins directory.
    1207                                          * @param array  $plugin_data An array of plugin data.
     1254                                         * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`
     1255                                         *                            and the {@see 'plugin_row_meta'} filter for the list
     1256                                         *                            of possible values.
    12081257                                         */
    12091258                                        do_action( 'manage_plugins_custom_column', $column_name, $plugin_file, $plugin_data );
     
    12751324                 *
    12761325                 * @since 2.3.0
    1277                  * @since 5.5.0 Added 'auto-update-enabled' and 'auto-update-disabled' to possible values for `$status`.
     1326                 * @since 5.5.0 Added 'auto-update-enabled' and 'auto-update-disabled'
     1327                 *              to possible values for `$status`.
    12781328                 *
    12791329                 * @param string $plugin_file Path to the plugin file relative to the plugins directory.
    1280                  * @param array  $plugin_data An array of plugin data.
    1281                  * @param string $status      Status filter currently applied to the plugin list. Possible
    1282                  *                            values are: 'all', 'active', 'inactive', 'recently_activated',
    1283                  *                            'upgrade', 'mustuse', 'dropins', 'search', 'paused',
    1284                  *                            'auto-update-enabled', 'auto-update-disabled'.
     1330                 * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`
     1331                 *                            and the {@see 'plugin_row_meta'} filter for the list
     1332                 *                            of possible values.
     1333                 * @param string $status      Status filter currently applied to the plugin list.
     1334                 *                            Possible values are: 'all', 'active', 'inactive',
     1335                 *                            'recently_activated', 'upgrade', 'mustuse', 'dropins',
     1336                 *                            'search', 'paused', 'auto-update-enabled', 'auto-update-disabled'.
    12851337                 */
    12861338                do_action( 'after_plugin_row', $plugin_file, $plugin_data, $status );
     
    12931345                 *
    12941346                 * @since 2.7.0
    1295                  * @since 5.5.0 Added 'auto-update-enabled' and 'auto-update-disabled' to possible values for `$status`.
     1347                 * @since 5.5.0 Added 'auto-update-enabled' and 'auto-update-disabled'
     1348                 *              to possible values for `$status`.
    12961349                 *
    12971350                 * @param string $plugin_file Path to the plugin file relative to the plugins directory.
    1298                  * @param array  $plugin_data An array of plugin data.
    1299                  * @param string $status      Status filter currently applied to the plugin list. Possible
    1300                  *                            values are: 'all', 'active', 'inactive', 'recently_activated',
    1301                  *                            'upgrade', 'mustuse', 'dropins', 'search', 'paused',
    1302                  *                            'auto-update-enabled', 'auto-update-disabled'.
     1351                 * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`
     1352                 *                            and the {@see 'plugin_row_meta'} filter for the list
     1353                 *                            of possible values.
     1354                 * @param string $status      Status filter currently applied to the plugin list.
     1355                 *                            Possible values are: 'all', 'active', 'inactive',
     1356                 *                            'recently_activated', 'upgrade', 'mustuse', 'dropins',
     1357                 *                            'search', 'paused', 'auto-update-enabled', 'auto-update-disabled'.
    13031358                 */
    13041359                do_action( "after_plugin_row_{$plugin_file}", $plugin_file, $plugin_data, $status );
  • trunk/src/wp-admin/includes/plugin.php

    r52035 r52227  
    5555 *
    5656 *     @type string $Name        Name of the plugin. Should be unique.
    57  *     @type string $Title       Title of the plugin and link to the plugin's site (if set).
     57 *     @type string $PluginURI   Plugin URI.
     58 *     @type string $Version     Plugin version.
    5859 *     @type string $Description Plugin description.
    59  *     @type string $Author      Author's name.
    60  *     @type string $AuthorURI   Author's website address (if set).
    61  *     @type string $Version     Plugin version.
     60 *     @type string $Author      Plugin author's name.
     61 *     @type string $AuthorURI   Plugin author's website address (if set).
    6262 *     @type string $TextDomain  Plugin textdomain.
    63  *     @type string $DomainPath  Plugins relative directory path to .mo files.
     63 *     @type string $DomainPath  Plugin's relative directory path to .mo files.
    6464 *     @type bool   $Network     Whether the plugin can only be activated network-wide.
    6565 *     @type string $RequiresWP  Minimum required version of WordPress.
    6666 *     @type string $RequiresPHP Minimum required version of PHP.
    6767 *     @type string $UpdateURI   ID of the plugin for update purposes, should be a URI.
     68 *     @type string $Title       Title of the plugin and link to the plugin's site (if set).
     69 *     @type string $AuthorName  Plugin author's name.
    6870 * }
    6971 */
     
    130132 *                            Default true.
    131133 * @param bool   $translate   Optional. If the returned data should be translated. Default true.
    132  * @return array {
    133  *     Plugin data. Values will be empty if not supplied by the plugin.
    134  *
    135  *     @type string $Name        Name of the plugin. Should be unique.
    136  *     @type string $Title       Title of the plugin and link to the plugin's site (if set).
    137  *     @type string $Description Plugin description.
    138  *     @type string $Author      Author's name.
    139  *     @type string $AuthorURI   Author's website address (if set).
    140  *     @type string $Version     Plugin version.
    141  *     @type string $TextDomain  Plugin textdomain.
    142  *     @type string $DomainPath  Plugins relative directory path to .mo files.
    143  *     @type bool   $Network     Whether the plugin can only be activated network-wide.
    144  * }
     134 * @return array Plugin data. Values will be empty if not supplied by the plugin.
     135 *               See get_plugin_data() for the list of possible values.
    145136 */
    146137function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup = true, $translate = true ) {
  • trunk/src/wp-admin/includes/update.php

    r52224 r52227  
    559559                 * @since 2.8.0
    560560                 *
    561                  * @param array  $plugin_data {
    562                  *     An array of plugin metadata.
    563                  *
    564                  *     @type string $name        The human-readable name of the plugin.
    565                  *     @type string $plugin_uri  Plugin URI.
    566                  *     @type string $version     Plugin version.
    567                  *     @type string $description Plugin description.
    568                  *     @type string $author      Plugin author.
    569                  *     @type string $author_uri  Plugin author URI.
    570                  *     @type string $text_domain Plugin text domain.
    571                  *     @type string $domain_path Relative path to the plugin's .mo file(s).
    572                  *     @type bool   $network     Whether the plugin can only be activated network wide.
    573                  *     @type string $title       The human-readable title of the plugin.
    574                  *     @type string $author_name Plugin author's name.
    575                  *     @type bool   $update      Whether there's an available update. Default null.
    576                  * }
     561                 * @param array  $plugin_data An array of plugin metadata. See get_plugin_data()
     562                 *                            and the {@see 'plugin_row_meta'} filter for the list
     563                 *                            of possible values.
    577564                 * @param object $response {
    578565                 *     An object of metadata about the available plugin update.
    579566                 *
    580                  *     @type int    $id           Plugin ID.
    581                  *     @type string $slug         Plugin slug.
    582                  *     @type string $plugin       Plugin basename.
    583                  *     @type string $new_version  New plugin version.
    584                  *     @type string $url          Plugin URL.
    585                  *     @type string $package      Plugin update package URL.
    586                  *     @type array $icons        An array of plugin icon URLs.
    587                  *     @type array $banners      An array of plugin banner URLs.
    588                  *     @type array $banners_rtl  An array of plugin RTL banner URLs.
    589                  *     @type string $requires     The version of WordPress which the plugin requires.
    590                  *     @type string $tested       The version of WordPress the plugin is tested against.
    591                  *     @type string $requires_php The version of PHP which the plugin requires.
     567                 *     @type string   $id           Plugin ID, e.g. `w.org/plugins/[plugin-name]`.
     568                 *     @type string   $slug         Plugin slug.
     569                 *     @type string   $plugin       Plugin basename.
     570                 *     @type string   $new_version  New plugin version.
     571                 *     @type string   $url          Plugin URL.
     572                 *     @type string   $package      Plugin update package URL.
     573                 *     @type string[] $icons        An array of plugin icon URLs.
     574                 *     @type string[] $banners      An array of plugin banner URLs.
     575                 *     @type string[] $banners_rtl  An array of plugin RTL banner URLs.
     576                 *     @type string   $requires     The version of WordPress which the plugin requires.
     577                 *     @type string   $tested       The version of WordPress the plugin is tested against.
     578                 *     @type string   $requires_php The version of PHP which the plugin requires.
    592579                 * }
    593580                 */
Note: See TracChangeset for help on using the changeset viewer.