Skip to content

Document globals in bundled themes #5920

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sabernhardt wants to merge 30 commits into
base: trunk
Choose a base branch
from
+154 −28
Open

Document globals in bundled themes #5920

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
45c8adc
2010 functions.php
sabernhardt Jan 21, 2024
b765a7e
2010 header.php
sabernhardt Jan 21, 2024
b0dd7a6
2011 functions.php
sabernhardt Jan 21, 2024
f1e0005
2011 header.php
sabernhardt Jan 21, 2024
df0980b
2011 content-featured.php
sabernhardt Jan 21, 2024
0f278e1
2011 showcase.php
sabernhardt Jan 21, 2024
6d342d3
2012 functions.php
sabernhardt Jan 21, 2024
9be551c
2013 functions.php
sabernhardt Jan 21, 2024
4b26696
2013 back-compat.php
sabernhardt Jan 21, 2024
cbd5ef8
2014 functions.php
sabernhardt Jan 21, 2024
2add9e4
2014 back-compat.php
sabernhardt Jan 21, 2024
20a6e3b
2014 customizer.php
sabernhardt Jan 21, 2024
e2c8a32
2014 widgets.php
sabernhardt Jan 21, 2024
94989f0
2015 functions.php
sabernhardt Jan 21, 2024
9f777c6
2015 back-compat.php
sabernhardt Jan 21, 2024
5c3d4a4
2016 functions.php
sabernhardt Jan 21, 2024
6b74b32
2017 functions.php
sabernhardt Jan 21, 2024
f6892bf
2017 content-front-page-panels.php
sabernhardt Jan 21, 2024
2d877d8
2019 functions.php
sabernhardt Jan 21, 2024
cecad66
2020 functions.php
sabernhardt Jan 21, 2024
80fb633
2021 functions.php
sabernhardt Jan 21, 2024
da9e9f7
2016: move `since` before `$content_width` global
sabernhardt Jan 22, 2024
8b245b5
2021: remove space at end of line
sabernhardt Jan 22, 2024
1c6e7ee
2021: remove space at end of another line
sabernhardt Jan 22, 2024
a9a4206
Use "The WordPress version string" for `$wp_version` description
sabernhardt Mar 21, 2024
b24fe08
Merge branch 'WordPress:trunk' into theme-globals
sabernhardt Jan 17, 2025
44d6dcc
Merge branch 'WordPress:trunk' into theme-globals
sabernhardt Sep 24, 2025
7d74ac6
Merge branch 'WordPress:trunk' into theme-globals
sabernhardt Feb 4, 2026
c7124ba
Move `$page` and `$paged` earlier in T11 `header.php`
sabernhardt Feb 4, 2026
84911f3
Move `$page` and `$paged` earlier in T10 `header.php`
sabernhardt Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/wp-content/themes/twentyeleven/content-featured.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
* @since Twenty Eleven 1.0
*/

/**
* @global string $feature_class Classes for post container of featured posts.
Copy link
Author

@sabernhardt sabernhardt Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

noruzzaman suggested this description in #10864:

Suggested change
* @global string $feature_class Classes for post container of featured posts.
* @global string $feature_class CSS classes for the article element.

*/
Copy link
Author

@sabernhardt sabernhardt Jan 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Twenty Twenty documents $wp_query in the index.php template using a similar short docblock. Is this the best way for templates such as content-featured.php or Twenty Seventeen's content-front-page-panels.php to document their globals?

