WordPress.org
Get WordPress

Make WordPress Core

Changeset 52227


Ignore:
Timestamp:
11/20/2021 02:21:15 AM (3 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.