[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> theme.php (summary)

Theme, template, and stylesheet functions.

File Size: 4203 lines (128 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 1 file
 wp-includes/class-wp-customize-manager.php

Defines 87 functions

  wp_get_themes()
  wp_get_theme()
  wp_clean_themes_cache()
  is_child_theme()
  get_stylesheet()
  get_stylesheet_directory()
  get_stylesheet_directory_uri()
  get_stylesheet_uri()
  get_locale_stylesheet_uri()
  get_template()
  get_template_directory()
  get_template_directory_uri()
  get_theme_roots()
  register_theme_directory()
  search_theme_directories()
  get_theme_root()
  get_theme_root_uri()
  get_raw_theme_root()
  locale_stylesheet()
  switch_theme()
  validate_current_theme()
  validate_theme_requirements()
  get_theme_mods()
  get_theme_mod()
  set_theme_mod()
  remove_theme_mod()
  remove_theme_mods()
  get_header_textcolor()
  header_textcolor()
  display_header_text()
  has_header_image()
  get_header_image()
  get_header_image_tag()
  the_header_image_tag()
  _get_random_header_data()
  get_random_header_image()
  is_random_header_image()
  header_image()
  get_uploaded_header_images()
  get_custom_header()
  register_default_headers()
  unregister_default_headers()
  has_header_video()
  get_header_video_url()
  the_header_video_url()
  get_header_video_settings()
  has_custom_header()
  is_header_video_active()
  get_custom_header_markup()
  the_custom_header_markup()
  get_background_image()
  background_image()
  get_background_color()
  background_color()
  _custom_background_cb()
  wp_custom_css_cb()
  wp_get_custom_css_post()
  wp_get_custom_css()
  wp_update_custom_css_post()
  add_editor_style()
  remove_editor_styles()
  get_editor_stylesheets()
  get_theme_starter_content()
  add_theme_support()
  _custom_header_background_just_in_time()
  _custom_logo_header_styles()
  get_theme_support()
  remove_theme_support()
  _remove_theme_support()
  current_theme_supports()
  require_if_theme_supports()
  register_theme_feature()
  get_registered_theme_features()
  get_registered_theme_feature()
  _delete_attachment_theme_mod()
  check_theme_switched()
  _wp_customize_include()
  _wp_customize_publish_changeset()
  _wp_customize_changeset_filter_insert_post_data()
  _wp_customize_loader_settings()
  wp_customize_url()
  wp_customize_support_script()
  is_customize_preview()
  _wp_keep_alive_customize_changeset_dependent_auto_drafts()
  create_initial_theme_features()
  wp_is_block_theme()
  _add_default_theme_supports()

Functions
Functions that are not part of a class:

wp_get_themes( $args = array()   X-Ref
Returns an array of WP_Theme objects based on the arguments.

Despite advances over get_themes(), this function is quite expensive, and grows
linearly with additional themes. Stick to wp_get_theme() if possible.

param: array $args {
return: WP_Theme[] Array of WP_Theme objects.
since: 3.4.0

wp_get_theme( $stylesheet = '', $theme_root = '' )   X-Ref
Gets a WP_Theme object for a theme.

param: string $stylesheet Optional. Directory name for the theme. Defaults to active theme.
param: string $theme_root Optional. Absolute path of the theme root to look in.
return: WP_Theme Theme object. Be sure to check the object's exists() method
since: 3.4.0

wp_clean_themes_cache( $clear_update_cache = true )   X-Ref
Clears the cache held by get_theme_roots() and WP_Theme.

param: bool $clear_update_cache Whether to clear the theme updates cache.
since: 3.5.0

is_child_theme()   X-Ref
Whether a child theme is in use.

return: bool True if a child theme is in use, false otherwise.
since: 3.0.0

get_stylesheet()   X-Ref
Retrieves name of the current stylesheet.

The theme name that is currently set as the front end theme.

For all intents and purposes, the template name and the stylesheet name
are going to be the same for most cases.

return: string Stylesheet name.
since: 1.5.0

get_stylesheet_directory()   X-Ref
Retrieves stylesheet directory path for the active theme.

return: string Path to active theme's stylesheet directory.
since: 1.5.0

get_stylesheet_directory_uri()   X-Ref
Retrieves stylesheet directory URI for the active theme.

return: string URI to active theme's stylesheet directory.
since: 1.5.0

get_stylesheet_uri()   X-Ref
Retrieves stylesheet URI for the active theme.

The stylesheet file name is 'style.css' which is appended to the stylesheet directory URI path.
See get_stylesheet_directory_uri().

return: string URI to active theme's stylesheet.
since: 1.5.0

get_locale_stylesheet_uri()   X-Ref
Retrieves the localized stylesheet URI.

The stylesheet directory for the localized stylesheet files are located, by
default, in the base theme directory. The name of the locale file will be the
locale followed by '.css'. If that does not exist, then the text direction
stylesheet will be checked for existence, for example 'ltr.css'.

The theme may change the location of the stylesheet directory by either using
the {@see 'stylesheet_directory_uri'} or {@see 'locale_stylesheet_uri'} filters.

If you want to change the location of the stylesheet files for the entire
WordPress workflow, then change the former. If you just have the locale in a
separate folder, then change the latter.

return: string URI to active theme's localized stylesheet.
since: 2.1.0

get_template()   X-Ref
Retrieves name of the active theme.

return: string Template name.
since: 1.5.0

get_template_directory()   X-Ref
Retrieves template directory path for the active theme.

return: string Path to active theme's template directory.
since: 1.5.0

get_template_directory_uri()   X-Ref
Retrieves template directory URI for the active theme.

return: string URI to active theme's template directory.
since: 1.5.0

get_theme_roots()   X-Ref
Retrieves theme roots.

return: array|string An array of theme roots keyed by template/stylesheet
since: 2.9.0

register_theme_directory( $directory )   X-Ref
Registers a directory that contains themes.

param: string $directory Either the full filesystem path to a theme folder
return: bool True if successfully registered a directory that contains themes,
since: 2.9.0

search_theme_directories( $force = false )   X-Ref
Searches all registered theme directories for complete and valid themes.

param: bool $force Optional. Whether to force a new directory scan. Default false.
return: array|false Valid themes found on success, false on failure.
since: 2.9.0

get_theme_root( $stylesheet_or_template = '' )   X-Ref
No description

get_theme_root_uri( $stylesheet_or_template = '', $theme_root = '' )   X-Ref
Retrieves URI for themes directory.

Does not have trailing slash.

param: string $stylesheet_or_template Optional. The stylesheet or template name of the theme.
param: string $theme_root             Optional. The theme root for which calculations will be based,
return: string Themes directory URI.
since: 1.5.0

get_raw_theme_root( $stylesheet_or_template, $skip_cache = false )   X-Ref
Gets the raw theme root relative to the content directory with no filters applied.

param: string $stylesheet_or_template The stylesheet or template name of the theme.
param: bool   $skip_cache             Optional. Whether to skip the cache.
return: string Theme root.
since: 3.1.0

locale_stylesheet()   X-Ref
Displays localized stylesheet link element.

since: 2.1.0

switch_theme( $stylesheet )   X-Ref
Switches the theme.

Accepts one argument: $stylesheet of the theme. It also accepts an additional function signature
of two arguments: $template then $stylesheet. This is for backward compatibility.

param: string $stylesheet Stylesheet name.
since: 2.5.0

validate_current_theme()   X-Ref
Checks that the active theme has the required files.

Standalone themes need to have a `templates/index.html` or `index.php` template file.
Child themes need to have a `Template` header in the `style.css` stylesheet.

Does not initially check the default theme, which is the fallback and should always exist.
But if it doesn't exist, it'll fall back to the latest core default theme that does exist.
Will switch theme to the fallback theme if active theme does not validate.

You can use the {@see 'validate_current_theme'} filter to return false to disable
this functionality.

return: bool
since: 1.5.0
since: 6.0.0 Removed the requirement for block themes to have an `index.php` template.

validate_theme_requirements( $stylesheet )   X-Ref
Validates the theme requirements for WordPress version and PHP version.

Uses the information from `Requires at least` and `Requires PHP` headers
defined in the theme's `style.css` file.

param: string $stylesheet Directory name for the theme.
return: true|WP_Error True if requirements are met, WP_Error on failure.
since: 5.5.0
since: 5.8.0 Removed support for using `readme.txt` as a fallback.

get_theme_mods()   X-Ref
Retrieves all theme modifications.

return: array Theme modifications.
since: 3.1.0
since: 5.9.0 The return value is always an array.

get_theme_mod( $name, $default = false )   X-Ref
Retrieves theme modification value for the active theme.

If the modification name does not exist and `$default` is a string, then the
default will be passed through the {@link https://www.php.net/sprintf sprintf()}
PHP function with the template directory URI as the first value and the
stylesheet directory URI as the second value.

param: string $name    Theme modification name.
param: mixed  $default Optional. Theme modification default value. Default false.
return: mixed Theme modification value.
since: 2.1.0

set_theme_mod( $name, $value )   X-Ref
Updates theme modification value for the active theme.

param: string $name  Theme modification name.
param: mixed  $value Theme modification value.
return: bool True if the value was updated, false otherwise.
since: 2.1.0
since: 5.6.0 A return value was added.

remove_theme_mod( $name )   X-Ref
Removes theme modification name from active theme list.

If removing the name also removes all elements, then the entire option
will be removed.

param: string $name Theme modification name.
since: 2.1.0

remove_theme_mods()   X-Ref
Removes theme modifications option for the active theme.

since: 2.1.0

get_header_textcolor()   X-Ref
Retrieves the custom header text color in 3- or 6-digit hexadecimal form.

return: string Header text color in 3- or 6-digit hexadecimal form (minus the hash symbol).
since: 2.1.0

header_textcolor()   X-Ref
Displays the custom header text color in 3- or 6-digit hexadecimal form (minus the hash symbol).

since: 2.1.0

display_header_text()   X-Ref
Whether to display the header text.

return: bool
since: 3.4.0

has_header_image()   X-Ref
Checks whether a header image is set or not.

return: bool Whether a header image is set or not.
since: 4.2.0

get_header_image()   X-Ref
Retrieves header image for custom header.

return: string|false
since: 2.1.0

get_header_image_tag( $attr = array()   X-Ref
Creates image tag markup for a custom header image.

param: array $attr Optional. Additional attributes for the image tag. Can be used
return: string HTML image element markup or empty string on failure.
since: 4.4.0

the_header_image_tag( $attr = array()   X-Ref
Displays the image markup for a custom header image.

param: array $attr Optional. Attributes for the image markup. Default empty.
since: 4.4.0

_get_random_header_data()   X-Ref
Gets random header image data from registered images in theme.

return: object
since: 3.4.0

get_random_header_image()   X-Ref
Gets random header image URL from registered images in theme.

return: string Path to header image.
since: 3.2.0

is_random_header_image( $type = 'any' )   X-Ref
Checks if random header image is in use.

Always true if user expressly chooses the option in Appearance > Header.
Also true if theme has multiple header images registered, no specific header image
is chosen, and theme turns on random headers with add_theme_support().

param: string $type The random pool to use. Possible values include 'any',
return: bool
since: 3.2.0

header_image()   X-Ref
Displays header image URL.

since: 2.1.0

get_uploaded_header_images()   X-Ref
Gets the header images uploaded for the active theme.

return: array
since: 3.2.0

get_custom_header()   X-Ref
Gets the header image data.

return: object
since: 3.4.0

register_default_headers( $headers )   X-Ref
Registers a selection of default headers to be displayed by the custom header admin UI.

param: array $headers Array of headers keyed by a string ID. The IDs point to arrays
since: 3.0.0

unregister_default_headers( $header )   X-Ref
Unregisters default headers.

This function must be called after register_default_headers() has already added the
header you want to remove.

param: string|array $header The header string id (key of array) to remove, or an array thereof.
return: bool|void A single header returns true on success, false on failure.
since: 3.0.0

has_header_video()   X-Ref
Checks whether a header video is set or not.

return: bool Whether a header video is set or not.
since: 4.7.0

get_header_video_url()   X-Ref
Retrieves header video URL for custom header.

Uses a local video if present, or falls back to an external video.

return: string|false Header video URL or false if there is no video.
since: 4.7.0

the_header_video_url()   X-Ref
Displays header video URL.

since: 4.7.0

get_header_video_settings()   X-Ref
Retrieves header video settings.

return: array
since: 4.7.0

has_custom_header()   X-Ref
Checks whether a custom header is set or not.

return: bool True if a custom header is set. False if not.
since: 4.7.0

is_header_video_active()   X-Ref
Checks whether the custom header video is eligible to show on the current page.

return: bool True if the custom header video should be shown. False if not.
since: 4.7.0

get_custom_header_markup()   X-Ref
Retrieves the markup for a custom header.

The container div will always be returned in the Customizer preview.

return: string The markup for a custom header on success.
since: 4.7.0

the_custom_header_markup()   X-Ref
Prints the markup for a custom header.

A container div will always be printed in the Customizer preview.

since: 4.7.0

get_background_image()   X-Ref
Retrieves background image for custom background.

return: string
since: 3.0.0

background_image()   X-Ref
Displays background image path.

since: 3.0.0

get_background_color()   X-Ref
Retrieves value for custom background color.

return: string
since: 3.0.0

background_color()   X-Ref
Displays background color value.

since: 3.0.0

_custom_background_cb()   X-Ref
Default custom background callback.

since: 3.0.0

wp_custom_css_cb()   X-Ref
Renders the Custom CSS style element.

since: 4.7.0

wp_get_custom_css_post( $stylesheet = '' )   X-Ref
Fetches the `custom_css` post for a given theme.

param: string $stylesheet Optional. A theme object stylesheet name. Defaults to the active theme.
return: WP_Post|null The custom_css post or null if none exists.
since: 4.7.0

wp_get_custom_css( $stylesheet = '' )   X-Ref
Fetches the saved Custom CSS content for rendering.

param: string $stylesheet Optional. A theme object stylesheet name. Defaults to the active theme.
return: string The Custom CSS Post content.
since: 4.7.0

wp_update_custom_css_post( $css, $args = array()   X-Ref
Updates the `custom_css` post for a given theme.

Inserts a `custom_css` post when one doesn't yet exist.

param: string $css CSS, stored in `post_content`.
param: array  $args {
return: WP_Post|WP_Error Post on success, error on failure.
since: 4.7.0

add_editor_style( $stylesheet = 'editor-style.css' )   X-Ref
Adds callback for custom TinyMCE editor stylesheets.

The parameter $stylesheet is the name of the stylesheet, relative to
the theme root. It also accepts an array of stylesheets.
It is optional and defaults to 'editor-style.css'.

This function automatically adds another stylesheet with -rtl prefix, e.g. editor-style-rtl.css.
If that file doesn't exist, it is removed before adding the stylesheet(s) to TinyMCE.
If an array of stylesheets is passed to add_editor_style(),
RTL is only added for the first stylesheet.

Since version 3.4 the TinyMCE body has .rtl CSS class.
It is a better option to use that class and add any RTL styles to the main stylesheet.

param: array|string $stylesheet Optional. Stylesheet name or array thereof, relative to theme root.
since: 3.0.0

remove_editor_styles()   X-Ref
Removes all visual editor stylesheets.

return: bool True on success, false if there were no stylesheets to remove.
since: 3.1.0

get_editor_stylesheets()   X-Ref
Retrieves any registered editor stylesheet URLs.

return: string[] If registered, a list of editor stylesheet URLs.
since: 4.0.0

get_theme_starter_content()   X-Ref
Expands a theme's starter content configuration using core-provided data.

return: array Array of starter content.
since: 4.7.0

add_theme_support( $feature, ...$args )   X-Ref
Registers theme support for a given feature.

Must be called in the theme's functions.php file to work.
If attached to a hook, it must be {@see 'after_setup_theme'}.
The {@see 'init'} hook may be too late for some features.

Example usage:

add_theme_support( 'title-tag' );
add_theme_support( 'custom-logo', array(
'height' => 480,
'width'  => 720,
) );

param: string $feature The feature being added. Likely core values include:
param: mixed  ...$args Optional extra arguments to pass along with certain features.
return: void|false Void on success, false on failure.
since: 2.9.0
since: 3.4.0 The `custom-header-uploads` feature was deprecated.
since: 3.6.0 The `html5` feature was added.
since: 3.9.0 The `html5` feature now also accepts 'gallery' and 'caption'.
since: 4.1.0 The `title-tag` feature was added.
since: 4.5.0 The `customize-selective-refresh-widgets` feature was added.
since: 4.7.0 The `starter-content` feature was added.
since: 5.0.0 The `responsive-embeds`, `align-wide`, `dark-editor-style`, `disable-custom-colors`,
since: 5.3.0 The `html5` feature now also accepts 'script' and 'style'.
since: 5.3.0 Formalized the existing and already documented `...$args` parameter
since: 5.5.0 The `core-block-patterns` feature was added and is enabled by default.
since: 5.5.0 The `custom-logo` feature now also accepts 'unlink-homepage-logo'.
since: 5.6.0 The `post-formats` feature warns if no array is passed.
since: 5.8.0 The `widgets-block-editor` feature enables the Widgets block editor.

_custom_header_background_just_in_time()   X-Ref
Registers the internal custom header and background routines.

since: 3.4.0

_custom_logo_header_styles()   X-Ref
Adds CSS to hide header text for custom logo, based on Customizer setting.

since: 4.5.0

get_theme_support( $feature, ...$args )   X-Ref
Gets the theme support arguments passed when registering that support.

Example usage:

get_theme_support( 'custom-logo' );
get_theme_support( 'custom-header', 'width' );

param: string $feature The feature to check. See add_theme_support() for the list
param: mixed  ...$args Optional extra arguments to be checked against certain features.
return: mixed The array of extra arguments or the value for the registered feature.
since: 3.1.0
since: 5.3.0 Formalized the existing and already documented `...$args` parameter

remove_theme_support( $feature )   X-Ref
Allows a theme to de-register its support of a certain feature

Should be called in the theme's functions.php file. Generally would
be used for child themes to override support from the parent theme.

param: string $feature The feature being removed. See add_theme_support() for the list
return: bool|void Whether feature was removed.
since: 3.0.0

_remove_theme_support( $feature )   X-Ref
Do not use. Removes theme support internally without knowledge of those not used
by themes directly.

param: string $feature The feature being removed. See add_theme_support() for the list
return: bool True if support was removed, false if the feature was not registered.
since: 3.1.0

current_theme_supports( $feature, ...$args )   X-Ref
Checks a theme's support for a given feature.

Example usage:

current_theme_supports( 'custom-logo' );
current_theme_supports( 'html5', 'comment-form' );

param: string $feature The feature being checked. See add_theme_support() for the list
param: mixed  ...$args Optional extra arguments to be checked against certain features.
return: bool True if the active theme supports the feature, false otherwise.
since: 2.9.0
since: 5.3.0 Formalized the existing and already documented `...$args` parameter

require_if_theme_supports( $feature, $include )   X-Ref
Checks a theme's support for a given feature before loading the functions which implement it.

param: string $feature The feature being checked. See add_theme_support() for the list
param: string $include Path to the file.
return: bool True if the active theme supports the supplied feature, false otherwise.
since: 2.9.0

register_theme_feature( $feature, $args = array()   X-Ref
Registers a theme feature for use in add_theme_support().

This does not indicate that the active theme supports the feature, it only describes
the feature's supported options.

param: string $feature The name uniquely identifying the feature. See add_theme_support()
param: array  $args {
return: true|WP_Error True if the theme feature was successfully registered, a WP_Error object if not.
since: 5.5.0

get_registered_theme_features()   X-Ref
Gets the list of registered theme features.

return: array[] List of theme features, keyed by their name.
since: 5.5.0

get_registered_theme_feature( $feature )   X-Ref
Gets the registration config for a theme feature.

param: string $feature The feature name. See add_theme_support() for the list
return: array|null The registration args, or null if the feature was not registered.
since: 5.5.0

_delete_attachment_theme_mod( $id )   X-Ref
Checks an attachment being deleted to see if it's a header or background image.

If true it removes the theme modification which would be pointing at the deleted
attachment.

param: int $id The attachment ID.
since: 3.0.0
since: 4.3.0 Also removes `header_image_data`.
since: 4.5.0 Also removes custom logo theme mods.

check_theme_switched()   X-Ref
Checks if a theme has been changed and runs 'after_switch_theme' hook on the next WP load.

See {@see 'after_switch_theme'}.

since: 3.3.0

_wp_customize_include()   X-Ref
Includes and instantiates the WP_Customize_Manager class.

Loads the Customizer at plugins_loaded when accessing the customize.php admin
page or when any request includes a wp_customize=on param or a customize_changeset
param (a UUID). This param is a signal for whether to bootstrap the Customizer when
WordPress is loading, especially in the Customizer preview
or when making Customizer Ajax requests for widgets or menus.

since: 3.4.0

_wp_customize_publish_changeset( $new_status, $old_status, $changeset_post )   X-Ref
Publishes a snapshot's changes.

param: string  $new_status     New post status.
param: string  $old_status     Old post status.
param: WP_Post $changeset_post Changeset post object.
since: 4.7.0

_wp_customize_changeset_filter_insert_post_data( $post_data, $supplied_post_data )   X-Ref
Filters changeset post data upon insert to ensure post_name is intact.

This is needed to prevent the post_name from being dropped when the post is
transitioned into pending status by a contributor.

param: array $post_data          An array of slashed post data.
param: array $supplied_post_data An array of sanitized, but otherwise unmodified post data.
return: array Filtered data.
since: 4.7.0

_wp_customize_loader_settings()   X-Ref
Adds settings for the customize-loader script.

since: 3.4.0

wp_customize_url( $stylesheet = '' )   X-Ref
Returns a URL to load the Customizer.

param: string $stylesheet Optional. Theme to customize. Defaults to active theme.
return: string
since: 3.4.0

wp_customize_support_script()   X-Ref
Prints a script to check whether or not the Customizer is supported,
and apply either the no-customize-support or customize-support class
to the body.

This function MUST be called inside the body tag.

Ideally, call this function immediately after the body tag is opened.
This prevents a flash of unstyled content.

It is also recommended that you add the "no-customize-support" class
to the body tag by default.

since: 3.4.0
since: 4.7.0 Support for IE8 and below is explicitly removed via conditional comments.
since: 5.5.0 IE8 and older are no longer supported.

is_customize_preview()   X-Ref
Whether the site is being previewed in the Customizer.

return: bool True if the site is being previewed in the Customizer, false otherwise.
since: 4.0.0

_wp_keep_alive_customize_changeset_dependent_auto_drafts( $new_status, $old_status, $post )   X-Ref
Makes sure that auto-draft posts get their post_date bumped or status changed
to draft to prevent premature garbage-collection.

When a changeset is updated but remains an auto-draft, ensure the post_date
for the auto-draft posts remains the same so that it will be
garbage-collected at the same time by `wp_delete_auto_drafts()`. Otherwise,
if the changeset is updated to be a draft then update the posts
to have a far-future post_date so that they will never be garbage collected
unless the changeset post itself is deleted.

When a changeset is updated to be a persistent draft or to be scheduled for
publishing, then transition any dependent auto-drafts to a draft status so
that they likewise will not be garbage-collected but also so that they can
be edited in the admin before publishing since there is not yet a post/page
editing flow in the Customizer. See #39752.

param: string   $new_status Transition to this post status.
param: string   $old_status Previous post status.
param: \WP_Post $post       Post data.
since: 4.8.0

create_initial_theme_features()   X-Ref
Creates the initial theme features when the 'setup_theme' action is fired.

See {@see 'setup_theme'}.

since: 5.5.0

wp_is_block_theme()   X-Ref
Returns whether the active theme is a block-based theme or not.

return: boolean Whether the active theme is a block-based theme or not.
since: 5.9.0

_add_default_theme_supports()   X-Ref
Adds default theme supports for block themes when the 'setup_theme' action fires.

See {@see 'setup_theme'}.

since: 5.9.0



Generated: Tue Oct 15 01:00:02 2024 Cross-referenced by PHPXref 0.7.1