global $feature_class;
?>
<article id="post-<?php the_ID(); ?>" <?php post_class( $feature_class ); ?>>
Expand Down
6 changes: 6 additions & 0 deletions src/wp-content/themes/twentyeleven/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@
* @uses set_post_thumbnail_size() To set a custom post thumbnail size.
*
* @since Twenty Eleven 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyeleven_setup() {

Expand Down Expand Up @@ -636,6 +638,8 @@ function twentyeleven_widgets_init() {
*
* @since Twenty Eleven 1.0
*
* @global WP_Query $wp_query WordPress Query object.
*
* @param string $html_id The HTML id attribute.
*/
function twentyeleven_content_nav( $html_id ) {
Expand Down Expand Up @@ -753,6 +757,8 @@ function twentyeleven_footer_sidebar_class() {
*
* @since Twenty Eleven 1.0
*
* @global WP_Comment $comment Global comment object.
Copy link
Author

@sabernhardt sabernhardt Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

58715.2.patch documented the $comment global in twentyten_comment(), twentyeleven_comment() and twentytwelve_comment(). This seems odd when $comment is also a parameter, though I do not know of a reason why these functions cannot document it as both global and parameter.

*
* @param WP_Comment $comment The comment object.
* @param array $args An array of comment arguments. @see get_comment_reply_link()
* @param int $depth The depth of the comment.
Expand Down
9 changes: 7 additions & 2 deletions src/wp-content/themes/twentyeleven/header.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,13 @@
* @subpackage Twenty_Eleven
* @since Twenty Eleven 1.0
*/

/**
* @global int $page WordPress paginated post page count.
* @global int $paged WordPress archive pagination page count.
*/
global $page, $paged;

?><!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
Expand All @@ -16,8 +23,6 @@
<title>
<?php
// Print the <title> tag based on what is being viewed.
global $page, $paged;

wp_title( '|', true, 'right' );

// Add the site name.
Expand Down
6 changes: 5 additions & 1 deletion src/wp-content/themes/twentyeleven/showcase.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,11 @@
if ( $recent->have_posts() ) :
$recent->the_post();

// Set $more to 0 in order to only get the first part of the post.
/*
Copy link
Author

@sabernhardt sabernhardt Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

single-line comment style changed to multi-line (should it be docblock or edited another way?)

* Set $more to 0 in order to only get the first part of the post.
Comment on lines +211 to +212
Copy link
Author

@sabernhardt sabernhardt Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/*
* Set $more to 0 in order to only get the first part of the post.
/**
* Sets $more to 0 in order to only get the first part of the post.

#10864 used the docblock format.

*
* @global int $more
Copy link
Member

@huzaifaalmesbah huzaifaalmesbah Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be okay to use it like this?
@global int $more Whether to cut off content at the 'more' tag. instead of using @global int $more

Copy link
Author

@sabernhardt sabernhardt Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure. Other options:

#10864 had

@global int $more Whether to display the full post or just the teaser.

get_the_content() has

@global int   $more      Boolean indicator for whether single post/page is being viewed.

*/
global $more;
$more = 0;

Expand Down
6 changes: 6 additions & 0 deletions src/wp-content/themes/twentyfifteen/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@

/**
* Twenty Fifteen only works in WordPress 4.1 or later.
*
* @global string $wp_version The WordPress version string.
*/
if ( version_compare( $GLOBALS['wp_version'], '4.1-alpha', '<' ) ) {
require get_template_directory() . '/inc/back-compat.php';
Expand All @@ -50,6 +52,8 @@
* as indicating support for post thumbnails.
*
* @since Twenty Fifteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfifteen_setup() {

Expand Down Expand Up @@ -499,6 +503,8 @@ function twentyfifteen_block_editor_styles() {
* @since Twenty Fifteen 1.7
* @deprecated Twenty Fifteen 3.4 Disabled filter because, by default, fonts are self-hosted.
*
* @global string $wp_version The WordPress version string.
*
* @param array $urls URLs to print for resource hints.
* @param string $relation_type The relation type the URLs are printed.
* @return array URLs to print for resource hints.
Expand Down
6 changes: 6 additions & 0 deletions src/wp-content/themes/twentyfifteen/inc/back-compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ function twentyfifteen_switch_theme() {
* Twenty Fifteen on WordPress versions prior to 4.1.
*
* @since Twenty Fifteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfifteen_upgrade_notice() {
printf(
Expand All @@ -48,6 +50,8 @@ function twentyfifteen_upgrade_notice() {
* Prevents the Customizer from being loaded on WordPress versions prior to 4.1.
*
* @since Twenty Fifteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfifteen_customize() {
wp_die(
Expand All @@ -68,6 +72,8 @@ function twentyfifteen_customize() {
* Prevents the Theme Preview from being loaded on WordPress versions prior to 4.1.
*
* @since Twenty Fifteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfifteen_preview() {
if ( isset( $_GET['preview'] ) ) {
Expand Down
14 changes: 14 additions & 0 deletions src/wp-content/themes/twentyfourteen/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@

/**
* Twenty Fourteen only works in WordPress 3.6 or later.
*
* @global string $wp_version The WordPress version string.
*/
if ( version_compare( $GLOBALS['wp_version'], '3.6', '<' ) ) {
require get_template_directory() . '/inc/back-compat.php';
Expand All @@ -54,6 +56,8 @@
* as indicating support post thumbnails.
*
* @since Twenty Fourteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfourteen_setup() {

Expand Down Expand Up @@ -226,6 +230,8 @@ function twentyfourteen_setup() {
* Adjusts content_width value for image attachment template.
*
* @since Twenty Fourteen 1.0
*
* @global int $content_width Content width.
*/
function twentyfourteen_content_width() {
if ( is_attachment() && wp_attachment_is_image() ) {
Expand Down Expand Up @@ -416,6 +422,8 @@ function twentyfourteen_admin_fonts() {
* @since Twenty Fourteen 1.9
* @deprecated Twenty Fourteen 3.6 Disabled filter because, by default, fonts are self-hosted.
*
* @global string $wp_version The WordPress version string.
*
* @param array $urls URLs to print for resource hints.
* @param string $relation_type The relation type the URLs are printed.
* @return array URLs to print for resource hints.
Expand Down Expand Up @@ -523,6 +531,8 @@ function twentyfourteen_the_attached_image() {
* Prints a list of all site contributors who published at least one post.
*
* @since Twenty Fourteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfourteen_list_authors() {
$args = array(
Expand Down Expand Up @@ -595,6 +605,8 @@ function twentyfourteen_list_authors() {
*
* @since Twenty Fourteen 1.0
*
* @global string $pagenow The filename of the current screen.
*
* @param array $classes A list of existing body class values.
* @return array The filtered body class list.
*/
Expand Down Expand Up @@ -743,6 +755,8 @@ function twentyfourteen_register_block_patterns() {
*
* To overwrite in a plugin, define your own Featured_Content class on or
* before the 'setup_theme' hook.
*
* @global string $pagenow The filename of the current screen.
*/
if ( ! class_exists( 'Featured_Content' ) && 'plugins.php' !== $GLOBALS['pagenow'] ) {
require get_template_directory() . '/inc/featured-content.php';
Expand Down
6 changes: 6 additions & 0 deletions src/wp-content/themes/twentyfourteen/inc/back-compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ function twentyfourteen_switch_theme() {
* Twenty Fourteen on WordPress versions prior to 3.6.
*
* @since Twenty Fourteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfourteen_upgrade_notice() {
printf(
Expand All @@ -48,6 +50,8 @@ function twentyfourteen_upgrade_notice() {
* Prevents the Customizer from being loaded on WordPress versions prior to 3.6.
*
* @since Twenty Fourteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfourteen_customize() {
wp_die(
Expand All @@ -68,6 +72,8 @@ function twentyfourteen_customize() {
* Prevents the Theme Preview from being loaded on WordPress versions prior to 3.4.
*
* @since Twenty Fourteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentyfourteen_preview() {
if ( isset( $_GET['preview'] ) ) {
Expand Down
2 changes: 2 additions & 0 deletions src/wp-content/themes/twentyfourteen/inc/customizer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,8 @@ function twentyfourteen_customize_preview_js() {
* Adds contextual help to the Themes and Post edit screens.
*
* @since Twenty Fourteen 1.0
*
* @global string $typenow The post type of the current screen.
*/
function twentyfourteen_contextual_help() {
if ( 'admin_head-edit.php' === current_filter() && 'post' !== $GLOBALS['typenow'] ) {
Expand Down
3 changes: 3 additions & 0 deletions src/wp-content/themes/twentyfourteen/inc/widgets.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,9 @@ public function enqueue_scripts() {
*
* @since Twenty Fourteen 1.0
*
* @global int $content_width Content width.
* @global int $more
Copy link
Author

@sabernhardt sabernhardt Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

59101-twentyfifteen.patch and the Core register_globals() function describe the $more variable as "Only set, if single page or post." However, that optional description does not make sense to me in the context of the Twenty_Fourteen_Ephemera_Widget::widget() method, which sets $GLOBALS['more'] = 0.

Copy link
Member

@huzaifaalmesbah huzaifaalmesbah Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also here

*
* @param array $args An array of standard parameters for widgets in this theme.
* @param array $instance An array of settings for this widget instance.
*/
Expand Down
2 changes: 2 additions & 0 deletions src/wp-content/themes/twentynineteen/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@

/**
* Twenty Nineteen only works in WordPress 4.7 or later.
*
* @global string $wp_version The WordPress version string.
*/
if ( version_compare( $GLOBALS['wp_version'], '4.7', '<' ) ) {
require get_template_directory() . '/inc/back-compat.php';
Expand Down
6 changes: 3 additions & 3 deletions src/wp-content/themes/twentynineteen/inc/back-compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ function twentynineteen_switch_theme() {
*
* @since Twenty Nineteen 1.0.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
Copy link
Author

@sabernhardt sabernhardt Jul 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had originally added new tags to match "WordPress version" in the back-compat files for consistency just within the themes collection. Because other Core files repeatedly describe $wp_version as "The WordPress version string," the themes match that instead now.

*/
function twentynineteen_upgrade_notice() {
printf(
Expand All @@ -51,7 +51,7 @@ function twentynineteen_upgrade_notice() {
*
* @since Twenty Nineteen 1.0.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentynineteen_customize() {
wp_die(
Expand All @@ -73,7 +73,7 @@ function twentynineteen_customize() {
*
* @since Twenty Nineteen 1.0.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentynineteen_preview() {
if ( isset( $_GET['preview'] ) ) {
Expand Down
8 changes: 7 additions & 1 deletion src/wp-content/themes/twentyseventeen/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@

/**
* Twenty Seventeen only works in WordPress 4.7 or later.
*
* @global string $wp_version The WordPress version string.
*/
if ( version_compare( $GLOBALS['wp_version'], '4.7-alpha', '<' ) ) {
require get_template_directory() . '/inc/back-compat.php';
Expand All @@ -23,6 +25,10 @@
* Note that this function is hooked into the after_setup_theme hook, which
* runs before the init hook. The init hook is too late for some features, such
* as indicating support for post thumbnails.
*
* @since Twenty Seventeen 1.0
*
* @global int $content_width Content width.
*/
function twentyseventeen_setup() {

Expand Down Expand Up @@ -248,7 +254,7 @@ function twentyseventeen_setup() {
*
* Priority 0 to make it available to lower priority callbacks.
*
* @global int $content_width
* @global int $content_width Content width.
*/
function twentyseventeen_content_width() {

Expand Down
6 changes: 3 additions & 3 deletions src/wp-content/themes/twentyseventeen/inc/back-compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ function twentyseventeen_switch_theme() {
*
* @since Twenty Seventeen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentyseventeen_upgrade_notice() {
printf(
Expand All @@ -51,7 +51,7 @@ function twentyseventeen_upgrade_notice() {
*
* @since Twenty Seventeen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentyseventeen_customize() {
wp_die(
Expand All @@ -73,7 +73,7 @@ function twentyseventeen_customize() {
*
* @since Twenty Seventeen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentyseventeen_preview() {
if ( isset( $_GET['preview'] ) ) {
Expand Down
3 changes: 3 additions & 0 deletions src/wp-content/themes/twentyseventeen/template-parts/page/content-front-page-panels.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
* @version 1.0
*/

/**
* @global int|string $twentyseventeencounter Front page section counter.
*/
global $twentyseventeencounter;

?>
Expand Down
8 changes: 6 additions & 2 deletions src/wp-content/themes/twentysixteen/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@

/**
* Twenty Sixteen only works in WordPress 4.4 or later.
*
* @global string $wp_version The WordPress version string.
*/
if ( version_compare( $GLOBALS['wp_version'], '4.4-alpha', '<' ) ) {
require get_template_directory() . '/inc/back-compat.php';
Expand All @@ -43,6 +45,8 @@
* Create your own twentysixteen_setup() function to override in a child theme.
*
* @since Twenty Sixteen 1.0
*
* @global string $wp_version The WordPress version string.
*/
function twentysixteen_setup() {
/*
Expand Down Expand Up @@ -241,9 +245,9 @@ function twentysixteen_setup() {
*
* Priority 0 to make it available to lower priority callbacks.
*
* @global int $content_width
*
* @since Twenty Sixteen 1.0
*
* @global int $content_width Content width.
*/
function twentysixteen_content_width() {
/**
Expand Down
6 changes: 3 additions & 3 deletions src/wp-content/themes/twentysixteen/inc/back-compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ function twentysixteen_switch_theme() {
*
* @since Twenty Sixteen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentysixteen_upgrade_notice() {
printf(
Expand All @@ -53,7 +53,7 @@ function twentysixteen_upgrade_notice() {
*
* @since Twenty Sixteen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentysixteen_customize() {
wp_die(
Expand All @@ -75,7 +75,7 @@ function twentysixteen_customize() {
*
* @since Twenty Sixteen 1.0
*
* @global string $wp_version WordPress version.
* @global string $wp_version The WordPress version string.
*/
function twentysixteen_preview() {
if ( isset( $_GET['preview'] ) ) {
Expand Down
Loading
Loading