locale;
return $locale ? $locale : get_locale();
}
/**
* Determine the current locale desired for the request.
*
* @since 5.0.0
*
* @global string $pagenow
*
* @return string The determined locale.
*/
function determine_locale() {
/**
* Filters the locale for the current request prior to the default determination process.
*
* Using this filter allows to override the default logic, effectively short-circuiting the function.
*
* @since 5.0.0
*
* @param string|null $locale The locale to return and short-circuit. Default null.
*/
$determined_locale = apply_filters( 'pre_determine_locale', null );
if ( ! empty( $determined_locale ) && is_string( $determined_locale ) ) {
return $determined_locale;
}
$determined_locale = get_locale();
if ( is_admin() ) {
$determined_locale = get_user_locale();
}
if ( isset( $_GET['_locale'] ) && 'user' === $_GET['_locale'] && wp_is_json_request() ) {
$determined_locale = get_user_locale();
}
if ( ! empty( $_GET['wp_lang'] ) && ! empty( $GLOBALS['pagenow'] ) && 'wp-login.php' === $GLOBALS['pagenow'] ) {
$determined_locale = sanitize_locale_name( wp_unslash( $_GET['wp_lang'] ) );
}
/**
* Filters the locale for the current request.
*
* @since 5.0.0
*
* @param string $locale The locale.
*/
return apply_filters( 'determine_locale', $determined_locale );
}
/**
* Retrieve the translation of $text.
*
* If there is no translation, or the text domain isn't loaded, the original text is returned.
*
* *Note:* Don't use translate() directly, use __() or related functions.
*
* @since 2.2.0
* @since 5.5.0 Introduced gettext-{$domain} filter.
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function translate( $text, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate( $text );
/**
* Filters text with its translation.
*
* @since 2.0.11
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( 'gettext', $translation, $text, $domain );
/**
* Filters text with its translation for a domain.
*
* The dynamic portion of the hook, `$domain`, refers to the text domain.
*
* @since 5.5.0
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( "gettext_{$domain}", $translation, $text, $domain );
return $translation;
}
/**
* Remove last item on a pipe-delimited string.
*
* Meant for removing the last item in a string, such as 'Role name|User role'. The original
* string will be returned if no pipe '|' characters are found in the string.
*
* @since 2.8.0
*
* @param string $string A pipe-delimited string.
* @return string Either $string or everything before the last pipe.
*/
function before_last_bar( $string ) {
$last_bar = strrpos( $string, '|' );
if ( false === $last_bar ) {
return $string;
} else {
return substr( $string, 0, $last_bar );
}
}
/**
* Retrieve the translation of $text in the context defined in $context.
*
* If there is no translation, or the text domain isn't loaded, the original text is returned.
*
* *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.
*
* @since 2.8.0
* @since 5.5.0 Introduced gettext_with_context-{$domain} filter.
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure.
*/
function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate( $text, $context );
/**
* Filters text with its translation based on context information.
*
* @since 2.8.0
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( 'gettext_with_context', $translation, $text, $context, $domain );
/**
* Filters text with its translation based on context information for a domain.
*
* The dynamic portion of the hook, `$domain`, refers to the text domain.
*
* @since 5.5.0
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( "gettext_with_context_{$domain}", $translation, $text, $context, $domain );
return $translation;
}
/**
* Retrieve the translation of $text.
*
* If there is no translation, or the text domain isn't loaded, the original text is returned.
*
* @since 2.1.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function __( $text, $domain = 'default' ) {
return translate( $text, $domain );
}
/**
* Retrieve the translation of $text and escapes it for safe use in an attribute.
*
* If there is no translation, or the text domain isn't loaded, the original text is returned.
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure.
*/
function esc_attr__( $text, $domain = 'default' ) {
return esc_attr( translate( $text, $domain ) );
}
/**
* Retrieve the translation of $text and escapes it for safe use in HTML output.
*
* If there is no translation, or the text domain isn't loaded, the original text
* is escaped and returned.
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function esc_html__( $text, $domain = 'default' ) {
return esc_html( translate( $text, $domain ) );
}
/**
* Display translated text.
*
* @since 1.2.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function _e( $text, $domain = 'default' ) {
echo translate( $text, $domain );
}
/**
* Display translated text that has been escaped for safe use in an attribute.
*
* Encodes `< > & " '` (less than, greater than, ampersand, double quote, single quote).
* Will never double encode entities.
*
* If you need the value for use in PHP, use esc_attr__().
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function esc_attr_e( $text, $domain = 'default' ) {
echo esc_attr( translate( $text, $domain ) );
}
/**
* Display translated text that has been escaped for safe use in HTML output.
*
* If there is no translation, or the text domain isn't loaded, the original text
* is escaped and displayed.
*
* If you need the value for use in PHP, use esc_html__().
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function esc_html_e( $text, $domain = 'default' ) {
echo esc_html( translate( $text, $domain ) );
}
/**
* Retrieve translated string with gettext context.
*
* Quite a few times, there will be collisions with similar translatable text
* found in more than two places, but with different translated context.
*
* By including the context in the pot file, translators can translate the two
* strings differently.
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe.
*/
function _x( $text, $context, $domain = 'default' ) {
return translate_with_gettext_context( $text, $context, $domain );
}
/**
* Display translated string with gettext context.
*
* @since 3.0.0
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe.
*/
function _ex( $text, $context, $domain = 'default' ) {
echo _x( $text, $context, $domain );
}
/**
* Translate string with gettext context, and escapes it for safe use in an attribute.
*
* If there is no translation, or the text domain isn't loaded, the original text
* is escaped and returned.
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function esc_attr_x( $text, $context, $domain = 'default' ) {
return esc_attr( translate_with_gettext_context( $text, $context, $domain ) );
}
/**
* Translate string with gettext context, and escapes it for safe use in HTML output.
*
* If there is no translation, or the text domain isn't loaded, the original text
* is escaped and returned.
*
* @since 2.9.0
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function esc_html_x( $text, $context, $domain = 'default' ) {
return esc_html( translate_with_gettext_context( $text, $context, $domain ) );
}
/**
* Translates and retrieves the singular or plural form based on the supplied number.
*
* Used when you want to use the appropriate form of a string based on whether a
* number is singular or plural.
*
* Example:
*
* printf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.8.0
* @since 5.5.0 Introduced ngettext-{$domain} filter.
*
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either the singular or plural form.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string The translated singular or plural form.
*/
function _n( $single, $plural, $number, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number );
/**
* Filters the singular or plural form of a string.
*
* @since 2.2.0
*
* @param string $translation Translated text.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
/**
* Filters the singular or plural form of a string for a domain.
*
* The dynamic portion of the hook, `$domain`, refers to the text domain.
*
* @since 5.5.0
*
* @param string $translation Translated text.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( "ngettext_{$domain}", $translation, $single, $plural, $number, $domain );
return $translation;
}
/**
* Translates and retrieves the singular or plural form based on the supplied number, with gettext context.
*
* This is a hybrid of _n() and _x(). It supports context and plurals.
*
* Used when you want to use the appropriate form of a string with context based on whether a
* number is singular or plural.
*
* Example of a generic phrase which is disambiguated via the context parameter:
*
* printf( _nx( '%s group', '%s groups', $people, 'group of people', 'text-domain' ), number_format_i18n( $people ) );
* printf( _nx( '%s group', '%s groups', $animals, 'group of animals', 'text-domain' ), number_format_i18n( $animals ) );
*
* @since 2.8.0
* @since 5.5.0 Introduced ngettext_with_context-{$domain} filter.
*
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either the singular or plural form.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string The translated singular or plural form.
*/
function _nx( $single, $plural, $number, $context, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number, $context );
/**
* Filters the singular or plural form of a string with gettext context.
*
* @since 2.8.0
*
* @param string $translation Translated text.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( 'ngettext_with_context', $translation, $single, $plural, $number, $context, $domain );
/**
* Filters the singular or plural form of a string with gettext context for a domain.
*
* The dynamic portion of the hook, `$domain`, refers to the text domain.
*
* @since 5.5.0
*
* @param string $translation Translated text.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( "ngettext_with_context_{$domain}", $translation, $single, $plural, $number, $context, $domain );
return $translation;
}
/**
* Registers plural strings in POT file, but does not translate them.
*
* Used when you want to keep structures with translatable plural
* strings and use them later when the number is known.
*
* Example:
*
* $message = _n_noop( '%s post', '%s posts', 'text-domain' );
* ...
* printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.5.0
*
* @param string $singular Singular form to be localized.
* @param string $plural Plural form to be localized.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default null.
* @return array {
* Array of translation information for the strings.
*
* @type string $0 Singular form to be localized. No longer used.
* @type string $1 Plural form to be localized. No longer used.
* @type string $singular Singular form to be localized.
* @type string $plural Plural form to be localized.
* @type null $context Context information for the translators.
* @type string $domain Text domain.
* }
*/
function _n_noop( $singular, $plural, $domain = null ) {
return array(
0 => $singular,
1 => $plural,
'singular' => $singular,
'plural' => $plural,
'context' => null,
'domain' => $domain,
);
}
/**
* Registers plural strings with gettext context in POT file, but does not translate them.
*
* Used when you want to keep structures with translatable plural
* strings and use them later when the number is known.
*
* Example of a generic phrase which is disambiguated via the context parameter:
*
* $messages = array(
* 'people' => _nx_noop( '%s group', '%s groups', 'people', 'text-domain' ),
* 'animals' => _nx_noop( '%s group', '%s groups', 'animals', 'text-domain' ),
* );
* ...
* $message = $messages[ $type ];
* printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.8.0
*
* @param string $singular Singular form to be localized.
* @param string $plural Plural form to be localized.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default null.
* @return array {
* Array of translation information for the strings.
*
* @type string $0 Singular form to be localized. No longer used.
* @type string $1 Plural form to be localized. No longer used.
* @type string $2 Context information for the translators. No longer used.
* @type string $singular Singular form to be localized.
* @type string $plural Plural form to be localized.
* @type string $context Context information for the translators.
* @type string $domain Text domain.
* }
*/
function _nx_noop( $singular, $plural, $context, $domain = null ) {
return array(
0 => $singular,
1 => $plural,
2 => $context,
'singular' => $singular,
'plural' => $plural,
'context' => $context,
'domain' => $domain,
);
}
/**
* Translates and retrieves the singular or plural form of a string that's been registered
* with _n_noop() or _nx_noop().
*
* Used when you want to use a translatable plural string once the number is known.
*
* Example:
*
* $message = _n_noop( '%s post', '%s posts', 'text-domain' );
* ...
* printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 3.1.0
*
* @param array $nooped_plural Array with singular, plural, and context keys, usually the result of _n_noop() or _nx_noop().
* @param int $count Number of objects.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains
* a text domain passed to _n_noop() or _nx_noop(), it will override this value. Default 'default'.
* @return string Either $single or $plural translated text.
*/
function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {
if ( $nooped_plural['domain'] ) {
$domain = $nooped_plural['domain'];
}
if ( $nooped_plural['context'] ) {
return _nx( $nooped_plural['singular'], $nooped_plural['plural'], $count, $nooped_plural['context'], $domain );
} else {
return _n( $nooped_plural['singular'], $nooped_plural['plural'], $count, $domain );
}
}
/**
* Load a .mo file into the text domain $domain.
*
* If the text domain already exists, the translations will be merged. If both
* sets have the same string, the translation from the original value will be taken.
*
* On success, the .mo file will be placed in the $l10n global by $domain
* and will be a MO object.
*
* @since 1.5.0
*
* @global MO[] $l10n An array of all currently loaded text domains.
* @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $mofile Path to the .mo file.
* @return bool True on success, false on failure.
*/
function load_textdomain( $domain, $mofile ) {
global $l10n, $l10n_unloaded;
$l10n_unloaded = (array) $l10n_unloaded;
/**
* Filters whether to override the .mo file loading.
*
* @since 2.9.0
*
* @param bool $override Whether to override the .mo file loading. Default false.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $mofile Path to the MO file.
*/
$plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile );
if ( true === (bool) $plugin_override ) {
unset( $l10n_unloaded[ $domain ] );
return true;
}
/**
* Fires before the MO translation file is loaded.
*
* @since 2.9.0
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $mofile Path to the .mo file.
*/
do_action( 'load_textdomain', $domain, $mofile );
/**
* Filters MO file path for loading translations for a specific text domain.
*
* @since 2.9.0
*
* @param string $mofile Path to the MO file.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain );
if ( ! is_readable( $mofile ) ) {
return false;
}
$mo = new MO();
if ( ! $mo->import_from_file( $mofile ) ) {
return false;
}
if ( isset( $l10n[ $domain ] ) ) {
$mo->merge_with( $l10n[ $domain ] );
}
unset( $l10n_unloaded[ $domain ] );
$l10n[ $domain ] = &$mo;
return true;
}
/**
* Unload translations for a text domain.
*
* @since 3.0.0
*
* @global MO[] $l10n An array of all currently loaded text domains.
* @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @return bool Whether textdomain was unloaded.
*/
function unload_textdomain( $domain ) {
global $l10n, $l10n_unloaded;
$l10n_unloaded = (array) $l10n_unloaded;
/**
* Filters whether to override the text domain unloading.
*
* @since 3.0.0
*
* @param bool $override Whether to override the text domain unloading. Default false.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$plugin_override = apply_filters( 'override_unload_textdomain', false, $domain );
if ( $plugin_override ) {
$l10n_unloaded[ $domain ] = true;
return true;
}
/**
* Fires before the text domain is unloaded.
*
* @since 3.0.0
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
do_action( 'unload_textdomain', $domain );
if ( isset( $l10n[ $domain ] ) ) {
unset( $l10n[ $domain ] );
$l10n_unloaded[ $domain ] = true;
return true;
}
return false;
}
/**
* Load default translated strings based on locale.
*
* Loads the .mo file in WP_LANG_DIR constant path from WordPress root.
* The translated (.mo) file is named based on the locale.
*
* @see load_textdomain()
*
* @since 1.5.0
*
* @param string $locale Optional. Locale to load. Default is the value of get_locale().
* @return bool Whether the textdomain was loaded.
*/
function load_default_textdomain( $locale = null ) {
if ( null === $locale ) {
$locale = determine_locale();
}
// Unload previously loaded strings so we can switch translations.
unload_textdomain( 'default' );
$return = load_textdomain( 'default', WP_LANG_DIR . "/$locale.mo" );
if ( ( is_multisite() || ( defined( 'WP_INSTALLING_NETWORK' ) && WP_INSTALLING_NETWORK ) ) && ! file_exists( WP_LANG_DIR . "/admin-$locale.mo" ) ) {
load_textdomain( 'default', WP_LANG_DIR . "/ms-$locale.mo" );
return $return;
}
if ( is_admin() || wp_installing() || ( defined( 'WP_REPAIRING' ) && WP_REPAIRING ) ) {
load_textdomain( 'default', WP_LANG_DIR . "/admin-$locale.mo" );
}
if ( is_network_admin() || ( defined( 'WP_INSTALLING_NETWORK' ) && WP_INSTALLING_NETWORK ) ) {
load_textdomain( 'default', WP_LANG_DIR . "/admin-network-$locale.mo" );
}
return $return;
}
/**
* Loads a plugin's translated strings.
*
* If the path is not given then it will be the root of the plugin directory.
*
* The .mo file should be named based on the text domain with a dash, and then the locale exactly.
*
* @since 1.5.0
* @since 4.6.0 The function now tries to load the .mo file from the languages directory first.
*
* @param string $domain Unique identifier for retrieving translated strings
* @param string|false $deprecated Optional. Deprecated. Use the $plugin_rel_path parameter instead.
* Default false.
* @param string|false $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.
* Default false.
* @return bool True when textdomain is successfully loaded, false otherwise.
*/
function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) {
/**
* Filters a plugin's locale.
*
* @since 3.0.0
*
* @param string $locale The plugin's current locale.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
$mofile = $domain . '-' . $locale . '.mo';
// Try to load from the languages directory first.
if ( load_textdomain( $domain, WP_LANG_DIR . '/plugins/' . $mofile ) ) {
return true;
}
if ( false !== $plugin_rel_path ) {
$path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
} elseif ( false !== $deprecated ) {
_deprecated_argument( __FUNCTION__, '2.7.0' );
$path = ABSPATH . trim( $deprecated, '/' );
} else {
$path = WP_PLUGIN_DIR;
}
return load_textdomain( $domain, $path . '/' . $mofile );
}
/**
* Load the translated strings for a plugin residing in the mu-plugins directory.
*
* @since 3.0.0
* @since 4.6.0 The function now tries to load the .mo file from the languages directory first.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $mu_plugin_rel_path Optional. Relative to `WPMU_PLUGIN_DIR` directory in which the .mo
* file resides. Default empty string.
* @return bool True when textdomain is successfully loaded, false otherwise.
*/
function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) {
/** This filter is documented in wp-includes/l10n.php */
$locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
$mofile = $domain . '-' . $locale . '.mo';
// Try to load from the languages directory first.
if ( load_textdomain( $domain, WP_LANG_DIR . '/plugins/' . $mofile ) ) {
return true;
}
$path = WPMU_PLUGIN_DIR . '/' . ltrim( $mu_plugin_rel_path, '/' );
return load_textdomain( $domain, $path . '/' . $mofile );
}
/**
* Load the theme's translated strings.
*
* If the current locale exists as a .mo file in the theme's root directory, it
* will be included in the translated strings by the $domain.
*
* The .mo files must be named based on the locale exactly.
*
* @since 1.5.0
* @since 4.6.0 The function now tries to load the .mo file from the languages directory first.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $path Optional. Path to the directory containing the .mo file.
* Default false.
* @return bool True when textdomain is successfully loaded, false otherwise.
*/
function load_theme_textdomain( $domain, $path = false ) {
/**
* Filters a theme's locale.
*
* @since 3.0.0
*
* @param string $locale The theme's current locale.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$locale = apply_filters( 'theme_locale', determine_locale(), $domain );
$mofile = $domain . '-' . $locale . '.mo';
// Try to load from the languages directory first.
if ( load_textdomain( $domain, WP_LANG_DIR . '/themes/' . $mofile ) ) {
return true;
}
if ( ! $path ) {
$path = get_template_directory();
}
return load_textdomain( $domain, $path . '/' . $locale . '.mo' );
}
/**
* Load the child themes translated strings.
*
* If the current locale exists as a .mo file in the child themes
* root directory, it will be included in the translated strings by the $domain.
*
* The .mo files must be named based on the locale exactly.
*
* @since 2.9.0
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $path Optional. Path to the directory containing the .mo file.
* Default false.
* @return bool True when the theme textdomain is successfully loaded, false otherwise.
*/
function load_child_theme_textdomain( $domain, $path = false ) {
if ( ! $path ) {
$path = get_stylesheet_directory();
}
return load_theme_textdomain( $domain, $path );
}
/**
* Loads the script translated strings.
*
* @since 5.0.0
* @since 5.0.2 Uses load_script_translations() to load translation data.
* @since 5.1.0 The `$domain` parameter was made optional.
*
* @see WP_Scripts::set_translations()
*
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain Optional. Text domain. Default 'default'.
* @param string $path Optional. The full file path to the directory containing translation files.
* @return string|false False if the script textdomain could not be loaded, the translated strings
* in JSON encoding otherwise.
*/
function load_script_textdomain( $handle, $domain = 'default', $path = null ) {
$wp_scripts = wp_scripts();
if ( ! isset( $wp_scripts->registered[ $handle ] ) ) {
return false;
}
$path = untrailingslashit( $path );
$locale = determine_locale();
// If a path was given and the handle file exists simply return it.
$file_base = 'default' === $domain ? $locale : $domain . '-' . $locale;
$handle_filename = $file_base . '-' . $handle . '.json';
if ( $path ) {
$translations = load_script_translations( $path . '/' . $handle_filename, $handle, $domain );
if ( $translations ) {
return $translations;
}
}
$src = $wp_scripts->registered[ $handle ]->src;
if ( ! preg_match( '|^(https?:)?//|', $src ) && ! ( $wp_scripts->content_url && 0 === strpos( $src, $wp_scripts->content_url ) ) ) {
$src = $wp_scripts->base_url . $src;
}
$relative = false;
$languages_path = WP_LANG_DIR;
$src_url = wp_parse_url( $src );
$content_url = wp_parse_url( content_url() );
$plugins_url = wp_parse_url( plugins_url() );
$site_url = wp_parse_url( site_url() );
// If the host is the same or it's a relative URL.
if (
( ! isset( $content_url['path'] ) || strpos( $src_url['path'], $content_url['path'] ) === 0 ) &&
( ! isset( $src_url['host'] ) || $src_url['host'] === $content_url['host'] )
) {
// Make the src relative the specific plugin or theme.
if ( isset( $content_url['path'] ) ) {
$relative = substr( $src_url['path'], strlen( $content_url['path'] ) );
} else {
$relative = $src_url['path'];
}
$relative = trim( $relative, '/' );
$relative = explode( '/', $relative );
$languages_path = WP_LANG_DIR . '/' . $relative[0];
$relative = array_slice( $relative, 2 ); // Remove plugins/ or themes/.
$relative = implode( '/', $relative );
} elseif (
( ! isset( $plugins_url['path'] ) || strpos( $src_url['path'], $plugins_url['path'] ) === 0 ) &&
( ! isset( $src_url['host'] ) || $src_url['host'] === $plugins_url['host'] )
) {
// Make the src relative the specific plugin.
if ( isset( $plugins_url['path'] ) ) {
$relative = substr( $src_url['path'], strlen( $plugins_url['path'] ) );
} else {
$relative = $src_url['path'];
}
$relative = trim( $relative, '/' );
$relative = explode( '/', $relative );
$languages_path = WP_LANG_DIR . '/plugins';
$relative = array_slice( $relative, 1 ); // Remove .
$relative = implode( '/', $relative );
} elseif ( ! isset( $src_url['host'] ) || $src_url['host'] === $site_url['host'] ) {
if ( ! isset( $site_url['path'] ) ) {
$relative = trim( $src_url['path'], '/' );
} elseif ( ( strpos( $src_url['path'], trailingslashit( $site_url['path'] ) ) === 0 ) ) {
// Make the src relative to the WP root.
$relative = substr( $src_url['path'], strlen( $site_url['path'] ) );
$relative = trim( $relative, '/' );
}
}
/**
* Filters the relative path of scripts used for finding translation files.
*
* @since 5.0.2
*
* @param string|false $relative The relative path of the script. False if it could not be determined.
* @param string $src The full source URL of the script.
*/
$relative = apply_filters( 'load_script_textdomain_relative_path', $relative, $src );
// If the source is not from WP.
if ( false === $relative ) {
return load_script_translations( false, $handle, $domain );
}
// Translations are always based on the unminified filename.
if ( substr( $relative, -7 ) === '.min.js' ) {
$relative = substr( $relative, 0, -7 ) . '.js';
}
$md5_filename = $file_base . '-' . md5( $relative ) . '.json';
if ( $path ) {
$translations = load_script_translations( $path . '/' . $md5_filename, $handle, $domain );
if ( $translations ) {
return $translations;
}
}
$translations = load_script_translations( $languages_path . '/' . $md5_filename, $handle, $domain );
if ( $translations ) {
return $translations;
}
return load_script_translations( false, $handle, $domain );
}
/**
* Loads the translation data for the given script handle and text domain.
*
* @since 5.0.2
*
* @param string|false $file Path to the translation file to load. False if there isn't one.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
* @return string|false The JSON-encoded translated strings for the given script handle and text domain. False if there are none.
*/
function load_script_translations( $file, $handle, $domain ) {
/**
* Pre-filters script translations for the given file, script handle and text domain.
*
* Returning a non-null value allows to override the default logic, effectively short-circuiting the function.
*
* @since 5.0.2
*
* @param string|false|null $translations JSON-encoded translation data. Default null.
* @param string|false $file Path to the translation file to load. False if there isn't one.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
$translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain );
if ( null !== $translations ) {
return $translations;
}
/**
* Filters the file path for loading script translations for the given script handle and text domain.
*
* @since 5.0.2
*
* @param string|false $file Path to the translation file to load. False if there isn't one.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
$file = apply_filters( 'load_script_translation_file', $file, $handle, $domain );
if ( ! $file || ! is_readable( $file ) ) {
return false;
}
$translations = file_get_contents( $file );
/**
* Filters script translations for the given file, script handle and text domain.
*
* @since 5.0.2
*
* @param string $translations JSON-encoded translation data.
* @param string $file Path to the translation file that was loaded.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
return apply_filters( 'load_script_translations', $translations, $file, $handle, $domain );
}
/**
* Loads plugin and theme textdomains just-in-time.
*
* When a textdomain is encountered for the first time, we try to load
* the translation file from `wp-content/languages`, removing the need
* to call load_plugin_texdomain() or load_theme_texdomain().
*
* @since 4.6.0
* @access private
*
* @see get_translations_for_domain()
* @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @return bool True when the textdomain is successfully loaded, false otherwise.
*/
function _load_textdomain_just_in_time( $domain ) {
global $l10n_unloaded;
$l10n_unloaded = (array) $l10n_unloaded;
// Short-circuit if domain is 'default' which is reserved for core.
if ( 'default' === $domain || isset( $l10n_unloaded[ $domain ] ) ) {
return false;
}
$translation_path = _get_path_to_translation( $domain );
if ( false === $translation_path ) {
return false;
}
return load_textdomain( $domain, $translation_path );
}
/**
* Gets the path to a translation file for loading a textdomain just in time.
*
* Caches the retrieved results internally.
*
* @since 4.7.0
* @access private
*
* @see _load_textdomain_just_in_time()
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param bool $reset Whether to reset the internal cache. Used by the switch to locale functionality.
* @return string|false The path to the translation file or false if no translation file was found.
*/
function _get_path_to_translation( $domain, $reset = false ) {
static $available_translations = array();
if ( true === $reset ) {
$available_translations = array();
}
if ( ! isset( $available_translations[ $domain ] ) ) {
$available_translations[ $domain ] = _get_path_to_translation_from_lang_dir( $domain );
}
return $available_translations[ $domain ];
}
/**
* Gets the path to a translation file in the languages directory for the current locale.
*
* Holds a cached list of available .mo files to improve performance.
*
* @since 4.7.0
* @access private
*
* @see _get_path_to_translation()
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @return string|false The path to the translation file or false if no translation file was found.
*/
function _get_path_to_translation_from_lang_dir( $domain ) {
static $cached_mofiles = null;
if ( null === $cached_mofiles ) {
$cached_mofiles = array();
$locations = array(
WP_LANG_DIR . '/plugins',
WP_LANG_DIR . '/themes',
);
foreach ( $locations as $location ) {
$mofiles = glob( $location . '/*.mo' );
if ( $mofiles ) {
$cached_mofiles = array_merge( $cached_mofiles, $mofiles );
}
}
}
$locale = determine_locale();
$mofile = "{$domain}-{$locale}.mo";
$path = WP_LANG_DIR . '/plugins/' . $mofile;
if ( in_array( $path, $cached_mofiles, true ) ) {
return $path;
}
$path = WP_LANG_DIR . '/themes/' . $mofile;
if ( in_array( $path, $cached_mofiles, true ) ) {
return $path;
}
return false;
}
/**
* Return the Translations instance for a text domain.
*
* If there isn't one, returns empty Translations instance.
*
* @since 2.8.0
*
* @global MO[] $l10n
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @return Translations|NOOP_Translations A Translations instance.
*/
function get_translations_for_domain( $domain ) {
global $l10n;
if ( isset( $l10n[ $domain ] ) || ( _load_textdomain_just_in_time( $domain ) && isset( $l10n[ $domain ] ) ) ) {
return $l10n[ $domain ];
}
static $noop_translations = null;
if ( null === $noop_translations ) {
$noop_translations = new NOOP_Translations;
}
return $noop_translations;
}
/**
* Whether there are translations for the text domain.
*
* @since 3.0.0
*
* @global MO[] $l10n
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @return bool Whether there are translations.
*/
function is_textdomain_loaded( $domain ) {
global $l10n;
return isset( $l10n[ $domain ] );
}
/**
* Translates role name.
*
* Since the role names are in the database and not in the source there
* are dummy gettext calls to get them into the POT file and this function
* properly translates them back.
*
* The before_last_bar() call is needed, because older installations keep the roles
* using the old context format: 'Role name|User role' and just skipping the
* content after the last bar is easier than fixing them in the DB. New installations
* won't suffer from that problem.
*
* @since 2.8.0
* @since 5.2.0 Added the `$domain` parameter.
*
* @param string $name The role name.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated role name on success, original name on failure.
*/
function translate_user_role( $name, $domain = 'default' ) {
return translate_with_gettext_context( before_last_bar( $name ), 'User role', $domain );
}
/**
* Get all available languages based on the presence of *.mo files in a given directory.
*
* The default directory is WP_LANG_DIR.
*
* @since 3.0.0
* @since 4.7.0 The results are now filterable with the {@see 'get_available_languages'} filter.
*
* @param string $dir A directory to search for language files.
* Default WP_LANG_DIR.
* @return string[] An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
*/
function get_available_languages( $dir = null ) {
$languages = array();
$lang_files = glob( ( is_null( $dir ) ? WP_LANG_DIR : $dir ) . '/*.mo' );
if ( $lang_files ) {
foreach ( $lang_files as $lang_file ) {
$lang_file = basename( $lang_file, '.mo' );
if ( 0 !== strpos( $lang_file, 'continents-cities' ) && 0 !== strpos( $lang_file, 'ms-' ) &&
0 !== strpos( $lang_file, 'admin-' ) ) {
$languages[] = $lang_file;
}
}
}
/**
* Filters the list of available language codes.
*
* @since 4.7.0
*
* @param string[] $languages An array of available language codes.
* @param string $dir The directory where the language files were found.
*/
return apply_filters( 'get_available_languages', $languages, $dir );
}
/**
* Get installed translations.
*
* Looks in the wp-content/languages directory for translations of
* plugins or themes.
*
* @since 3.7.0
*
* @param string $type What to search for. Accepts 'plugins', 'themes', 'core'.
* @return array Array of language data.
*/
function wp_get_installed_translations( $type ) {
if ( 'themes' !== $type && 'plugins' !== $type && 'core' !== $type ) {
return array();
}
$dir = 'core' === $type ? '' : "/$type";
if ( ! is_dir( WP_LANG_DIR ) ) {
return array();
}
if ( $dir && ! is_dir( WP_LANG_DIR . $dir ) ) {
return array();
}
$files = scandir( WP_LANG_DIR . $dir );
if ( ! $files ) {
return array();
}
$language_data = array();
foreach ( $files as $file ) {
if ( '.' === $file[0] || is_dir( WP_LANG_DIR . "$dir/$file" ) ) {
continue;
}
if ( substr( $file, -3 ) !== '.po' ) {
continue;
}
if ( ! preg_match( '/(?:(.+)-)?([a-z]{2,3}(?:_[A-Z]{2})?(?:_[a-z0-9]+)?).po/', $file, $match ) ) {
continue;
}
if ( ! in_array( substr( $file, 0, -3 ) . '.mo', $files, true ) ) {
continue;
}
list( , $textdomain, $language ) = $match;
if ( '' === $textdomain ) {
$textdomain = 'default';
}
$language_data[ $textdomain ][ $language ] = wp_get_pomo_file_data( WP_LANG_DIR . "$dir/$file" );
}
return $language_data;
}
/**
* Extract headers from a PO file.
*
* @since 3.7.0
*
* @param string $po_file Path to PO file.
* @return string[] Array of PO file header values keyed by header name.
*/
function wp_get_pomo_file_data( $po_file ) {
$headers = get_file_data(
$po_file,
array(
'POT-Creation-Date' => '"POT-Creation-Date',
'PO-Revision-Date' => '"PO-Revision-Date',
'Project-Id-Version' => '"Project-Id-Version',
'X-Generator' => '"X-Generator',
)
);
foreach ( $headers as $header => $value ) {
// Remove possible contextual '\n' and closing double quote.
$headers[ $header ] = preg_replace( '~(\\\n)?"$~', '', $value );
}
return $headers;
}
/**
* Language selector.
*
* @since 4.0.0
* @since 4.3.0 Introduced the `echo` argument.
* @since 4.7.0 Introduced the `show_option_site_default` argument.
* @since 5.1.0 Introduced the `show_option_en_us` argument.
*
* @see get_available_languages()
* @see wp_get_available_translations()
*
* @param string|array $args {
* Optional. Array or string of arguments for outputting the language selector.
*
* @type string $id ID attribute of the select element. Default 'locale'.
* @type string $name Name attribute of the select element. Default 'locale'.
* @type array $languages List of installed languages, contain only the locales.
* Default empty array.
* @type array $translations List of available translations. Default result of
* wp_get_available_translations().
* @type string $selected Language which should be selected. Default empty.
* @type bool|int $echo Whether to echo the generated markup. Accepts 0, 1, or their
* boolean equivalents. Default 1.
* @type bool $show_available_translations Whether to show available translations. Default true.
* @type bool $show_option_site_default Whether to show an option to fall back to the site's locale. Default false.
* @type bool $show_option_en_us Whether to show an option for English (United States). Default true.
* }
* @return string HTML dropdown list of languages.
*/
function wp_dropdown_languages( $args = array() ) {
$parsed_args = wp_parse_args(
$args,
array(
'id' => 'locale',
'name' => 'locale',
'languages' => array(),
'translations' => array(),
'selected' => '',
'echo' => 1,
'show_available_translations' => true,
'show_option_site_default' => false,
'show_option_en_us' => true,
)
);
// Bail if no ID or no name.
if ( ! $parsed_args['id'] || ! $parsed_args['name'] ) {
return;
}
// English (United States) uses an empty string for the value attribute.
if ( 'en_US' === $parsed_args['selected'] ) {
$parsed_args['selected'] = '';
}
$translations = $parsed_args['translations'];
if ( empty( $translations ) ) {
require_once ABSPATH . 'wp-admin/includes/translation-install.php';
$translations = wp_get_available_translations();
}
/*
* $parsed_args['languages'] should only contain the locales. Find the locale in
* $translations to get the native name. Fall back to locale.
*/
$languages = array();
foreach ( $parsed_args['languages'] as $locale ) {
if ( isset( $translations[ $locale ] ) ) {
$translation = $translations[ $locale ];
$languages[] = array(
'language' => $translation['language'],
'native_name' => $translation['native_name'],
'lang' => current( $translation['iso'] ),
);
// Remove installed language from available translations.
unset( $translations[ $locale ] );
} else {
$languages[] = array(
'language' => $locale,
'native_name' => $locale,
'lang' => '',
);
}
}
$translations_available = ( ! empty( $translations ) && $parsed_args['show_available_translations'] );
// Holds the HTML markup.
$structure = array();
// List installed languages.
if ( $translations_available ) {
$structure[] = '';
}
// Site default.
if ( $parsed_args['show_option_site_default'] ) {
$structure[] = sprintf(
'%s ',
selected( 'site-default', $parsed_args['selected'], false ),
_x( 'Site Default', 'default site language' )
);
}
if ( $parsed_args['show_option_en_us'] ) {
$structure[] = sprintf(
'English (United States) ',
selected( '', $parsed_args['selected'], false )
);
}
// List installed languages.
foreach ( $languages as $language ) {
$structure[] = sprintf(
'permalink_structure );
}
/**
* Determines whether permalinks are being used and rewrite module is not enabled.
*
* Means that permalink links are enabled and index.php is in the URL.
*
* @since 1.5.0
*
* @return bool Whether permalink links are enabled and index.php is in the URL.
*/
public function using_index_permalinks() {
if ( empty( $this->permalink_structure ) ) {
return false;
}
// If the index is not in the permalink, we're using mod_rewrite.
return preg_match( '#^/*' . $this->index . '#', $this->permalink_structure );
}
/**
* Determines whether permalinks are being used and rewrite module is enabled.
*
* Using permalinks and index.php is not in the URL.
*
* @since 1.5.0
*
* @return bool Whether permalink links are enabled and index.php is NOT in the URL.
*/
public function using_mod_rewrite_permalinks() {
return $this->using_permalinks() && ! $this->using_index_permalinks();
}
/**
* Indexes for matches for usage in preg_*() functions.
*
* The format of the string is, with empty matches property value, '$NUM'.
* The 'NUM' will be replaced with the value in the $number parameter. With
* the matches property not empty, the value of the returned string will
* contain that value of the matches property. The format then will be
* '$MATCHES[NUM]', with MATCHES as the value in the property and NUM the
* value of the $number parameter.
*
* @since 1.5.0
*
* @param int $number Index number.
* @return string
*/
public function preg_index( $number ) {
$match_prefix = '$';
$match_suffix = '';
if ( ! empty( $this->matches ) ) {
$match_prefix = '$' . $this->matches . '[';
$match_suffix = ']';
}
return "$match_prefix$number$match_suffix";
}
/**
* Retrieves all page and attachments for pages URIs.
*
* The attachments are for those that have pages as parents and will be
* retrieved.
*
* @since 2.5.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @return array Array of page URIs as first element and attachment URIs as second element.
*/
public function page_uri_index() {
global $wpdb;
// Get pages in order of hierarchy, i.e. children after parents.
$pages = $wpdb->get_results( "SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_type = 'page' AND post_status != 'auto-draft'" );
$posts = get_page_hierarchy( $pages );
// If we have no pages get out quick.
if ( ! $posts ) {
return array( array(), array() );
}
// Now reverse it, because we need parents after children for rewrite rules to work properly.
$posts = array_reverse( $posts, true );
$page_uris = array();
$page_attachment_uris = array();
foreach ( $posts as $id => $post ) {
// URL => page name.
$uri = get_page_uri( $id );
$attachments = $wpdb->get_results( $wpdb->prepare( "SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_type = 'attachment' AND post_parent = %d", $id ) );
if ( ! empty( $attachments ) ) {
foreach ( $attachments as $attachment ) {
$attach_uri = get_page_uri( $attachment->ID );
$page_attachment_uris[ $attach_uri ] = $attachment->ID;
}
}
$page_uris[ $uri ] = $id;
}
return array( $page_uris, $page_attachment_uris );
}
/**
* Retrieves all of the rewrite rules for pages.
*
* @since 1.5.0
*
* @return string[] Page rewrite rules.
*/
public function page_rewrite_rules() {
// The extra .? at the beginning prevents clashes with other regular expressions in the rules array.
$this->add_rewrite_tag( '%pagename%', '(.?.+?)', 'pagename=' );
return $this->generate_rewrite_rules( $this->get_page_permastruct(), EP_PAGES, true, true, false, false );
}
/**
* Retrieves date permalink structure, with year, month, and day.
*
* The permalink structure for the date, if not set already depends on the
* permalink structure. It can be one of three formats. The first is year,
* month, day; the second is day, month, year; and the last format is month,
* day, year. These are matched against the permalink structure for which
* one is used. If none matches, then the default will be used, which is
* year, month, day.
*
* Prevents post ID and date permalinks from overlapping. In the case of
* post_id, the date permalink will be prepended with front permalink with
* 'date/' before the actual permalink to form the complete date permalink
* structure.
*
* @since 1.5.0
*
* @return string|false Date permalink structure on success, false on failure.
*/
public function get_date_permastruct() {
if ( isset( $this->date_structure ) ) {
return $this->date_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->date_structure = '';
return false;
}
// The date permalink must have year, month, and day separated by slashes.
$endians = array( '%year%/%monthnum%/%day%', '%day%/%monthnum%/%year%', '%monthnum%/%day%/%year%' );
$this->date_structure = '';
$date_endian = '';
foreach ( $endians as $endian ) {
if ( false !== strpos( $this->permalink_structure, $endian ) ) {
$date_endian = $endian;
break;
}
}
if ( empty( $date_endian ) ) {
$date_endian = '%year%/%monthnum%/%day%';
}
/*
* Do not allow the date tags and %post_id% to overlap in the permalink
* structure. If they do, move the date tags to $front/date/.
*/
$front = $this->front;
preg_match_all( '/%.+?%/', $this->permalink_structure, $tokens );
$tok_index = 1;
foreach ( (array) $tokens[0] as $token ) {
if ( '%post_id%' === $token && ( $tok_index <= 3 ) ) {
$front = $front . 'date/';
break;
}
$tok_index++;
}
$this->date_structure = $front . $date_endian;
return $this->date_structure;
}
/**
* Retrieves the year permalink structure without month and day.
*
* Gets the date permalink structure and strips out the month and day
* permalink structures.
*
* @since 1.5.0
*
* @return string|false Year permalink structure on success, false on failure.
*/
public function get_year_permastruct() {
$structure = $this->get_date_permastruct();
if ( empty( $structure ) ) {
return false;
}
$structure = str_replace( '%monthnum%', '', $structure );
$structure = str_replace( '%day%', '', $structure );
$structure = preg_replace( '#/+#', '/', $structure );
return $structure;
}
/**
* Retrieves the month permalink structure without day and with year.
*
* Gets the date permalink structure and strips out the day permalink
* structures. Keeps the year permalink structure.
*
* @since 1.5.0
*
* @return string|false Year/Month permalink structure on success, false on failure.
*/
public function get_month_permastruct() {
$structure = $this->get_date_permastruct();
if ( empty( $structure ) ) {
return false;
}
$structure = str_replace( '%day%', '', $structure );
$structure = preg_replace( '#/+#', '/', $structure );
return $structure;
}
/**
* Retrieves the day permalink structure with month and year.
*
* Keeps date permalink structure with all year, month, and day.
*
* @since 1.5.0
*
* @return string|false Year/Month/Day permalink structure on success, false on failure.
*/
public function get_day_permastruct() {
return $this->get_date_permastruct();
}
/**
* Retrieves the permalink structure for categories.
*
* If the category_base property has no value, then the category structure
* will have the front property value, followed by 'category', and finally
* '%category%'. If it does, then the root property will be used, along with
* the category_base property value.
*
* @since 1.5.0
*
* @return string|false Category permalink structure on success, false on failure.
*/
public function get_category_permastruct() {
return $this->get_extra_permastruct( 'category' );
}
/**
* Retrieve the permalink structure for tags.
*
* If the tag_base property has no value, then the tag structure will have
* the front property value, followed by 'tag', and finally '%tag%'. If it
* does, then the root property will be used, along with the tag_base
* property value.
*
* @since 2.3.0
*
* @return string|false Tag permalink structure on success, false on failure.
*/
public function get_tag_permastruct() {
return $this->get_extra_permastruct( 'post_tag' );
}
/**
* Retrieves an extra permalink structure by name.
*
* @since 2.5.0
*
* @param string $name Permalink structure name.
* @return string|false Permalink structure string on success, false on failure.
*/
public function get_extra_permastruct( $name ) {
if ( empty( $this->permalink_structure ) ) {
return false;
}
if ( isset( $this->extra_permastructs[ $name ] ) ) {
return $this->extra_permastructs[ $name ]['struct'];
}
return false;
}
/**
* Retrieves the author permalink structure.
*
* The permalink structure is front property, author base, and finally
* '/%author%'. Will set the author_structure property and then return it
* without attempting to set the value again.
*
* @since 1.5.0
*
* @return string|false Author permalink structure on success, false on failure.
*/
public function get_author_permastruct() {
if ( isset( $this->author_structure ) ) {
return $this->author_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->author_structure = '';
return false;
}
$this->author_structure = $this->front . $this->author_base . '/%author%';
return $this->author_structure;
}
/**
* Retrieves the search permalink structure.
*
* The permalink structure is root property, search base, and finally
* '/%search%'. Will set the search_structure property and then return it
* without attempting to set the value again.
*
* @since 1.5.0
*
* @return string|false Search permalink structure on success, false on failure.
*/
public function get_search_permastruct() {
if ( isset( $this->search_structure ) ) {
return $this->search_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->search_structure = '';
return false;
}
$this->search_structure = $this->root . $this->search_base . '/%search%';
return $this->search_structure;
}
/**
* Retrieves the page permalink structure.
*
* The permalink structure is root property, and '%pagename%'. Will set the
* page_structure property and then return it without attempting to set the
* value again.
*
* @since 1.5.0
*
* @return string|false Page permalink structure on success, false on failure.
*/
public function get_page_permastruct() {
if ( isset( $this->page_structure ) ) {
return $this->page_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->page_structure = '';
return false;
}
$this->page_structure = $this->root . '%pagename%';
return $this->page_structure;
}
/**
* Retrieves the feed permalink structure.
*
* The permalink structure is root property, feed base, and finally
* '/%feed%'. Will set the feed_structure property and then return it
* without attempting to set the value again.
*
* @since 1.5.0
*
* @return string|false Feed permalink structure on success, false on failure.
*/
public function get_feed_permastruct() {
if ( isset( $this->feed_structure ) ) {
return $this->feed_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->feed_structure = '';
return false;
}
$this->feed_structure = $this->root . $this->feed_base . '/%feed%';
return $this->feed_structure;
}
/**
* Retrieves the comment feed permalink structure.
*
* The permalink structure is root property, comment base property, feed
* base and finally '/%feed%'. Will set the comment_feed_structure property
* and then return it without attempting to set the value again.
*
* @since 1.5.0
*
* @return string|false Comment feed permalink structure on success, false on failure.
*/
public function get_comment_feed_permastruct() {
if ( isset( $this->comment_feed_structure ) ) {
return $this->comment_feed_structure;
}
if ( empty( $this->permalink_structure ) ) {
$this->comment_feed_structure = '';
return false;
}
$this->comment_feed_structure = $this->root . $this->comments_base . '/' . $this->feed_base . '/%feed%';
return $this->comment_feed_structure;
}
/**
* Adds or updates existing rewrite tags (e.g. %postname%).
*
* If the tag already exists, replace the existing pattern and query for
* that tag, otherwise add the new tag.
*
* @since 1.5.0
*
* @see WP_Rewrite::$rewritecode
* @see WP_Rewrite::$rewritereplace
* @see WP_Rewrite::$queryreplace
*
* @param string $tag Name of the rewrite tag to add or update.
* @param string $regex Regular expression to substitute the tag for in rewrite rules.
* @param string $query String to append to the rewritten query. Must end in '='.
*/
public function add_rewrite_tag( $tag, $regex, $query ) {
$position = array_search( $tag, $this->rewritecode, true );
if ( false !== $position && null !== $position ) {
$this->rewritereplace[ $position ] = $regex;
$this->queryreplace[ $position ] = $query;
} else {
$this->rewritecode[] = $tag;
$this->rewritereplace[] = $regex;
$this->queryreplace[] = $query;
}
}
/**
* Removes an existing rewrite tag.
*
* @since 4.5.0
*
* @see WP_Rewrite::$rewritecode
* @see WP_Rewrite::$rewritereplace
* @see WP_Rewrite::$queryreplace
*
* @param string $tag Name of the rewrite tag to remove.
*/
public function remove_rewrite_tag( $tag ) {
$position = array_search( $tag, $this->rewritecode, true );
if ( false !== $position && null !== $position ) {
unset( $this->rewritecode[ $position ] );
unset( $this->rewritereplace[ $position ] );
unset( $this->queryreplace[ $position ] );
}
}
/**
* Generates rewrite rules from a permalink structure.
*
* The main WP_Rewrite function for building the rewrite rule list. The
* contents of the function is a mix of black magic and regular expressions,
* so best just ignore the contents and move to the parameters.
*
* @since 1.5.0
*
* @param string $permalink_structure The permalink structure.
* @param int $ep_mask Optional. Endpoint mask defining what endpoints are added to the structure.
* Accepts `EP_NONE`, `EP_PERMALINK`, `EP_ATTACHMENT`, `EP_DATE`, `EP_YEAR`,
* `EP_MONTH`, `EP_DAY`, `EP_ROOT`, `EP_COMMENTS`, `EP_SEARCH`, `EP_CATEGORIES`,
* `EP_TAGS`, `EP_AUTHORS`, `EP_PAGES`, `EP_ALL_ARCHIVES`, and `EP_ALL`.
* Default `EP_NONE`.
* @param bool $paged Optional. Whether archive pagination rules should be added for the structure.
* Default true.
* @param bool $feed Optional Whether feed rewrite rules should be added for the structure.
* Default true.
* @param bool $forcomments Optional. Whether the feed rules should be a query for a comments feed.
* Default false.
* @param bool $walk_dirs Optional. Whether the 'directories' making up the structure should be walked
* over and rewrite rules built for each in-turn. Default true.
* @param bool $endpoints Optional. Whether endpoints should be applied to the generated rewrite rules.
* Default true.
* @return string[] Array of rewrite rules keyed by their regex pattern.
*/
public function generate_rewrite_rules( $permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true ) {
// Build a regex to match the feed section of URLs, something like (feed|atom|rss|rss2)/?
$feedregex2 = '';
foreach ( (array) $this->feeds as $feed_name ) {
$feedregex2 .= $feed_name . '|';
}
$feedregex2 = '(' . trim( $feedregex2, '|' ) . ')/?$';
/*
* $feedregex is identical but with /feed/ added on as well, so URLs like /feed/atom
* and /atom are both possible
*/
$feedregex = $this->feed_base . '/' . $feedregex2;
// Build a regex to match the trackback and page/xx parts of URLs.
$trackbackregex = 'trackback/?$';
$pageregex = $this->pagination_base . '/?([0-9]{1,})/?$';
$commentregex = $this->comments_pagination_base . '-([0-9]{1,})/?$';
$embedregex = 'embed/?$';
// Build up an array of endpoint regexes to append => queries to append.
if ( $endpoints ) {
$ep_query_append = array();
foreach ( (array) $this->endpoints as $endpoint ) {
// Match everything after the endpoint name, but allow for nothing to appear there.
$epmatch = $endpoint[1] . '(/(.*))?/?$';
// This will be appended on to the rest of the query for each dir.
$epquery = '&' . $endpoint[2] . '=';
$ep_query_append[ $epmatch ] = array( $endpoint[0], $epquery );
}
}
// Get everything up to the first rewrite tag.
$front = substr( $permalink_structure, 0, strpos( $permalink_structure, '%' ) );
// Build an array of the tags (note that said array ends up being in $tokens[0]).
preg_match_all( '/%.+?%/', $permalink_structure, $tokens );
$num_tokens = count( $tokens[0] );
$index = $this->index; // Probably 'index.php'.
$feedindex = $index;
$trackbackindex = $index;
$embedindex = $index;
/*
* Build a list from the rewritecode and queryreplace arrays, that will look something
* like tagname=$matches[i] where i is the current $i.
*/
$queries = array();
for ( $i = 0; $i < $num_tokens; ++$i ) {
if ( 0 < $i ) {
$queries[ $i ] = $queries[ $i - 1 ] . '&';
} else {
$queries[ $i ] = '';
}
$query_token = str_replace( $this->rewritecode, $this->queryreplace, $tokens[0][ $i ] ) . $this->preg_index( $i + 1 );
$queries[ $i ] .= $query_token;
}
// Get the structure, minus any cruft (stuff that isn't tags) at the front.
$structure = $permalink_structure;
if ( '/' !== $front ) {
$structure = str_replace( $front, '', $structure );
}
/*
* Create a list of dirs to walk over, making rewrite rules for each level
* so for example, a $structure of /%year%/%monthnum%/%postname% would create
* rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname%
*/
$structure = trim( $structure, '/' );
$dirs = $walk_dirs ? explode( '/', $structure ) : array( $structure );
$num_dirs = count( $dirs );
// Strip slashes from the front of $front.
$front = preg_replace( '|^/+|', '', $front );
// The main workhorse loop.
$post_rewrite = array();
$struct = $front;
for ( $j = 0; $j < $num_dirs; ++$j ) {
// Get the struct for this dir, and trim slashes off the front.
$struct .= $dirs[ $j ] . '/'; // Accumulate. see comment near explode('/', $structure) above.
$struct = ltrim( $struct, '/' );
// Replace tags with regexes.
$match = str_replace( $this->rewritecode, $this->rewritereplace, $struct );
// Make a list of tags, and store how many there are in $num_toks.
$num_toks = preg_match_all( '/%.+?%/', $struct, $toks );
// Get the 'tagname=$matches[i]'.
$query = ( ! empty( $num_toks ) && isset( $queries[ $num_toks - 1 ] ) ) ? $queries[ $num_toks - 1 ] : '';
// Set up $ep_mask_specific which is used to match more specific URL types.
switch ( $dirs[ $j ] ) {
case '%year%':
$ep_mask_specific = EP_YEAR;
break;
case '%monthnum%':
$ep_mask_specific = EP_MONTH;
break;
case '%day%':
$ep_mask_specific = EP_DAY;
break;
default:
$ep_mask_specific = EP_NONE;
}
// Create query for /page/xx.
$pagematch = $match . $pageregex;
$pagequery = $index . '?' . $query . '&paged=' . $this->preg_index( $num_toks + 1 );
// Create query for /comment-page-xx.
$commentmatch = $match . $commentregex;
$commentquery = $index . '?' . $query . '&cpage=' . $this->preg_index( $num_toks + 1 );
if ( get_option( 'page_on_front' ) ) {
// Create query for Root /comment-page-xx.
$rootcommentmatch = $match . $commentregex;
$rootcommentquery = $index . '?' . $query . '&page_id=' . get_option( 'page_on_front' ) . '&cpage=' . $this->preg_index( $num_toks + 1 );
}
// Create query for /feed/(feed|atom|rss|rss2|rdf).
$feedmatch = $match . $feedregex;
$feedquery = $feedindex . '?' . $query . '&feed=' . $this->preg_index( $num_toks + 1 );
// Create query for /(feed|atom|rss|rss2|rdf) (see comment near creation of $feedregex).
$feedmatch2 = $match . $feedregex2;
$feedquery2 = $feedindex . '?' . $query . '&feed=' . $this->preg_index( $num_toks + 1 );
// Create query and regex for embeds.
$embedmatch = $match . $embedregex;
$embedquery = $embedindex . '?' . $query . '&embed=true';
// If asked to, turn the feed queries into comment feed ones.
if ( $forcomments ) {
$feedquery .= '&withcomments=1';
$feedquery2 .= '&withcomments=1';
}
// Start creating the array of rewrites for this dir.
$rewrite = array();
// ...adding on /feed/ regexes => queries.
if ( $feed ) {
$rewrite = array(
$feedmatch => $feedquery,
$feedmatch2 => $feedquery2,
$embedmatch => $embedquery,
);
}
// ...and /page/xx ones.
if ( $paged ) {
$rewrite = array_merge( $rewrite, array( $pagematch => $pagequery ) );
}
// Only on pages with comments add ../comment-page-xx/.
if ( EP_PAGES & $ep_mask || EP_PERMALINK & $ep_mask ) {
$rewrite = array_merge( $rewrite, array( $commentmatch => $commentquery ) );
} elseif ( EP_ROOT & $ep_mask && get_option( 'page_on_front' ) ) {
$rewrite = array_merge( $rewrite, array( $rootcommentmatch => $rootcommentquery ) );
}
// Do endpoints.
if ( $endpoints ) {
foreach ( (array) $ep_query_append as $regex => $ep ) {
// Add the endpoints on if the mask fits.
if ( $ep[0] & $ep_mask || $ep[0] & $ep_mask_specific ) {
$rewrite[ $match . $regex ] = $index . '?' . $query . $ep[1] . $this->preg_index( $num_toks + 2 );
}
}
}
// If we've got some tags in this dir.
if ( $num_toks ) {
$post = false;
$page = false;
/*
* Check to see if this dir is permalink-level: i.e. the structure specifies an
* individual post. Do this by checking it contains at least one of 1) post name,
* 2) post ID, 3) page name, 4) timestamp (year, month, day, hour, second and
* minute all present). Set these flags now as we need them for the endpoints.
*/
if ( strpos( $struct, '%postname%' ) !== false
|| strpos( $struct, '%post_id%' ) !== false
|| strpos( $struct, '%pagename%' ) !== false
|| ( strpos( $struct, '%year%' ) !== false && strpos( $struct, '%monthnum%' ) !== false && strpos( $struct, '%day%' ) !== false && strpos( $struct, '%hour%' ) !== false && strpos( $struct, '%minute%' ) !== false && strpos( $struct, '%second%' ) !== false )
) {
$post = true;
if ( strpos( $struct, '%pagename%' ) !== false ) {
$page = true;
}
}
if ( ! $post ) {
// For custom post types, we need to add on endpoints as well.
foreach ( get_post_types( array( '_builtin' => false ) ) as $ptype ) {
if ( strpos( $struct, "%$ptype%" ) !== false ) {
$post = true;
// This is for page style attachment URLs.
$page = is_post_type_hierarchical( $ptype );
break;
}
}
}
// If creating rules for a permalink, do all the endpoints like attachments etc.
if ( $post ) {
// Create query and regex for trackback.
$trackbackmatch = $match . $trackbackregex;
$trackbackquery = $trackbackindex . '?' . $query . '&tb=1';
// Create query and regex for embeds.
$embedmatch = $match . $embedregex;
$embedquery = $embedindex . '?' . $query . '&embed=true';
// Trim slashes from the end of the regex for this dir.
$match = rtrim( $match, '/' );
// Get rid of brackets.
$submatchbase = str_replace( array( '(', ')' ), '', $match );
// Add a rule for at attachments, which take the form of /some-text.
$sub1 = $submatchbase . '/([^/]+)/';
// Add trackback regex /trackback/...
$sub1tb = $sub1 . $trackbackregex;
// And /feed/(atom|...)
$sub1feed = $sub1 . $feedregex;
// And /(feed|atom...)
$sub1feed2 = $sub1 . $feedregex2;
// And /comment-page-xx
$sub1comment = $sub1 . $commentregex;
// And /embed/...
$sub1embed = $sub1 . $embedregex;
/*
* Add another rule to match attachments in the explicit form:
* /attachment/some-text
*/
$sub2 = $submatchbase . '/attachment/([^/]+)/';
// And add trackbacks /attachment/trackback.
$sub2tb = $sub2 . $trackbackregex;
// Feeds, /attachment/feed/(atom|...)
$sub2feed = $sub2 . $feedregex;
// And feeds again on to this /attachment/(feed|atom...)
$sub2feed2 = $sub2 . $feedregex2;
// And /comment-page-xx
$sub2comment = $sub2 . $commentregex;
// And /embed/...
$sub2embed = $sub2 . $embedregex;
// Create queries for these extra tag-ons we've just dealt with.
$subquery = $index . '?attachment=' . $this->preg_index( 1 );
$subtbquery = $subquery . '&tb=1';
$subfeedquery = $subquery . '&feed=' . $this->preg_index( 2 );
$subcommentquery = $subquery . '&cpage=' . $this->preg_index( 2 );
$subembedquery = $subquery . '&embed=true';
// Do endpoints for attachments.
if ( ! empty( $endpoints ) ) {
foreach ( (array) $ep_query_append as $regex => $ep ) {
if ( $ep[0] & EP_ATTACHMENT ) {
$rewrite[ $sub1 . $regex ] = $subquery . $ep[1] . $this->preg_index( 3 );
$rewrite[ $sub2 . $regex ] = $subquery . $ep[1] . $this->preg_index( 3 );
}
}
}
/*
* Now we've finished with endpoints, finish off the $sub1 and $sub2 matches
* add a ? as we don't have to match that last slash, and finally a $ so we
* match to the end of the URL
*/
$sub1 .= '?$';
$sub2 .= '?$';
/*
* Post pagination, e.g. /2/
* Previously: '(/[0-9]+)?/?$', which produced '/2' for page.
* When cast to int, returned 0.
*/
$match = $match . '(?:/([0-9]+))?/?$';
$query = $index . '?' . $query . '&page=' . $this->preg_index( $num_toks + 1 );
// Not matching a permalink so this is a lot simpler.
} else {
// Close the match and finalise the query.
$match .= '?$';
$query = $index . '?' . $query;
}
/*
* Create the final array for this dir by joining the $rewrite array (which currently
* only contains rules/queries for trackback, pages etc) to the main regex/query for
* this dir
*/
$rewrite = array_merge( $rewrite, array( $match => $query ) );
// If we're matching a permalink, add those extras (attachments etc) on.
if ( $post ) {
// Add trackback.
$rewrite = array_merge( array( $trackbackmatch => $trackbackquery ), $rewrite );
// Add embed.
$rewrite = array_merge( array( $embedmatch => $embedquery ), $rewrite );
// Add regexes/queries for attachments, attachment trackbacks and so on.
if ( ! $page ) {
// Require /attachment/stuff form for pages because of confusion with subpages.
$rewrite = array_merge(
$rewrite,
array(
$sub1 => $subquery,
$sub1tb => $subtbquery,
$sub1feed => $subfeedquery,
$sub1feed2 => $subfeedquery,
$sub1comment => $subcommentquery,
$sub1embed => $subembedquery,
)
);
}
$rewrite = array_merge(
array(
$sub2 => $subquery,
$sub2tb => $subtbquery,
$sub2feed => $subfeedquery,
$sub2feed2 => $subfeedquery,
$sub2comment => $subcommentquery,
$sub2embed => $subembedquery,
),
$rewrite
);
}
}
// Add the rules for this dir to the accumulating $post_rewrite.
$post_rewrite = array_merge( $rewrite, $post_rewrite );
}
// The finished rules. phew!
return $post_rewrite;
}
/**
* Generates rewrite rules with permalink structure and walking directory only.
*
* Shorten version of WP_Rewrite::generate_rewrite_rules() that allows for shorter
* list of parameters. See the method for longer description of what generating
* rewrite rules does.
*
* @since 1.5.0
*
* @see WP_Rewrite::generate_rewrite_rules() See for long description and rest of parameters.
*
* @param string $permalink_structure The permalink structure to generate rules.
* @param bool $walk_dirs Optional. Whether to create list of directories to walk over.
* Default false.
* @return array
*/
public function generate_rewrite_rule( $permalink_structure, $walk_dirs = false ) {
return $this->generate_rewrite_rules( $permalink_structure, EP_NONE, false, false, false, $walk_dirs );
}
/**
* Constructs rewrite matches and queries from permalink structure.
*
* Runs the action {@see 'generate_rewrite_rules'} with the parameter that is an
* reference to the current WP_Rewrite instance to further manipulate the
* permalink structures and rewrite rules. Runs the {@see 'rewrite_rules_array'}
* filter on the full rewrite rule array.
*
* There are two ways to manipulate the rewrite rules, one by hooking into
* the {@see 'generate_rewrite_rules'} action and gaining full control of the
* object or just manipulating the rewrite rule array before it is passed
* from the function.
*
* @since 1.5.0
*
* @return string[] An associative array of matches and queries.
*/
public function rewrite_rules() {
$rewrite = array();
if ( empty( $this->permalink_structure ) ) {
return $rewrite;
}
// robots.txt -- only if installed at the root.
$home_path = parse_url( home_url() );
$robots_rewrite = ( empty( $home_path['path'] ) || '/' === $home_path['path'] ) ? array( 'robots\.txt$' => $this->index . '?robots=1' ) : array();
// favicon.ico -- only if installed at the root.
$favicon_rewrite = ( empty( $home_path['path'] ) || '/' === $home_path['path'] ) ? array( 'favicon\.ico$' => $this->index . '?favicon=1' ) : array();
// Old feed and service files.
$deprecated_files = array(
'.*wp-(atom|rdf|rss|rss2|feed|commentsrss2)\.php$' => $this->index . '?feed=old',
'.*wp-app\.php(/.*)?$' => $this->index . '?error=403',
);
// Registration rules.
$registration_pages = array();
if ( is_multisite() && is_main_site() ) {
$registration_pages['.*wp-signup.php$'] = $this->index . '?signup=true';
$registration_pages['.*wp-activate.php$'] = $this->index . '?activate=true';
}
// Deprecated.
$registration_pages['.*wp-register.php$'] = $this->index . '?register=true';
// Post rewrite rules.
$post_rewrite = $this->generate_rewrite_rules( $this->permalink_structure, EP_PERMALINK );
/**
* Filters rewrite rules used for "post" archives.
*
* @since 1.5.0
*
* @param string[] $post_rewrite Array of rewrite rules for posts, keyed by their regex pattern.
*/
$post_rewrite = apply_filters( 'post_rewrite_rules', $post_rewrite );
// Date rewrite rules.
$date_rewrite = $this->generate_rewrite_rules( $this->get_date_permastruct(), EP_DATE );
/**
* Filters rewrite rules used for date archives.
*
* Likely date archives would include /yyyy/, /yyyy/mm/, and /yyyy/mm/dd/.
*
* @since 1.5.0
*
* @param string[] $date_rewrite Array of rewrite rules for date archives, keyed by their regex pattern.
*/
$date_rewrite = apply_filters( 'date_rewrite_rules', $date_rewrite );
// Root-level rewrite rules.
$root_rewrite = $this->generate_rewrite_rules( $this->root . '/', EP_ROOT );
/**
* Filters rewrite rules used for root-level archives.
*
* Likely root-level archives would include pagination rules for the homepage
* as well as site-wide post feeds (e.g. /feed/, and /feed/atom/).
*
* @since 1.5.0
*
* @param string[] $root_rewrite Array of root-level rewrite rules, keyed by their regex pattern.
*/
$root_rewrite = apply_filters( 'root_rewrite_rules', $root_rewrite );
// Comments rewrite rules.
$comments_rewrite = $this->generate_rewrite_rules( $this->root . $this->comments_base, EP_COMMENTS, false, true, true, false );
/**
* Filters rewrite rules used for comment feed archives.
*
* Likely comments feed archives include /comments/feed/, and /comments/feed/atom/.
*
* @since 1.5.0
*
* @param string[] $comments_rewrite Array of rewrite rules for the site-wide comments feeds, keyed by their regex pattern.
*/
$comments_rewrite = apply_filters( 'comments_rewrite_rules', $comments_rewrite );
// Search rewrite rules.
$search_structure = $this->get_search_permastruct();
$search_rewrite = $this->generate_rewrite_rules( $search_structure, EP_SEARCH );
/**
* Filters rewrite rules used for search archives.
*
* Likely search-related archives include /search/search+query/ as well as
* pagination and feed paths for a search.
*
* @since 1.5.0
*
* @param string[] $search_rewrite Array of rewrite rules for search queries, keyed by their regex pattern.
*/
$search_rewrite = apply_filters( 'search_rewrite_rules', $search_rewrite );
// Author rewrite rules.
$author_rewrite = $this->generate_rewrite_rules( $this->get_author_permastruct(), EP_AUTHORS );
/**
* Filters rewrite rules used for author archives.
*
* Likely author archives would include /author/author-name/, as well as
* pagination and feed paths for author archives.
*
* @since 1.5.0
*
* @param string[] $author_rewrite Array of rewrite rules for author archives, keyed by their regex pattern.
*/
$author_rewrite = apply_filters( 'author_rewrite_rules', $author_rewrite );
// Pages rewrite rules.
$page_rewrite = $this->page_rewrite_rules();
/**
* Filters rewrite rules used for "page" post type archives.
*
* @since 1.5.0
*
* @param string[] $page_rewrite Array of rewrite rules for the "page" post type, keyed by their regex pattern.
*/
$page_rewrite = apply_filters( 'page_rewrite_rules', $page_rewrite );
// Extra permastructs.
foreach ( $this->extra_permastructs as $permastructname => $struct ) {
if ( is_array( $struct ) ) {
if ( count( $struct ) == 2 ) {
$rules = $this->generate_rewrite_rules( $struct[0], $struct[1] );
} else {
$rules = $this->generate_rewrite_rules( $struct['struct'], $struct['ep_mask'], $struct['paged'], $struct['feed'], $struct['forcomments'], $struct['walk_dirs'], $struct['endpoints'] );
}
} else {
$rules = $this->generate_rewrite_rules( $struct );
}
/**
* Filters rewrite rules used for individual permastructs.
*
* The dynamic portion of the hook name, `$permastructname`, refers
* to the name of the registered permastruct, e.g. 'post_tag' (tags),
* 'category' (categories), etc.
*
* @since 3.1.0
*
* @param string[] $rules Array of rewrite rules generated for the current permastruct, keyed by their regex pattern.
*/
$rules = apply_filters( "{$permastructname}_rewrite_rules", $rules );
if ( 'post_tag' === $permastructname ) {
/**
* Filters rewrite rules used specifically for Tags.
*
* @since 2.3.0
* @deprecated 3.1.0 Use {@see 'post_tag_rewrite_rules'} instead.
*
* @param string[] $rules Array of rewrite rules generated for tags, keyed by their regex pattern.
*/
$rules = apply_filters_deprecated( 'tag_rewrite_rules', array( $rules ), '3.1.0', 'post_tag_rewrite_rules' );
}
$this->extra_rules_top = array_merge( $this->extra_rules_top, $rules );
}
// Put them together.
if ( $this->use_verbose_page_rules ) {
$this->rules = array_merge( $this->extra_rules_top, $robots_rewrite, $favicon_rewrite, $deprecated_files, $registration_pages, $root_rewrite, $comments_rewrite, $search_rewrite, $author_rewrite, $date_rewrite, $page_rewrite, $post_rewrite, $this->extra_rules );
} else {
$this->rules = array_merge( $this->extra_rules_top, $robots_rewrite, $favicon_rewrite, $deprecated_files, $registration_pages, $root_rewrite, $comments_rewrite, $search_rewrite, $author_rewrite, $date_rewrite, $post_rewrite, $page_rewrite, $this->extra_rules );
}
/**
* Fires after the rewrite rules are generated.
*
* @since 1.5.0
*
* @param WP_Rewrite $this Current WP_Rewrite instance (passed by reference).
*/
do_action_ref_array( 'generate_rewrite_rules', array( &$this ) );
/**
* Filters the full set of generated rewrite rules.
*
* @since 1.5.0
*
* @param string[] $rules The compiled array of rewrite rules, keyed by their regex pattern.
*/
$this->rules = apply_filters( 'rewrite_rules_array', $this->rules );
return $this->rules;
}
/**
* Retrieves the rewrite rules.
*
* The difference between this method and WP_Rewrite::rewrite_rules() is that
* this method stores the rewrite rules in the 'rewrite_rules' option and retrieves
* it. This prevents having to process all of the permalinks to get the rewrite rules
* in the form of caching.
*
* @since 1.5.0
*
* @return string[] Array of rewrite rules keyed by their regex pattern.
*/
public function wp_rewrite_rules() {
$this->rules = get_option( 'rewrite_rules' );
if ( empty( $this->rules ) ) {
$this->matches = 'matches';
$this->rewrite_rules();
if ( ! did_action( 'wp_loaded' ) ) {
add_action( 'wp_loaded', array( $this, 'flush_rules' ) );
return $this->rules;
}
update_option( 'rewrite_rules', $this->rules );
}
return $this->rules;
}
/**
* Retrieves mod_rewrite-formatted rewrite rules to write to .htaccess.
*
* Does not actually write to the .htaccess file, but creates the rules for
* the process that will.
*
* Will add the non_wp_rules property rules to the .htaccess file before
* the WordPress rewrite rules one.
*
* @since 1.5.0
*
* @return string
*/
public function mod_rewrite_rules() {
if ( ! $this->using_permalinks() ) {
return '';
}
$site_root = parse_url( site_url() );
if ( isset( $site_root['path'] ) ) {
$site_root = trailingslashit( $site_root['path'] );
}
$home_root = parse_url( home_url() );
if ( isset( $home_root['path'] ) ) {
$home_root = trailingslashit( $home_root['path'] );
} else {
$home_root = '/';
}
$rules = "\n";
$rules .= "RewriteEngine On\n";
$rules .= "RewriteBase $home_root\n";
// Prevent -f checks on index.php.
$rules .= "RewriteRule ^index\.php$ - [L]\n";
// Add in the rules that don't redirect to WP's index.php (and thus shouldn't be handled by WP at all).
foreach ( (array) $this->non_wp_rules as $match => $query ) {
// Apache 1.3 does not support the reluctant (non-greedy) modifier.
$match = str_replace( '.+?', '.+', $match );
$rules .= 'RewriteRule ^' . $match . ' ' . $home_root . $query . " [QSA,L]\n";
}
if ( $this->use_verbose_rules ) {
$this->matches = '';
$rewrite = $this->rewrite_rules();
$num_rules = count( $rewrite );
$rules .= "RewriteCond %{REQUEST_FILENAME} -f [OR]\n" .
"RewriteCond %{REQUEST_FILENAME} -d\n" .
"RewriteRule ^.*$ - [S=$num_rules]\n";
foreach ( (array) $rewrite as $match => $query ) {
// Apache 1.3 does not support the reluctant (non-greedy) modifier.
$match = str_replace( '.+?', '.+', $match );
if ( strpos( $query, $this->index ) !== false ) {
$rules .= 'RewriteRule ^' . $match . ' ' . $home_root . $query . " [QSA,L]\n";
} else {
$rules .= 'RewriteRule ^' . $match . ' ' . $site_root . $query . " [QSA,L]\n";
}
}
} else {
$rules .= "RewriteCond %{REQUEST_FILENAME} !-f\n" .
"RewriteCond %{REQUEST_FILENAME} !-d\n" .
"RewriteRule . {$home_root}{$this->index} [L]\n";
}
$rules .= " \n";
/**
* Filters the list of rewrite rules formatted for output to an .htaccess file.
*
* @since 1.5.0
*
* @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
*/
$rules = apply_filters( 'mod_rewrite_rules', $rules );
/**
* Filters the list of rewrite rules formatted for output to an .htaccess file.
*
* @since 1.5.0
* @deprecated 1.5.0 Use the {@see 'mod_rewrite_rules'} filter instead.
*
* @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
*/
return apply_filters_deprecated( 'rewrite_rules', array( $rules ), '1.5.0', 'mod_rewrite_rules' );
}
/**
* Retrieves IIS7 URL Rewrite formatted rewrite rules to write to web.config file.
*
* Does not actually write to the web.config file, but creates the rules for
* the process that will.
*
* @since 2.8.0
*
* @param bool $add_parent_tags Optional. Whether to add parent tags to the rewrite rule sets.
* Default false.
* @return string IIS7 URL rewrite rule sets.
*/
public function iis7_url_rewrite_rules( $add_parent_tags = false ) {
if ( ! $this->using_permalinks() ) {
return '';
}
$rules = '';
if ( $add_parent_tags ) {
$rules .= '
';
}
$rules .= '
';
if ( $add_parent_tags ) {
$rules .= '
';
}
/**
* Filters the list of rewrite rules formatted for output to a web.config.
*
* @since 2.8.0
*
* @param string $rules Rewrite rules formatted for IIS web.config.
*/
return apply_filters( 'iis7_url_rewrite_rules', $rules );
}
/**
* Adds a rewrite rule that transforms a URL structure to a set of query vars.
*
* Any value in the $after parameter that isn't 'bottom' will result in the rule
* being placed at the top of the rewrite rules.
*
* @since 2.1.0
* @since 4.4.0 Array support was added to the `$query` parameter.
*
* @param string $regex Regular expression to match request against.
* @param string|array $query The corresponding query vars for this rewrite rule.
* @param string $after Optional. Priority of the new rule. Accepts 'top'
* or 'bottom'. Default 'bottom'.
*/
public function add_rule( $regex, $query, $after = 'bottom' ) {
if ( is_array( $query ) ) {
$external = false;
$query = add_query_arg( $query, 'index.php' );
} else {
$index = false === strpos( $query, '?' ) ? strlen( $query ) : strpos( $query, '?' );
$front = substr( $query, 0, $index );
$external = $front != $this->index;
}
// "external" = it doesn't correspond to index.php.
if ( $external ) {
$this->add_external_rule( $regex, $query );
} else {
if ( 'bottom' === $after ) {
$this->extra_rules = array_merge( $this->extra_rules, array( $regex => $query ) );
} else {
$this->extra_rules_top = array_merge( $this->extra_rules_top, array( $regex => $query ) );
}
}
}
/**
* Adds a rewrite rule that doesn't correspond to index.php.
*
* @since 2.1.0
*
* @param string $regex Regular expression to match request against.
* @param string $query The corresponding query vars for this rewrite rule.
*/
public function add_external_rule( $regex, $query ) {
$this->non_wp_rules[ $regex ] = $query;
}
/**
* Adds an endpoint, like /trackback/.
*
* @since 2.1.0
* @since 3.9.0 $query_var parameter added.
* @since 4.3.0 Added support for skipping query var registration by passing `false` to `$query_var`.
*
* @see add_rewrite_endpoint() for full documentation.
* @global WP $wp Current WordPress environment instance.
*
* @param string $name Name of the endpoint.
* @param int $places Endpoint mask describing the places the endpoint should be added.
* @param string|bool $query_var Optional. Name of the corresponding query variable. Pass `false` to
* skip registering a query_var for this endpoint. Defaults to the
* value of `$name`.
*/
public function add_endpoint( $name, $places, $query_var = true ) {
global $wp;
// For backward compatibility, if null has explicitly been passed as `$query_var`, assume `true`.
if ( true === $query_var || null === $query_var ) {
$query_var = $name;
}
$this->endpoints[] = array( $places, $name, $query_var );
if ( $query_var ) {
$wp->add_query_var( $query_var );
}
}
/**
* Adds a new permalink structure.
*
* A permalink structure (permastruct) is an abstract definition of a set of rewrite rules;
* it is an easy way of expressing a set of regular expressions that rewrite to a set of
* query strings. The new permastruct is added to the WP_Rewrite::$extra_permastructs array.
*
* When the rewrite rules are built by WP_Rewrite::rewrite_rules(), all of these extra
* permastructs are passed to WP_Rewrite::generate_rewrite_rules() which transforms them
* into the regular expressions that many love to hate.
*
* The `$args` parameter gives you control over how WP_Rewrite::generate_rewrite_rules()
* works on the new permastruct.
*
* @since 2.5.0
*
* @param string $name Name for permalink structure.
* @param string $struct Permalink structure (e.g. category/%category%)
* @param array $args {
* Optional. Arguments for building rewrite rules based on the permalink structure.
* Default empty array.
*
* @type bool $with_front Whether the structure should be prepended with `WP_Rewrite::$front`.
* Default true.
* @type int $ep_mask The endpoint mask defining which endpoints are added to the structure.
* Accepts `EP_NONE`, `EP_PERMALINK`, `EP_ATTACHMENT`, `EP_DATE`, `EP_YEAR`,
* `EP_MONTH`, `EP_DAY`, `EP_ROOT`, `EP_COMMENTS`, `EP_SEARCH`, `EP_CATEGORIES`,
* `EP_TAGS`, `EP_AUTHORS`, `EP_PAGES`, `EP_ALL_ARCHIVES`, and `EP_ALL`.
* Default `EP_NONE`.
* @type bool $paged Whether archive pagination rules should be added for the structure.
* Default true.
* @type bool $feed Whether feed rewrite rules should be added for the structure. Default true.
* @type bool $forcomments Whether the feed rules should be a query for a comments feed. Default false.
* @type bool $walk_dirs Whether the 'directories' making up the structure should be walked over
* and rewrite rules built for each in-turn. Default true.
* @type bool $endpoints Whether endpoints should be applied to the generated rules. Default true.
* }
*/
public function add_permastruct( $name, $struct, $args = array() ) {
// Back-compat for the old parameters: $with_front and $ep_mask.
if ( ! is_array( $args ) ) {
$args = array( 'with_front' => $args );
}
if ( func_num_args() == 4 ) {
$args['ep_mask'] = func_get_arg( 3 );
}
$defaults = array(
'with_front' => true,
'ep_mask' => EP_NONE,
'paged' => true,
'feed' => true,
'forcomments' => false,
'walk_dirs' => true,
'endpoints' => true,
);
$args = array_intersect_key( $args, $defaults );
$args = wp_parse_args( $args, $defaults );
if ( $args['with_front'] ) {
$struct = $this->front . $struct;
} else {
$struct = $this->root . $struct;
}
$args['struct'] = $struct;
$this->extra_permastructs[ $name ] = $args;
}
/**
* Removes a permalink structure.
*
* @since 4.5.0
*
* @param string $name Name for permalink structure.
*/
public function remove_permastruct( $name ) {
unset( $this->extra_permastructs[ $name ] );
}
/**
* Removes rewrite rules and then recreate rewrite rules.
*
* Calls WP_Rewrite::wp_rewrite_rules() after removing the 'rewrite_rules' option.
* If the function named 'save_mod_rewrite_rules' exists, it will be called.
*
* @since 2.0.1
*
* @param bool $hard Whether to update .htaccess (hard flush) or just update rewrite_rules option (soft flush). Default is true (hard).
*/
public function flush_rules( $hard = true ) {
static $do_hard_later = null;
// Prevent this action from running before everyone has registered their rewrites.
if ( ! did_action( 'wp_loaded' ) ) {
add_action( 'wp_loaded', array( $this, 'flush_rules' ) );
$do_hard_later = ( isset( $do_hard_later ) ) ? $do_hard_later || $hard : $hard;
return;
}
if ( isset( $do_hard_later ) ) {
$hard = $do_hard_later;
unset( $do_hard_later );
}
update_option( 'rewrite_rules', '' );
$this->wp_rewrite_rules();
/**
* Filters whether a "hard" rewrite rule flush should be performed when requested.
*
* A "hard" flush updates .htaccess (Apache) or web.config (IIS).
*
* @since 3.7.0
*
* @param bool $hard Whether to flush rewrite rules "hard". Default true.
*/
if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) ) {
return;
}
if ( function_exists( 'save_mod_rewrite_rules' ) ) {
save_mod_rewrite_rules();
}
if ( function_exists( 'iis7_save_url_rewrite_rules' ) ) {
iis7_save_url_rewrite_rules();
}
}
/**
* Sets up the object's properties.
*
* The 'use_verbose_page_rules' object property will be set to true if the
* permalink structure begins with one of the following: '%postname%', '%category%',
* '%tag%', or '%author%'.
*
* @since 1.5.0
*/
public function init() {
$this->extra_rules = array();
$this->non_wp_rules = array();
$this->endpoints = array();
$this->permalink_structure = get_option( 'permalink_structure' );
$this->front = substr( $this->permalink_structure, 0, strpos( $this->permalink_structure, '%' ) );
$this->root = '';
if ( $this->using_index_permalinks() ) {
$this->root = $this->index . '/';
}
unset( $this->author_structure );
unset( $this->date_structure );
unset( $this->page_structure );
unset( $this->search_structure );
unset( $this->feed_structure );
unset( $this->comment_feed_structure );
$this->use_trailing_slashes = ( '/' === substr( $this->permalink_structure, -1, 1 ) );
// Enable generic rules for pages if permalink structure doesn't begin with a wildcard.
if ( preg_match( '/^[^%]*%(?:postname|category|tag|author)%/', $this->permalink_structure ) ) {
$this->use_verbose_page_rules = true;
} else {
$this->use_verbose_page_rules = false;
}
}
/**
* Sets the main permalink structure for the site.
*
* Will update the 'permalink_structure' option, if there is a difference
* between the current permalink structure and the parameter value. Calls
* WP_Rewrite::init() after the option is updated.
*
* Fires the {@see 'permalink_structure_changed'} action once the init call has
* processed passing the old and new values
*
* @since 1.5.0
*
* @param string $permalink_structure Permalink structure.
*/
public function set_permalink_structure( $permalink_structure ) {
if ( $permalink_structure != $this->permalink_structure ) {
$old_permalink_structure = $this->permalink_structure;
update_option( 'permalink_structure', $permalink_structure );
$this->init();
/**
* Fires after the permalink structure is updated.
*
* @since 2.8.0
*
* @param string $old_permalink_structure The previous permalink structure.
* @param string $permalink_structure The new permalink structure.
*/
do_action( 'permalink_structure_changed' false,
'post_tag' => false,
'post_format' => false,
);
} else {
/**
* Filters the post formats rewrite base.
*
* @since 3.1.0
*
* @param string $context Context of the rewrite base. Default 'type'.
*/
$post_format_base = apply_filters( 'post_format_rewrite_base', 'type' );
$rewrite = array(
'category' => array(
'hierarchical' => true,
'slug' => get_option( 'category_base' ) ? get_option( 'category_base' ) : 'category',
'with_front' => ! get_option( 'category_base' ) || $wp_rewrite->using_index_permalinks(),
'ep_mask' => EP_CATEGORIES,
),
'post_tag' => array(
'hierarchical' => false,
'slug' => get_option( 'tag_base' ) ? get_option( 'tag_base' ) : 'tag',
'with_front' => ! get_option( 'tag_base' ) || $wp_rewrite->using_index_permalinks(),
'ep_mask' => EP_TAGS,
),
'post_format' => $post_format_base ? array( 'slug' => $post_format_base ) : false,
);
}
register_taxonomy(
'category',
'post',
array(
'hierarchical' => true,
'query_var' => 'category_name',
'rewrite' => $rewrite['category'],
'public' => true,
'show_ui' => true,
'show_admin_column' => true,
'_builtin' => true,
'capabilities' => array(
'manage_terms' => 'manage_categories',
'edit_terms' => 'edit_categories',
'delete_terms' => 'delete_categories',
'assign_terms' => 'assign_categories',
),
'show_in_rest' => true,
'rest_base' => 'categories',
'rest_controller_class' => 'WP_REST_Terms_Controller',
)
);
register_taxonomy(
'post_tag',
'post',
array(
'hierarchical' => false,
'query_var' => 'tag',
'rewrite' => $rewrite['post_tag'],
'public' => true,
'show_ui' => true,
'show_admin_column' => true,
'_builtin' => true,
'capabilities' => array(
'manage_terms' => 'manage_post_tags',
'edit_terms' => 'edit_post_tags',
'delete_terms' => 'delete_post_tags',
'assign_terms' => 'assign_post_tags',
),
'show_in_rest' => true,
'rest_base' => 'tags',
'rest_controller_class' => 'WP_REST_Terms_Controller',
)
);
register_taxonomy(
'nav_menu',
'nav_menu_item',
array(
'public' => false,
'hierarchical' => false,
'labels' => array(
'name' => __( 'Navigation Menus' ),
'singular_name' => __( 'Navigation Menu' ),
),
'query_var' => false,
'rewrite' => false,
'show_ui' => false,
'_builtin' => true,
'show_in_nav_menus' => false,
)
);
register_taxonomy(
'link_category',
'link',
array(
'hierarchical' => false,
'labels' => array(
'name' => __( 'Link Categories' ),
'singular_name' => __( 'Link Category' ),
'search_items' => __( 'Search Link Categories' ),
'popular_items' => null,
'all_items' => __( 'All Link Categories' ),
'edit_item' => __( 'Edit Link Category' ),
'update_item' => __( 'Update Link Category' ),
'add_new_item' => __( 'Add New Link Category' ),
'new_item_name' => __( 'New Link Category Name' ),
'separate_items_with_commas' => null,
'add_or_remove_items' => null,
'choose_from_most_used' => null,
'back_to_items' => __( 'ā Back to Link Categories' ),
),
'capabilities' => array(
'manage_terms' => 'manage_links',
'edit_terms' => 'manage_links',
'delete_terms' => 'manage_links',
'assign_terms' => 'manage_links',
),
'query_var' => false,
'rewrite' => false,
'public' => false,
'show_ui' => true,
'_builtin' => true,
)
);
register_taxonomy(
'post_format',
'post',
array(
'public' => true,
'hierarchical' => false,
'labels' => array(
'name' => _x( 'Formats', 'post format' ),
'singular_name' => _x( 'Format', 'post format' ),
),
'query_var' => true,
'rewrite' => $rewrite['post_format'],
'show_ui' => false,
'_builtin' => true,
'show_in_nav_menus' => current_theme_supports( 'post-formats' ),
)
);
}
/**
* Retrieves a list of registered taxonomy names or objects.
*
* @since 3.0.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param array $args Optional. An array of `key => value` arguments to match against the taxonomy objects.
* Default empty array.
* @param string $output Optional. The type of output to return in the array. Accepts either taxonomy 'names'
* or 'objects'. Default 'names'.
* @param string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
* one element from the array needs to match; 'and' means all elements must match.
* Default 'and'.
* @return string[]|WP_Taxonomy[] An array of taxonomy names or objects.
*/
function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' ) {
global $wp_taxonomies;
$field = ( 'names' === $output ) ? 'name' : false;
return wp_filter_object_list( $wp_taxonomies, $args, $operator, $field );
}
/**
* Return the names or objects of the taxonomies which are registered for the requested object or object type, such as
* a post object or post type name.
*
* Example:
*
* $taxonomies = get_object_taxonomies( 'post' );
*
* This results in:
*
* Array( 'category', 'post_tag' )
*
* @since 2.3.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param string|string[]|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
* @param string $output Optional. The type of output to return in the array. Accepts either
* 'names' or 'objects'. Default 'names'.
* @return string[]|WP_Taxonomy[] The names or objects of all taxonomies of `$object_type`.
*/
function get_object_taxonomies( $object, $output = 'names' ) {
global $wp_taxonomies;
if ( is_object( $object ) ) {
if ( 'attachment' === $object->post_type ) {
return get_attachment_taxonomies( $object, $output );
}
$object = $object->post_type;
}
$object = (array) $object;
$taxonomies = array();
foreach ( (array) $wp_taxonomies as $tax_name => $tax_obj ) {
if ( array_intersect( $object, (array) $tax_obj->object_type ) ) {
if ( 'names' === $output ) {
$taxonomies[] = $tax_name;
} else {
$taxonomies[ $tax_name ] = $tax_obj;
}
}
}
return $taxonomies;
}
/**
* Retrieves the taxonomy object of $taxonomy.
*
* The get_taxonomy function will first check that the parameter string given
* is a taxonomy object and if it is, it will return it.
*
* @since 2.3.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param string $taxonomy Name of taxonomy object to return.
* @return WP_Taxonomy|false The Taxonomy Object or false if $taxonomy doesn't exist.
*/
function get_taxonomy( $taxonomy ) {
global $wp_taxonomies;
if ( ! taxonomy_exists( $taxonomy ) ) {
return false;
}
return $wp_taxonomies[ $taxonomy ];
}
/**
* Determines whether the taxonomy name exists.
*
* Formerly is_taxonomy(), introduced in 2.3.0.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 3.0.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param string $taxonomy Name of taxonomy object.
* @return bool Whether the taxonomy exists.
*/
function taxonomy_exists( $taxonomy ) {
global $wp_taxonomies;
return isset( $wp_taxonomies[ $taxonomy ] );
}
/**
* Determines whether the taxonomy object is hierarchical.
*
* Checks to make sure that the taxonomy is an object first. Then Gets the
* object, and finally returns the hierarchical value in the object.
*
* A false return value might also mean that the taxonomy does not exist.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 2.3.0
*
* @param string $taxonomy Name of taxonomy object.
* @return bool Whether the taxonomy is hierarchical.
*/
function is_taxonomy_hierarchical( $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return false;
}
$taxonomy = get_taxonomy( $taxonomy );
return $taxonomy->hierarchical;
}
/**
* Creates or modifies a taxonomy object.
*
* Note: Do not use before the {@see 'init'} hook.
*
* A simple function for creating or modifying a taxonomy object based on
* the parameters given. If modifying an existing taxonomy object, note
* that the `$object_type` value from the original registration will be
* overwritten.
*
* @since 2.3.0
* @since 4.2.0 Introduced `show_in_quick_edit` argument.
* @since 4.4.0 The `show_ui` argument is now enforced on the term editing screen.
* @since 4.4.0 The `public` argument now controls whether the taxonomy can be queried on the front end.
* @since 4.5.0 Introduced `publicly_queryable` argument.
* @since 4.7.0 Introduced `show_in_rest`, 'rest_base' and 'rest_controller_class'
* arguments to register the Taxonomy in REST API.
* @since 5.1.0 Introduced `meta_box_sanitize_cb` argument.
* @since 5.4.0 Added the registered taxonomy object as a return value.
* @since 5.5.0 Introduced `default_term` argument.
*
* @global array $wp_taxonomies Registered taxonomies.
*
* @param string $taxonomy Taxonomy key, must not exceed 32 characters.
* @param array|string $object_type Object type or array of object types with which the taxonomy should be associated.
* @param array|string $args {
* Optional. Array or query string of arguments for registering a taxonomy.
*
* @type array $labels An array of labels for this taxonomy. By default, Tag labels are
* used for non-hierarchical taxonomies, and Category labels are used
* for hierarchical taxonomies. See accepted values in
* get_taxonomy_labels(). Default empty array.
* @type string $description A short descriptive summary of what the taxonomy is for. Default empty.
* @type bool $public Whether a taxonomy is intended for use publicly either via
* the admin interface or by front-end users. The default settings
* of `$publicly_queryable`, `$show_ui`, and `$show_in_nav_menus`
* are inherited from `$public`.
* @type bool $publicly_queryable Whether the taxonomy is publicly queryable.
* If not set, the default is inherited from `$public`
* @type bool $hierarchical Whether the taxonomy is hierarchical. Default false.
* @type bool $show_ui Whether to generate and allow a UI for managing terms in this taxonomy in
* the admin. If not set, the default is inherited from `$public`
* (default true).
* @type bool $show_in_menu Whether to show the taxonomy in the admin menu. If true, the taxonomy is
* shown as a submenu of the object type menu. If false, no menu is shown.
* `$show_ui` must be true. If not set, default is inherited from `$show_ui`
* (default true).
* @type bool $show_in_nav_menus Makes this taxonomy available for selection in navigation menus. If not
* set, the default is inherited from `$public` (default true).
* @type bool $show_in_rest Whether to include the taxonomy in the REST API. Set this to true
* for the taxonomy to be available in the block editor.
* @type string $rest_base To change the base url of REST API route. Default is $taxonomy.
* @type string $rest_controller_class REST API Controller class name. Default is 'WP_REST_Terms_Controller'.
* @type bool $show_tagcloud Whether to list the taxonomy in the Tag Cloud Widget controls. If not set,
* the default is inherited from `$show_ui` (default true).
* @type bool $show_in_quick_edit Whether to show the taxonomy in the quick/bulk edit panel. It not set,
* the default is inherited from `$show_ui` (default true).
* @type bool $show_admin_column Whether to display a column for the taxonomy on its post type listing
* screens. Default false.
* @type bool|callable $meta_box_cb Provide a callback function for the meta box display. If not set,
* post_categories_meta_box() is used for hierarchical taxonomies, and
* post_tags_meta_box() is used for non-hierarchical. If false, no meta
* box is shown.
* @type callable $meta_box_sanitize_cb Callback function for sanitizing taxonomy data saved from a meta
* box. If no callback is defined, an appropriate one is determined
* based on the value of `$meta_box_cb`.
* @type array $capabilities {
* Array of capabilities for this taxonomy.
*
* @type string $manage_terms Default 'manage_categories'.
* @type string $edit_terms Default 'manage_categories'.
* @type string $delete_terms Default 'manage_categories'.
* @type string $assign_terms Default 'edit_posts'.
* }
* @type bool|array $rewrite {
* Triggers the handling of rewrites for this taxonomy. Default true, using $taxonomy as slug. To prevent
* rewrite, set to false. To specify rewrite rules, an array can be passed with any of these keys:
*
* @type string $slug Customize the permastruct slug. Default `$taxonomy` key.
* @type bool $with_front Should the permastruct be prepended with WP_Rewrite::$front. Default true.
* @type bool $hierarchical Either hierarchical rewrite tag or not. Default false.
* @type int $ep_mask Assign an endpoint mask. Default `EP_NONE`.
* }
* @type string|bool $query_var Sets the query var key for this taxonomy. Default `$taxonomy` key. If
* false, a taxonomy cannot be loaded at `?{query_var}={term_slug}`. If a
* string, the query `?{query_var}={term_slug}` will be valid.
* @type callable $update_count_callback Works much like a hook, in that it will be called when the count is
* updated. Default _update_post_term_count() for taxonomies attached
* to post types, which confirms that the objects are published before
* counting them. Default _update_generic_term_count() for taxonomies
* attached to other object types, such as users.
* @type string|array $default_term {
* Default term to be used for the taxonomy.
*
* @type string $name Name of default term.
* @type string $slug Slug for default term. Default empty.
* @type string $description Description for default term. Default empty.
* }
* @type bool $_builtin This taxonomy is a "built-in" taxonomy. INTERNAL USE ONLY!
* Default false.
* }
* @return WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure.
*/
function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
global $wp_taxonomies;
if ( ! is_array( $wp_taxonomies ) ) {
$wp_taxonomies = array();
}
$args = wp_parse_args( $args );
if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) {
_doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' );
return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) );
}
$taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args );
$taxonomy_object->add_rewrite_rules();
$wp_taxonomies[ $taxonomy ] = $taxonomy_object;
$taxonomy_object->add_hooks();
// Add default term.
if ( ! empty( $taxonomy_object->default_term ) ) {
$term = term_exists( $taxonomy_object->default_term['name'], $taxonomy );
if ( $term ) {
update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
} else {
$term = wp_insert_term(
$taxonomy_object->default_term['name'],
$taxonomy,
array(
'slug' => sanitize_title( $taxonomy_object->default_term['slug'] ),
'description' => $taxonomy_object->default_term['description'],
)
);
// Update `term_id` in options.
if ( ! is_wp_error( $term ) ) {
update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
}
}
}
/**
* Fires after a taxonomy is registered.
*
* @since 3.3.0
*
* @param string $taxonomy Taxonomy slug.
* @param array|string $object_type Object type or array of object types.
* @param array $args Array of taxonomy registration arguments.
*/
do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );
return $taxonomy_object;
}
/**
* Unregisters a taxonomy.
*
* Can not be used to unregister built-in taxonomies.
*
* @since 4.5.0
*
* @global WP $wp Current WordPress environment instance.
* @global array $wp_taxonomies List of taxonomies.
*
* @param string $taxonomy Taxonomy name.
* @return bool|WP_Error True on success, WP_Error on failure or if the taxonomy doesn't exist.
*/
function unregister_taxonomy( $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
$taxonomy_object = get_taxonomy( $taxonomy );
// Do not allow unregistering internal taxonomies.
if ( $taxonomy_object->_builtin ) {
return new WP_Error( 'invalid_taxonomy', __( 'Unregistering a built-in taxonomy is not allowed.' ) );
}
global $wp_taxonomies;
$taxonomy_object->remove_rewrite_rules();
$taxonomy_object->remove_hooks();
// Remove custom taxonomy default term option.
if ( ! empty( $taxonomy_object->default_term ) ) {
delete_option( 'default_term_' . $taxonomy_object->name );
}
// Remove the taxonomy.
unset( $wp_taxonomies[ $taxonomy ] );
/**
* Fires after a taxonomy is unregistered.
*
* @since 4.5.0
*
* @param string $taxonomy Taxonomy name.
*/
do_action( 'unregistered_taxonomy', $taxonomy );
return true;
}
/**
* Builds an object with all taxonomy labels out of a taxonomy object.
*
* @since 3.0.0
* @since 4.3.0 Added the `no_terms` label.
* @since 4.4.0 Added the `items_list_navigation` and `items_list` labels.
* @since 4.9.0 Added the `most_used` and `back_to_items` labels.
*
* @param WP_Taxonomy $tax Taxonomy object.
* @return object {
* Taxonomy labels object. The first default value is for non-hierarchical taxonomies
* (like tags) and the second one is for hierarchical taxonomies (like categories).
*
* @type string $name General name for the taxonomy, usually plural. The same
* as and overridden by `$tax->label`. Default 'Tags'/'Categories'.
* @type string $singular_name Name for one object of this taxonomy. Default 'Tag'/'Category'.
* @type string $search_items Default 'Search Tags'/'Search Categories'.
* @type string $popular_items This label is only used for non-hierarchical taxonomies.
* Default 'Popular Tags'.
* @type string $all_items Default 'All Tags'/'All Categories'.
* @type string $parent_item This label is only used for hierarchical taxonomies. Default
* 'Parent Category'.
* @type string $parent_item_colon The same as `parent_item`, but with colon `:` in the end.
* @type string $edit_item Default 'Edit Tag'/'Edit Category'.
* @type string $view_item Default 'View Tag'/'View Category'.
* @type string $update_item Default 'Update Tag'/'Update Category'.
* @type string $add_new_item Default 'Add New Tag'/'Add New Category'.
* @type string $new_item_name Default 'New Tag Name'/'New Category Name'.
* @type string $separate_items_with_commas This label is only used for non-hierarchical taxonomies. Default
* 'Separate tags with commas', used in the meta box.
* @type string $add_or_remove_items This label is only used for non-hierarchical taxonomies. Default
* 'Add or remove tags', used in the meta box when JavaScript
* is disabled.
* @type string $choose_from_most_used This label is only used on non-hierarchical taxonomies. Default
* 'Choose from the most used tags', used in the meta box.
* @type string $not_found Default 'No tags found'/'No categories found', used in
* the meta box and taxonomy list table.
* @type string $no_terms Default 'No tags'/'No categories', used in the posts and media
* list tables.
* @type string $items_list_navigation Label for the table pagination hidden heading.
* @type string $items_list Label for the table hidden heading.
* @type string $most_used Title for the Most Used tab. Default 'Most Used'.
* @type string $back_to_items Label displayed after a term has been updated.
* }
*/
function get_taxonomy_labels( $tax ) {
$tax->labels = (array) $tax->labels;
if ( isset( $tax->helps ) && empty( $tax->labels['separate_items_with_commas'] ) ) {
$tax->labels['separate_items_with_commas'] = $tax->helps;
}
if ( isset( $tax->no_tagcloud ) && empty( $tax->labels['not_found'] ) ) {
$tax->labels['not_found'] = $tax->no_tagcloud;
}
$nohier_vs_hier_defaults = array(
'name' => array( _x( 'Tags', 'taxonomy general name' ), _x( 'Categories', 'taxonomy general name' ) ),
'singular_name' => array( _x( 'Tag', 'taxonomy singular name' ), _x( 'Category', 'taxonomy singular name' ) ),
'search_items' => array( __( 'Search Tags' ), __( 'Search Categories' ) ),
'popular_items' => array( __( 'Popular Tags' ), null ),
'all_items' => array( __( 'All Tags' ), __( 'All Categories' ) ),
'parent_item' => array( null, __( 'Parent Category' ) ),
'parent_item_colon' => array( null, __( 'Parent Category:' ) ),
'edit_item' => array( __( 'Edit Tag' ), __( 'Edit Category' ) ),
'view_item' => array( __( 'View Tag' ), __( 'View Category' ) ),
'update_item' => array( __( 'Update Tag' ), __( 'Update Category' ) ),
'add_new_item' => array( __( 'Add New Tag' ), __( 'Add New Category' ) ),
'new_item_name' => array( __( 'New Tag Name' ), __( 'New Category Name' ) ),
'separate_items_with_commas' => array( __( 'Separate tags with commas' ), null ),
'add_or_remove_items' => array( __( 'Add or remove tags' ), null ),
'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ),
'not_found' => array( __( 'No tags found.' ), __( 'No categories found.' ) ),
'no_terms' => array( __( 'No tags' ), __( 'No categories' ) ),
'items_list_navigation' => array( __( 'Tags list navigation' ), __( 'Categories list navigation' ) ),
'items_list' => array( __( 'Tags list' ), __( 'Categories list' ) ),
/* translators: Tab heading when selecting from the most used terms. */
'most_used' => array( _x( 'Most Used', 'tags' ), _x( 'Most Used', 'categories' ) ),
'back_to_items' => array( __( 'ā Back to Tags' ), __( 'ā Back to Categories' ) ),
);
$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
$labels = _get_custom_object_labels( $tax, $nohier_vs_hier_defaults );
$taxonomy = $tax->name;
$default_labels = clone $labels;
/**
* Filters the labels of a specific taxonomy.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
*
* @since 4.4.0
*
* @see get_taxonomy_labels() for the full list of taxonomy labels.
*
* @param object $labels Object with labels for the taxonomy as member variables.
*/
$labels = apply_filters( "taxonomy_labels_{$taxonomy}", $labels );
// Ensure that the filtered labels contain all required default values.
$labels = (object) array_merge( (array) $default_labels, (array) $labels );
return $labels;
}
/**
* Add an already registered taxonomy to an object type.
*
* @since 3.0.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param string $taxonomy Name of taxonomy object.
* @param string $object_type Name of the object type.
* @return bool True if successful, false if not.
*/
function register_taxonomy_for_object_type( $taxonomy, $object_type ) {
global $wp_taxonomies;
if ( ! isset( $wp_taxonomies[ $taxonomy ] ) ) {
return false;
}
if ( ! get_post_type_object( $object_type ) ) {
return false;
}
if ( ! in_array( $object_type, $wp_taxonomies[ $taxonomy ]->object_type, true ) ) {
$wp_taxonomies[ $taxonomy ]->object_type[] = $object_type;
}
// Filter out empties.
$wp_taxonomies[ $taxonomy ]->object_type = array_filter( $wp_taxonomies[ $taxonomy ]->object_type );
/**
* Fires after a taxonomy is registered for an object type.
*
* @since 5.1.0
*
* @param string $taxonomy Taxonomy name.
* @param string $object_type Name of the object type.
*/
do_action( 'registered_taxonomy_for_object_type', $taxonomy, $object_type );
return true;
}
/**
* Remove an already registered taxonomy from an object type.
*
* @since 3.7.0
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param string $taxonomy Name of taxonomy object.
* @param string $object_type Name of the object type.
* @return bool True if successful, false if not.
*/
function unregister_taxonomy_for_object_type( $taxonomy, $object_type ) {
global $wp_taxonomies;
if ( ! isset( $wp_taxonomies[ $taxonomy ] ) ) {
return false;
}
if ( ! get_post_type_object( $object_type ) ) {
return false;
}
$key = array_search( $object_type, $wp_taxonomies[ $taxonomy ]->object_type, true );
if ( false === $key ) {
return false;
}
unset( $wp_taxonomies[ $taxonomy ]->object_type[ $key ] );
/**
* Fires after a taxonomy is unregistered for an object type.
*
* @since 5.1.0
*
* @param string $taxonomy Taxonomy name.
* @param string $object_type Name of the object type.
*/
do_action( 'unregistered_taxonomy_for_object_type', $taxonomy, $object_type );
return true;
}
//
// Term API.
//
/**
* Retrieve object_ids of valid taxonomy and term.
*
* The strings of $taxonomies must exist before this function will continue. On
* failure of finding a valid taxonomy, it will return an WP_Error class, kind
* of like Exceptions in PHP 5, except you can't catch them. Even so, you can
* still test for the WP_Error class and get the error message.
*
* The $terms aren't checked the same as $taxonomies, but still need to exist
* for $object_ids to be returned.
*
* It is possible to change the order that object_ids is returned by either
* using PHP sort family functions or using the database by using $args with
* either ASC or DESC array. The value should be in the key named 'order'.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int|array $term_ids Term ID or array of term IDs of terms that will be used.
* @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
* @param array|string $args Change the order of the object_ids, either ASC or DESC.
* @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success.
* the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
*/
function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
global $wpdb;
if ( ! is_array( $term_ids ) ) {
$term_ids = array( $term_ids );
}
if ( ! is_array( $taxonomies ) ) {
$taxonomies = array( $taxonomies );
}
foreach ( (array) $taxonomies as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
}
$defaults = array( 'order' => 'ASC' );
$args = wp_parse_args( $args, $defaults );
$order = ( 'desc' === strtolower( $args['order'] ) ) ? 'DESC' : 'ASC';
$term_ids = array_map( 'intval', $term_ids );
$taxonomies = "'" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "'";
$term_ids = "'" . implode( "', '", $term_ids ) . "'";
$sql = "SELECT tr.object_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tt.taxonomy IN ($taxonomies) AND tt.term_id IN ($term_ids) ORDER BY tr.object_id $order";
$last_changed = wp_cache_get_last_changed( 'terms' );
$cache_key = 'get_objects_in_term:' . md5( $sql ) . ":$last_changed";
$cache = wp_cache_get( $cache_key, 'terms' );
if ( false === $cache ) {
$object_ids = $wpdb->get_col( $sql );
wp_cache_set( $cache_key, $object_ids, 'terms' );
} else {
$object_ids = (array) $cache;
}
if ( ! $object_ids ) {
return array();
}
return $object_ids;
}
/**
* Given a taxonomy query, generates SQL to be appended to a main query.
*
* @since 3.1.0
*
* @see WP_Tax_Query
*
* @param array $tax_query A compact tax query
* @param string $primary_table
* @param string $primary_id_column
* @return array
*/
function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
$tax_query_obj = new WP_Tax_Query( $tax_query );
return $tax_query_obj->get_sql( $primary_table, $primary_id_column );
}
/**
* Get all Term data from database by Term ID.
*
* The usage of the get_term function is to apply filters to a term object. It
* is possible to get a term object from the database before applying the
* filters.
*
* $term ID must be part of $taxonomy, to get from the database. Failure, might
* be able to be captured by the hooks. Failure would be the same value as $wpdb
* returns for the get_row method.
*
* There are two hooks, one is specifically for each term, named 'get_term', and
* the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the
* term object, and the taxonomy name as parameters. Both hooks are expected to
* return a Term object.
*
* {@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name.
* Must return term object. Used in get_term() as a catch-all filter for every
* $term.
*
* {@see 'get_$taxonomy'} hook - Takes two parameters the term Object and the taxonomy
* name. Must return term object. $taxonomy will be the taxonomy name, so for
* example, if 'category', it would be 'get_category' as the filter name. Useful
* for custom taxonomies or plugging into default taxonomies.
*
* @todo Better formatting for DocBlock
*
* @since 2.3.0
* @since 4.4.0 Converted to return a WP_Term object if `$output` is `OBJECT`.
* The `$taxonomy` parameter was made optional.
*
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param int|WP_Term|object $term If integer, term data will be fetched from the database,
* or from the cache if available.
* If stdClass object (as in the results of a database query),
* will apply filters and return a `WP_Term` object with the `$term` data.
* If `WP_Term`, will return `$term`.
* @param string $taxonomy Optional. Taxonomy name that `$term` is part of.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Term object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize term fields. Default 'raw'.
* @return WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
* WP_Error if `$taxonomy` does not exist. Null for miscellaneous failure.
*/
function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
if ( empty( $term ) ) {
return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
}
if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
if ( $term instanceof WP_Term ) {
$_term = $term;
} elseif ( is_object( $term ) ) {
if ( empty( $term->filter ) || 'raw' === $term->filter ) {
$_term = sanitize_term( $term, $taxonomy, 'raw' );
$_term = new WP_Term( $_term );
} else {
$_term = WP_Term::get_instance( $term->term_id );
}
} else {
$_term = WP_Term::get_instance( $term, $taxonomy );
}
if ( is_wp_error( $_term ) ) {
return $_term;
} elseif ( ! $_term ) {
return null;
}
// Ensure for filters that this is not empty.
$taxonomy = $_term->taxonomy;
/**
* Filters a taxonomy term object.
*
* @since 2.3.0
* @since 4.4.0 `$_term` is now a `WP_Term` object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
*/
$_term = apply_filters( 'get_term', $_term, $taxonomy );
/**
* Filters a taxonomy term object.
*
* The dynamic portion of the filter name, `$taxonomy`, refers
* to the slug of the term's taxonomy.
*
* @since 2.3.0
* @since 4.4.0 `$_term` is now a `WP_Term` object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
*/
$_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );
// Bail if a filter callback has changed the type of the `$_term` object.
if ( ! ( $_term instanceof WP_Term ) ) {
return $_term;
}
// Sanitize term, according to the specified filter.
$_term->filter( $filter );
if ( ARRAY_A === $output ) {
return $_term->to_array();
} elseif ( ARRAY_N === $output ) {
return array_values( $_term->to_array() );
}
return $_term;
}
/**
* Get all Term data from database by Term field and data.
*
* Warning: $value is not escaped for 'name' $field. You must do it yourself, if
* required.
*
* The default $field is 'id', therefore it is possible to also use null for
* field, but not recommended that you do so.
*
* If $value does not exist, the return value will be false. If $taxonomy exists
* and $field and $value combinations exist, the Term will be returned.
*
* This function will always return the first term that matches the `$field`-
* `$value`-`$taxonomy` combination specified in the parameters. If your query
* is likely to match more than one term (as is likely to be the case when
* `$field` is 'name', for example), consider using get_terms() instead; that
* way, you will get all matching terms, and can provide your own logic for
* deciding which one was intended.
*
* @todo Better formatting for DocBlock.
*
* @since 2.3.0
* @since 4.4.0 `$taxonomy` is optional if `$field` is 'term_taxonomy_id'. Converted to return
* a WP_Term object if `$output` is `OBJECT`.
* @since 5.5.0 Added 'ID' as an alias of 'id' for the `$field` parameter.
*
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param string $field Either 'slug', 'name', 'id' or 'ID' (term_id), or 'term_taxonomy_id'.
* @param string|int $value Search for this term value.
* @param string $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Term object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize term fields. Default 'raw'.
* @return WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
* False if `$taxonomy` does not exist or `$term` was not found.
*/
function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
// 'term_taxonomy_id' lookups don't require taxonomy checks.
if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) {
return false;
}
// No need to perform a query for empty 'slug' or 'name'.
if ( 'slug' === $field || 'name' === $field ) {
$value = (string) $value;
if ( 0 === strlen( $value ) ) {
return false;
}
}
if ( 'id' === $field || 'ID' === $field || 'term_id' === $field ) {
$term = get_term( (int) $value, $taxonomy, $output, $filter );
if ( is_wp_error( $term ) || null === $term ) {
$term = false;
}
return $term;
}
$args = array(
'get' => 'all',
'number' => 1,
'taxonomy' => $taxonomy,
'update_term_meta_cache' => false,
'orderby' => 'none',
'suppress_filter' => true,
);
switch ( $field ) {
case 'slug':
$args['slug'] = $value;
break;
case 'name':
$args['name'] = $value;
break;
case 'term_taxonomy_id':
$args['term_taxonomy_id'] = $value;
unset( $args['taxonomy'] );
break;
default:
return false;
}
$terms = get_terms( $args );
if ( is_wp_error( $terms ) || empty( $terms ) ) {
return false;
}
$term = array_shift( $terms );
// In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the DB.
if ( 'term_taxonomy_id' === $field ) {
$taxonomy = $term->taxonomy;
}
return get_term( $term, $taxonomy, $output, $filter );
}
/**
* Merge all term children into a single array of their IDs.
*
* This recursive function will merge all of the children of $term into the same
* array of term IDs. Only useful for taxonomies which are hierarchical.
*
* Will return an empty array if $term does not exist in $taxonomy.
*
* @since 2.3.0
*
* @param int $term_id ID of Term to get children.
* @param string $taxonomy Taxonomy Name.
* @return array|WP_Error List of Term IDs. WP_Error returned if `$taxonomy` does not exist.
*/
function get_term_children( $term_id, $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
$term_id = intval( $term_id );
$terms = _get_term_hierarchy( $taxonomy );
if ( ! isset( $terms[ $term_id ] ) ) {
return array();
}
$children = $terms[ $term_id ];
foreach ( (array) $terms[ $term_id ] as $child ) {
if ( $term_id === $child ) {
continue;
}
if ( isset( $terms[ $child ] ) ) {
$children = array_merge( $children, get_term_children( $child, $taxonomy ) );
}
}
return $children;
}
/**
* Get sanitized Term field.
*
* The function is for contextual reasons and for simplicity of usage.
*
* @since 2.3.0
* @since 4.4.0 The `$taxonomy` parameter was made optional. `$term` can also now accept a WP_Term object.
*
* @see sanitize_term_field()
*
* @param string $field Term field to fetch.
* @param int|WP_Term $term Term ID or object.
* @param string $taxonomy Optional. Taxonomy Name. Default empty.
* @param string $context Optional. How to sanitize term fields. Look at sanitize_term_field() for available options.
* Default 'display'.
* @return string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
*/
function get_term_field( $field, $term, $taxonomy = '', $context = 'display' ) {
$term = get_term( $term, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( ! is_object( $term ) ) {
return '';
}
if ( ! isset( $term->$field ) ) {
return '';
}
return sanitize_term_field( $field, $term->$field, $term->term_id, $term->taxonomy, $context );
}
/**
* Sanitizes Term for editing.
*
* Return value is sanitize_term() and usage is for sanitizing the term for
* editing. Function is for contextual and simplicity.
*
* @since 2.3.0
*
* @param int|object $id Term ID or object.
* @param string $taxonomy Taxonomy name.
* @return string|int|null|WP_Error Will return empty string if $term is not an object.
*/
function get_term_to_edit( $id, $taxonomy ) {
$term = get_term( $id, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( ! is_object( $term ) ) {
return '';
}
return sanitize_term( $term, $taxonomy, 'edit' );
}
/**
* Retrieve the terms in a given taxonomy or list of taxonomies.
*
* You can fully inject any customizations to the query before it is sent, as
* well as control the output with a filter.
*
* The {@see 'get_terms'} filter will be called when the cache has the term and will
* pass the found term along with the array of $taxonomies and array of $args.
* This filter is also called before the array of terms is passed and will pass
* the array of terms, along with the $taxonomies and $args.
*
* The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with
* the $args.
*
* The {@see 'get_terms_orderby'} filter passes the `ORDER BY` clause for the query
* along with the $args array.
*
* Prior to 4.5.0, the first parameter of `get_terms()` was a taxonomy or list of taxonomies:
*
* $terms = get_terms( 'post_tag', array(
* 'hide_empty' => false,
* ) );
*
* Since 4.5.0, taxonomies should be passed via the 'taxonomy' argument in the `$args` array:
*
* $terms = get_terms( array(
* 'taxonomy' => 'post_tag',
* 'hide_empty' => false,
* ) );
*
* @since 2.3.0
* @since 4.2.0 Introduced 'name' and 'childless' parameters.
* @since 4.4.0 Introduced the ability to pass 'term_id' as an alias of 'id' for the `orderby` parameter.
* Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return
* a list of WP_Term objects.
* @since 4.5.0 Changed the function signature so that the `$args` array can be provided as the first parameter.
* Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata.
* @since 4.8.0 Introduced 'suppress_filter' parameter.
*
* @internal The `$deprecated` parameter is parsed for backward compatibility only.
*
* @param array|string $args Optional. Array or string of arguments. See WP_Term_Query::__construct()
* for information on accepted arguments. Default empty.
* @param array|string $deprecated Argument array, when using the legacy function parameter format. If present,
* this parameter will be interpreted as `$args`, and the first function parameter
* will be parsed as a taxonomy or array of taxonomies.
* @return WP_Term[]|int|WP_Error Array of WP_Term instances, a count thereof,
* or WP_Error if any of the taxonomies do not exist.
*/
function get_terms( $args = array(), $deprecated = '' ) {
$term_query = new WP_Term_Query();
$defaults = array(
'suppress_filter' => false,
);
/*
* Legacy argument format ($taxonomy, $args) takes precedence.
*
* We detect legacy argument format by checking if
* (a) a second non-empty parameter is passed, or
* (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies)
*/
$_args = wp_parse_args( $args );
$key_intersect = array_intersect_key( $term_query->query_var_defaults, (array) $_args );
$do_legacy_args = $deprecated || empty( $key_intersect );
if ( $do_legacy_args ) {
$taxonomies = (array) $args;
$args = wp_parse_args( $deprecated, $defaults );
$args['taxonomy'] = $taxonomies;
} else {
$args = wp_parse_args( $args, $defaults );
if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) {
$args['taxonomy'] = (array) $args['taxonomy'];
}
}
if ( ! empty( $args['taxonomy'] ) ) {
foreach ( $args['taxonomy'] as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
}
}
// Don't pass suppress_filter to WP_Term_Query.
$suppress_filter = $args['suppress_filter'];
unset( $args['suppress_filter'] );
$terms = $term_query->query( $args );
// Count queries are not filtered, for legacy reasons.
if ( ! is_array( $terms ) ) {
return $terms;
}
if ( $suppress_filter ) {
return $terms;
}
/**
* Filters the found terms.
*
* @since 2.3.0
* @since 4.6.0 Added the `$term_query` parameter.
*
* @param array $terms Array of found terms.
* @param array $taxonomies An array of taxonomies.
* @param array $args An array of get_terms() arguments.
* @param WP_Term_Query $term_query The WP_Term_Query object.
*/
return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );
}
/**
* Adds metadata to a term.
*
* @since 4.4.0
*
* @param int $term_id Term ID.
* @param string $meta_key Metadata name.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. Whether the same key should not be added.
* Default false.
* @return int|false|WP_Error Meta ID on success, false on failure.
* WP_Error when term_id is ambiguous between taxonomies.
*/
function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) {
if ( wp_term_is_shared( $term_id ) ) {
return new WP_Error( 'ambiguous_term_id', __( 'Term meta cannot be added to terms that are shared between taxonomies.' ), $term_id );
}
return add_metadata( 'term', $term_id, $meta_key, $meta_value, $unique );
}
/**
* Removes metadata matching criteria from a term.
*
* @since 4.4.0
*
* @param int $term_id Term ID.
* @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. If provided,
* rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure.
*/
function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) {
return delete_metadata( 'term', $term_id, $meta_key, $meta_value );
}
/**
* Retrieves metadata for a term.
*
* @since 4.4.0
*
* @param int $term_id Term ID.
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys. Default empty.
* @param bool $single Optional. Whether to return a single value.
* This parameter has no effect if $key is not specified.
* Default false.
* @return mixed An array if $single is false. The value of the meta field
* if $single is true. False for an invalid $term_id.
*/
function get_term_meta( $term_id, $key = '', $single = false ) {
return get_metadata( 'term', $term_id, $key, $single );
}
/**
* Updates term metadata.
*
* Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID.
*
* If the meta field for the term does not exist, it will be added.
*
* @since 4.4.0
*
* @param int $term_id Term ID.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating.
* If specified, only update existing metadata entries with
* this value. Otherwise, update all entries. Default empty.
* @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
* false on failure or if the value passed to the function
* is the same as the one that is already in the database.
* WP_Error when term_id is ambiguous between taxonomies.
*/
function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) {
if ( wp_term_is_shared( $term_id ) ) {
return new WP_Error( 'ambiguous_term_id', __( 'Term meta cannot be added to terms that are shared between taxonomies.' ), $term_id );
}
return update_metadata( 'term', $term_id, $meta_key, $meta_value, $prev_value );
}
/**
* Updates metadata cache for list of term IDs.
*
* Performs SQL query to retrieve all metadata for the terms matching `$term_ids` and stores them in the cache.
* Subsequent calls to `get_term_meta()` will not need to query the database.
*
* @since 4.4.0
*
* @param array $term_ids List of term IDs.
* @return array|false An array of metadata on success, false if there is nothing to update.
*/
function update_termmeta_cache( $term_ids ) {
return update_meta_cache( 'term', $term_ids );
}
/**
* Get all meta data, including meta IDs, for the given term ID.
*
* @since 4.9.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $term_id Term ID.
* @return array|false Array with meta data, or false when the meta table is not installed.
*/
function has_term_meta( $term_id ) {
$check = wp_check_term_meta_support_prefilter( null );
if ( null !== $check ) {
return $check;
}
global $wpdb;
return $wpdb->get_results( $wpdb->prepare( "SELECT meta_key, meta_value, meta_id, term_id FROM $wpdb->termmeta WHERE term_id = %d ORDER BY meta_key,meta_id", $term_id ), ARRAY_A );
}
/**
* Registers a meta key for terms.
*
* @since 4.9.8
*
* @param string $taxonomy Taxonomy to register a meta key for. Pass an empty string
* to register the meta key across all existing taxonomies.
* @param string $meta_key The meta key to register.
* @param array $args Data used to describe the meta key when registered. See
* {@see register_meta()} for a list of supported arguments.
* @return bool True if the meta key was successfully registered, false if not.
*/
function register_term_meta( $taxonomy, $meta_key, array $args ) {
$args['object_subtype'] = $taxonomy;
return register_meta( 'term', $meta_key, $args );
}
/**
* Unregisters a meta key for terms.
*
* @since 4.9.8
*
* @param string $taxonomy Taxonomy the meta key is currently registered for. Pass
* an empty string if the meta key is registered across all
* existing taxonomies.
* @param string $meta_key The meta key to unregister.
* @return bool True on success, false if the meta key was not previously registered.
*/
function unregister_term_meta( $taxonomy, $meta_key ) {
return unregister_meta_key( 'term', $meta_key, $taxonomy );
}
/**
* Determines whether a taxonomy term exists.
*
* Formerly is_term(), introduced in 2.3.0.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 3.0.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int|string $term The term to check. Accepts term ID, slug, or name.
* @param string $taxonomy Optional. The taxonomy name to use.
* @param int $parent Optional. ID of parent term under which to confine the exists search.
* @return mixed Returns null if the term does not exist.
* Returns the term ID if no taxonomy is specified and the term ID exists.
* Returns an array of the term ID and the term taxonomy ID if the taxonomy is specified and the pairing exists.
* Returns 0 if term ID 0 is passed to the function.
*/
function term_exists( $term, $taxonomy = '', $parent = null ) {
global $wpdb;
$select = "SELECT term_id FROM $wpdb->terms as t WHERE ";
$tax_select = "SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE ";
if ( is_int( $term ) ) {
if ( 0 === $term ) {
return 0;
}
$where = 't.term_id = %d';
if ( ! empty( $taxonomy ) ) {
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber
return $wpdb->get_row( $wpdb->prepare( $tax_select . $where . ' AND tt.taxonomy = %s', $term, $taxonomy ), ARRAY_A );
} else {
return $wpdb->get_var( $wpdb->prepare( $select . $where, $term ) );
}
}
$term = trim( wp_unslash( $term ) );
$slug = sanitize_title( $term );
$where = 't.slug = %s';
$else_where = 't.name = %s';
$where_fields = array( $slug );
$else_where_fields = array( $term );
$orderby = 'ORDER BY t.term_id ASC';
$limit = 'LIMIT 1';
if ( ! empty( $taxonomy ) ) {
if ( is_numeric( $parent ) ) {
$parent = (int) $parent;
$where_fields[] = $parent;
$else_where_fields[] = $parent;
$where .= ' AND tt.parent = %d';
$else_where .= ' AND tt.parent = %d';
}
$where_fields[] = $taxonomy;
$else_where_fields[] = $taxonomy;
$result = $wpdb->get_row( $wpdb->prepare( "SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $where AND tt.taxonomy = %s $orderby $limit", $where_fields ), ARRAY_A );
if ( $result ) {
return $result;
}
return $wpdb->get_row( $wpdb->prepare( "SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $else_where AND tt.taxonomy = %s $orderby $limit", $else_where_fields ), ARRAY_A );
}
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
$result = $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->terms as t WHERE $where $orderby $limit", $where_fields ) );
if ( $result ) {
return $result;
}
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
return $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->terms as t WHERE $else_where $orderby $limit", $else_where_fields ) );
}
/**
* Check if a term is an ancestor of another term.
*
* You can use either an ID or the term object for both parameters.
*
* @since 3.4.0
*
* @param int|object $term1 ID or object to check if this is the parent term.
* @param int|object $term2 The child term.
* @param string $taxonomy Taxonomy name that $term1 and `$term2` belong to.
* @return bool Whether `$term2` is a child of `$term1`.
*/
function term_is_ancestor_of( $term1, $term2, $taxonomy ) {
if ( ! isset( $term1->term_id ) ) {
$term1 = get_term( $term1, $taxonomy );
}
if ( ! isset( $term2->parent ) ) {
$term2 = get_term( $term2, $taxonomy );
}
if ( empty( $term1->term_id ) || empty( $term2->parent ) ) {
return false;
}
if ( $term2->parent === $term1->term_id ) {
return true;
}
return term_is_ancestor_of( $term1, get_term( $term2->parent, $taxonomy ), $taxonomy );
}
/**
* Sanitize Term all fields.
*
* Relies on sanitize_term_field() to sanitize the term. The difference is that
* this function will sanitize all fields. The context is based
* on sanitize_term_field().
*
* The $term is expected to be either an array or an object.
*
* @since 2.3.0
*
* @param array|object $term The term to check.
* @param string $taxonomy The taxonomy name to use.
* @param string $context Optional. Context in which to sanitize the term. Accepts 'edit', 'db',
* 'display', 'attribute', or 'js'. Default 'display'.
* @return array|object Term with all fields sanitized.
*/
function sanitize_term( $term, $taxonomy, $context = 'display' ) {
$fields = array( 'term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group', 'term_taxonomy_id', 'object_id' );
$do_object = is_object( $term );
$term_id = $do_object ? $term->term_id : ( isset( $term['term_id'] ) ? $term['term_id'] : 0 );
foreach ( (array) $fields as $field ) {
if ( $do_object ) {
if ( isset( $term->$field ) ) {
$term->$field = sanitize_term_field( $field, $term->$field, $term_id, $taxonomy, $context );
}
} else {
if ( isset( $term[ $field ] ) ) {
$term[ $field ] = sanitize_term_field( $field, $term[ $field ], $term_id, $taxonomy, $context );
}
}
}
if ( $do_object ) {
$term->filter = $context;
} else {
$term['filter'] = $context;
}
return $term;
}
/**
* Cleanse the field value in the term based on the context.
*
* Passing a term field value through the function should be assumed to have
* cleansed the value for whatever context the term field is going to be used.
*
* If no context or an unsupported context is given, then default filters will
* be applied.
*
* There are enough filters for each context to support a custom filtering
* without creating your own filter function. Simply create a function that
* hooks into the filter you need.
*
* @since 2.3.0
*
* @param string $field Term field to sanitize.
* @param string $value Search for this term value.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy Name.
* @param string $context Context in which to sanitize the term field. Accepts 'edit', 'db', 'display',
* 'attribute', or 'js'.
* @return mixed Sanitized field.
*/
function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) {
$int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' );
if ( in_array( $field, $int_fields, true ) ) {
$value = (int) $value;
if ( $value < 0 ) {
$value = 0;
}
}
$context = strtolower( $context );
if ( 'raw' === $context ) {
return $value;
}
if ( 'edit' === $context ) {
/**
* Filters a term field to edit before it is sanitized.
*
* The dynamic portion of the filter name, `$field`, refers to the term field.
*
* @since 2.3.0
*
* @param mixed $value Value of the term field.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
*/
$value = apply_filters( "edit_term_{$field}", $value, $term_id, $taxonomy );
/**
* Filters the taxonomy field to edit before it is sanitized.
*
* The dynamic portions of the filter name, `$taxonomy` and `$field`, refer
* to the taxonomy slug and taxonomy field, respectively.
*
* @since 2.3.0
*
* @param mixed $value Value of the taxonomy field to edit.
* @param int $term_id Term ID.
*/
$value = apply_filters( "edit_{$taxonomy}_{$field}", $value, $term_id );
if ( 'description' === $field ) {
$value = esc_html( $value ); // textarea_escaped
} else {
$value = esc_attr( $value );
}
} elseif ( 'db' === $context ) {
/**
* Filters a term field value before it is sanitized.
*
* The dynamic portion of the filter name, `$field`, refers to the term field.
*
* @since 2.3.0
*
* @param mixed $value Value of the term field.
* @param string $taxonomy Taxonomy slug.
*/
$value = apply_filters( "pre_term_{$field}", $value, $taxonomy );
/**
* Filters a taxonomy field before it is sanitized.
*
* The dynamic portions of the filter name, `$taxonomy` and `$field`, refer
* to the taxonomy slug and field name, respectively.
*
* @since 2.3.0
*
* @param mixed $value Value of the taxonomy field.
*/
$value = apply_filters( "pre_{$taxonomy}_{$field}", $value );
// Back compat filters.
if ( 'slug' === $field ) {
/**
* Filters the category nicename before it is sanitized.
*
* Use the {@see 'pre_$taxonomy_$field'} hook instead.
*
* @since 2.0.3
*
* @param string $value The category nicename.
*/
$value = apply_filters( 'pre_category_nicename', $value );
}
} elseif ( 'rss' === $context ) {
/**
* Filters the term field for use in RSS.
*
* The dynamic portion of the filter name, `$field`, refers to the term field.
*
* @since 2.3.0
*
* @param mixed $value Value of the term field.
* @param string $taxonomy Taxonomy slug.
*/
$value = apply_filters( "term_{$field}_rss", $value, $taxonomy );
/**
* Filters the taxonomy field for use in RSS.
*
* The dynamic portions of the hook name, `$taxonomy`, and `$field`, refer
* to the taxonomy slug and field name, respectively.
*
* @since 2.3.0
*
* @param mixed $value Value of the taxonomy field.
*/
$value = apply_filters( "{$taxonomy}_{$field}_rss", $value );
} else {
// Use display filters by default.
/**
* Filters the term field sanitized for display.
*
* The dynamic portion of the filter name, `$field`, refers to the term field name.
*
* @since 2.3.0
*
* @param mixed $value Value of the term field.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
* @param string $context Context to retrieve the term field value.
*/
$value = apply_filters( "term_{$field}", $value, $term_id, $taxonomy, $context );
/**
* Filters the taxonomy field sanitized for display.
*
* The dynamic portions of the filter name, `$taxonomy`, and `$field`, refer
* to the taxonomy slug and taxonomy field, respectively.
*
* @since 2.3.0
*
* @param mixed $value Value of the taxonomy field.
* @param int $term_id Term ID.
* @param string $context Context to retrieve the taxonomy field value.
*/
$value = apply_filters( "{$taxonomy}_{$field}", $value, $term_id, $context );
}
if ( 'attribute' === $context ) {
$value = esc_attr( $value );
} elseif ( 'js' === $context ) {
$value = esc_js( $value );
}
return $value;
}
/**
* Count how many terms are in Taxonomy.
*
* Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true).
*
* @since 2.3.0
*
* @param string $taxonomy Taxonomy name.
* @param array|string $args Optional. Array of arguments that get passed to get_terms().
* Default empty array.
* @return array|int|WP_Error Number of terms in that taxonomy or WP_Error if the taxonomy does not exist.
*/
function wp_count_terms( $taxonomy, $args = array() ) {
$defaults = array(
'taxonomy' => $taxonomy,
'hide_empty' => false,
);
$args = wp_parse_args( $args, $defaults );
// Backward compatibility.
if ( isset( $args['ignore_empty'] ) ) {
$args['hide_empty'] = $args['ignore_empty'];
unset( $args['ignore_empty'] );
}
$args['fields'] = 'count';
return get_terms( $args );
}
/**
* Will unlink the object from the taxonomy or taxonomies.
*
* Will remove all relationships between the object and any terms in
* a particular taxonomy or taxonomies. Does not remove the term or
* taxonomy itself.
*
* @since 2.3.0
*
* @param int $object_id The term Object Id that refers to the term.
* @param string|array $taxonomies List of Taxonomy Names or single Taxonomy name.
*/
function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
$object_id = (int) $object_id;
if ( ! is_array( $taxonomies ) ) {
$taxonomies = array( $taxonomies );
}
foreach ( (array) $taxonomies as $taxonomy ) {
$term_ids = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'ids' ) );
$term_ids = array_map( 'intval', $term_ids );
wp_remove_object_terms( $object_id, $term_ids, $taxonomy );
}
}
/**
* Removes a term from the database.
*
* If the term is a parent of other terms, then the children will be updated to
* that term's parent.
*
* Metadata associated with the term will be deleted.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $term Term ID.
* @param string $taxonomy Taxonomy Name.
* @param array|string $args {
* Optional. Array of arguments to override the default term ID. Default empty array.
*
* @type int $default The term ID to make the default term. This will only override
* the terms found if there is only one term found. Any other and
* the found terms are used.
* @type bool $force_default Optional. Whether to force the supplied term as default to be
* assigned even if the object was not going to be term-less.
* Default false.
* }
* @return bool|int|WP_Error True on success, false if term does not exist. Zero on attempted
* deletion of default Category. WP_Error if the taxonomy does not exist.
*/
function wp_delete_term( $term, $taxonomy, $args = array() ) {
global $wpdb;
$term = (int) $term;
$ids = term_exists( $term, $taxonomy );
if ( ! $ids ) {
return false;
}
if ( is_wp_error( $ids ) ) {
return $ids;
}
$tt_id = $ids['term_taxonomy_id'];
$defaults = array();
if ( 'category' === $taxonomy ) {
$defaults['default'] = (int) get_option( 'default_category' );
if ( $defaults['default'] === $term ) {
return 0; // Don't delete the default category.
}
}
// Don't delete the default custom taxonomy term.
$taxonomy_object = get_taxonomy( $taxonomy );
if ( ! empty( $taxonomy_object->default_term ) ) {
$defaults['default'] = (int) get_option( 'default_term_' . $taxonomy );
if ( $defaults['default'] === $term ) {
return 0;
}
}
$args = wp_parse_args( $args, $defaults );
if ( isset( $args['default'] ) ) {
$default = (int) $args['default'];
if ( ! term_exists( $default, $taxonomy ) ) {
unset( $default );
}
}
if ( isset( $args['force_default'] ) ) {
$force_default = $args['force_default'];
}
/**
* Fires when deleting a term, before any modifications are made to posts or terms.
*
* @since 4.1.0
*
* @param int $term Term ID.
* @param string $taxonomy Taxonomy Name.
*/
do_action( 'pre_delete_term', $term, $taxonomy );
// Update children to point to new parent.
if ( is_taxonomy_hierarchical( $taxonomy ) ) {
$term_obj = get_term( $term, $taxonomy );
if ( is_wp_error( $term_obj ) ) {
return $term_obj;
}
$parent = $term_obj->parent;
$edit_ids = $wpdb->get_results( "SELECT term_id, term_taxonomy_id FROM $wpdb->term_taxonomy WHERE `parent` = " . (int) $term_obj->term_id );
$edit_tt_ids = wp_list_pluck( $edit_ids, 'term_taxonomy_id' );
/**
* Fires immediately before a term to delete's children are reassigned a parent.
*
* @since 2.9.0
*
* @param array $edit_tt_ids An array of term taxonomy IDs for the given term.
*/
do_action( 'edit_term_taxonomies', $edit_tt_ids );
$wpdb->update( $wpdb->term_taxonomy, compact( 'parent' ), array( 'parent' => $term_obj->term_id ) + compact( 'taxonomy' ) );
// Clean the cache for all child terms.
$edit_term_ids = wp_list_pluck( $edit_ids, 'term_id' );
clean_term_cache( $edit_term_ids, $taxonomy );
/**
* Fires immediately after a term to delete's children are reassigned a parent.
*
* @since 2.9.0
*
* @param array $edit_tt_ids An array of term taxonomy IDs for the given term.
*/
do_action( 'edited_term_taxonomies', $edit_tt_ids );
}
// Get the term before deleting it or its term relationships so we can pass to actions below.
$deleted_term = get_term( $term, $taxonomy );
$object_ids = (array) $wpdb->get_col( $wpdb->prepare( "SELECT object_id FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $tt_id ) );
foreach ( $object_ids as $object_id ) {
$terms = wp_get_object_terms(
$object_id,
$taxonomy,
array(
'fields' => 'ids',
'orderby' => 'none',
)
);
if ( 1 === count( $terms ) && isset( $default ) ) {
$terms = array( $default );
} else {
$terms = array_diff( $terms, array( $term ) );
if ( isset( $default ) && isset( $force_default ) && $force_default ) {
$terms = array_merge( $terms, array( $default ) );
}
}
$terms = array_map( 'intval', $terms );
wp_set_object_terms( $object_id, $terms, $taxonomy );
}
// Clean the relationship caches for all object types using this term.
$tax_object = get_taxonomy( $taxonomy );
foreach ( $tax_object->object_type as $object_type ) {
clean_object_term_cache( $object_ids, $object_type );
}
$term_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->termmeta WHERE term_id = %d ", $term ) );
foreach ( $term_meta_ids as $mid ) {
delete_metadata_by_mid( 'term', $mid );
}
/**
* Fires immediately before a term taxonomy ID is deleted.
*
* @since 2.9.0
*
* @param int $tt_id Term taxonomy ID.
*/
do_action( 'delete_term_taxonomy', $tt_id );
$wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) );
/**
* Fires immediately after a term taxonomy ID is deleted.
*
* @since 2.9.0
*
* @param int $tt_id Term taxonomy ID.
*/
do_action( 'deleted_term_taxonomy', $tt_id );
// Delete the term if no taxonomies use it.
if ( ! $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE term_id = %d", $term ) ) ) {
$wpdb->delete( $wpdb->terms, array( 'term_id' => $term ) );
}
clean_term_cache( $term, $taxonomy );
/**
* Fires after a term is deleted from the database and the cache is cleaned.
*
* @since 2.5.0
* @since 4.5.0 Introduced the `$object_ids` argument.
*
* @param int $term Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param mixed $deleted_term Copy of the already-deleted term, in the form specified
* by the parent function. WP_Error otherwise.
* @param array $object_ids List of term object IDs.
*/
do_action( 'delete_term', $term, $tt_id, $taxonomy, $deleted_term, $object_ids );
/**
* Fires after a term in a specific taxonomy is deleted.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the specific
* taxonomy the term belonged to.
*
* @since 2.3.0
* @since 4.5.0 Introduced the `$object_ids` argument.
*
* @param int $term Term ID.
* @param int $tt_id Term taxonomy ID.
* @param mixed $deleted_term Copy of the already-deleted term, in the form specified
* by the parent function. WP_Error otherwise.
* @param array $object_ids List of term object IDs.
*/
do_action( "delete_{$taxonomy}", $term, $tt_id, $deleted_term, $object_ids );
return true;
}
/**
* Deletes one existing category.
*
* @since 2.0.0
*
* @param int $cat_ID Category term ID.
* @return bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist;
* Zero on attempted deletion of default Category; WP_Error object is also a possibility.
*/
function wp_delete_category( $cat_ID ) {
return wp_delete_term( $cat_ID, 'category' );
}
/**
* Retrieves the terms associated with the given object(s), in the supplied taxonomies.
*
* @since 2.3.0
* @since 4.2.0 Added support for 'taxonomy', 'parent', and 'term_taxonomy_id' values of `$orderby`.
* Introduced `$parent` argument.
* @since 4.4.0 Introduced `$meta_query` and `$update_term_meta_cache` arguments. When `$fields` is 'all' or
* 'all_with_object_id', an array of `WP_Term` objects will be returned.
* @since 4.7.0 Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments.
*
* @param int|int[] $object_ids The ID(s) of the object(s) to retrieve.
* @param string|string[] $taxonomies The taxonomy names to retrieve terms from.
* @param array|string $args See WP_Term_Query::__construct() for supported arguments.
* @return array|WP_Error The requested term data or empty array if no terms found.
* WP_Error if any of the taxonomies don't exist.
*/
function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
if ( empty( $object_ids ) || empty( $taxonomies ) ) {
return array();
}
if ( ! is_array( $taxonomies ) ) {
$taxonomies = array( $taxonomies );
}
foreach ( $taxonomies as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
}
if ( ! is_array( $object_ids ) ) {
$object_ids = array( $object_ids );
}
$object_ids = array_map( 'intval', $object_ids );
$args = wp_parse_args( $args );
/**
* Filter arguments for retrieving object terms.
*
* @since 4.9.0
*
* @param array $args An array of arguments for retrieving terms for the given object(s).
* See {@see wp_get_object_terms()} for details.
* @param int[] $object_ids Array of object IDs.
* @param string[] $taxonomies Array of taxonomy names to retrieve terms from.
*/
$args = apply_filters( 'wp_get_object_terms_args', $args, $object_ids, $taxonomies );
/*
* When one or more queried taxonomies is registered with an 'args' array,
* those params override the `$args` passed to this function.
*/
$terms = array();
if ( count( $taxonomies ) > 1 ) {
foreach ( $taxonomies as $index => $taxonomy ) {
$t = get_taxonomy( $taxonomy );
if ( isset( $t->args ) && is_array( $t->args ) && array_merge( $args, $t->args ) != $args ) {
unset( $taxonomies[ $index ] );
$terms = array_merge( $terms, wp_get_object_terms( $object_ids, $taxonomy, array_merge( $args, $t->args ) ) );
}
}
} else {
$t = get_taxonomy( $taxonomies[0] );
if ( isset( $t->args ) && is_array( $t->args ) ) {
$args = array_merge( $args, $t->args );
}
}
$args['taxonomy'] = $taxonomies;
$args['object_ids'] = $object_ids;
// Taxonomies registered without an 'args' param are handled here.
if ( ! empty( $taxonomies ) ) {
$terms_from_remaining_taxonomies = get_terms( $args );
// Array keys should be preserved for values of $fields that use term_id for keys.
if ( ! empty( $args['fields'] ) && 0 === strpos( $args['fields'], 'id=>' ) ) {
$terms = $terms + $terms_from_remaining_taxonomies;
} else {
$terms = array_merge( $terms, $terms_from_remaining_taxonomies );
}
}
/**
* Filters the terms for a given object or objects.
*
* @since 4.2.0
*
* @param array $terms Array of terms for the given object or objects.
* @param int[] $object_ids Array of object IDs for which terms were retrieved.
* @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
* @param array $args Array of arguments for retrieving terms for the given
* object(s). See wp_get_object_terms() for details.
*/
$terms = apply_filters( 'get_object_terms', $terms, $object_ids, $taxonomies, $args );
$object_ids = implode( ',', $object_ids );
$taxonomies = "'" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "'";
/**
* Filters the terms for a given object or objects.
*
* The `$taxonomies` parameter passed to this filter is formatted as a SQL fragment. The
* {@see 'get_object_terms'} filter is recommended as an alternative.
*
* @since 2.8.0
*
* @param array $terms Array of terms for the given object or objects.
* @param int[] $object_ids Array of object IDs for which terms were retrieved.
* @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
* @param array $args Array of arguments for retrieving terms for the given
* object(s). See wp_get_object_terms() for details.
*/
return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );
}
/**
* Add a new term to the database.
*
* A non-existent term is inserted in the following sequence:
* 1. The term is added to the term table, then related to the taxonomy.
* 2. If everything is correct, several actions are fired.
* 3. The 'term_id_filter' is evaluated.
* 4. The term cache is cleaned.
* 5. Several more actions are fired.
* 6. An array is returned containing the `term_id` and `term_taxonomy_id`.
*
* If the 'slug' argument is not empty, then it is checked to see if the term
* is invalid. If it is not a valid, existing term, it is added and the term_id
* is given.
*
* If the taxonomy is hierarchical, and the 'parent' argument is not empty,
* the term is inserted and the term_id will be given.
*
* Error handling:
* If `$taxonomy` does not exist or `$term` is empty,
* a WP_Error object will be returned.
*
* If the term already exists on the same hierarchical level,
* or the term slug and name are not unique, a WP_Error object will be returned.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @since 2.3.0
*
* @param string $term The term name to add.
* @param string $taxonomy The taxonomy to which to add the term.
* @param array|string $args {
* Optional. Array or string of arguments for inserting a term.
*
* @type string $alias_of Slug of the term to make this term an alias of.
* Default empty string. Accepts a term slug.
* @type string $description The term description. Default empty string.
* @type int $parent The id of the parent term. Default 0.
* @type string $slug The term slug to use. Default empty string.
* }
* @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
* WP_Error otherwise.
*/
function wp_insert_term( $term, $taxonomy, $args = array() ) {
global $wpdb;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
/**
* Filters a term before it is sanitized and inserted into the database.
*
* @since 3.0.0
*
* @param string|WP_Error $term The term name to add, or a WP_Error object if there's an error.
* @param string $taxonomy Taxonomy slug.
*/
$term = apply_filters( 'pre_insert_term', $term, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( is_int( $term ) && 0 === $term ) {
return new WP_Error( 'invalid_term_id', __( 'Invalid term ID.' ) );
}
if ( '' === trim( $term ) ) {
return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );
}
$defaults = array(
'alias_of' => '',
'description' => '',
'parent' => 0,
'slug' => '',
);
$args = wp_parse_args( $args, $defaults );
if ( $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) {
return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );
}
$args['name'] = $term;
$args['taxonomy'] = $taxonomy;
// Coerce null description to strings, to avoid database errors.
$args['description'] = (string) $args['description'];
$args = sanitize_term( $args, $taxonomy, 'db' );
// expected_slashed ($name)
$name = wp_unslash( $args['name'] );
$description = wp_unslash( $args['description'] );
$parent = (int) $args['parent'];
$slug_provided = ! empty( $args['slug'] );
if ( ! $slug_provided ) {
$slug = sanitize_title( $name );
} else {
$slug = $args['slug'];
}
$term_group = 0;
if ( $args['alias_of'] ) {
$alias = get_term_by( 'slug', $args['alias_of'], $taxonomy );
if ( ! empty( $alias->term_group ) ) {
// The alias we want is already in a group, so let's use that one.
$term_group = $alias->term_group;
} elseif ( ! empty( $alias->term_id ) ) {
/*
* The alias is not in a group, so we create a new one
* and add the alias to it.
*/
$term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1;
wp_update_term(
$alias->term_id,
$taxonomy,
array(
'term_group' => $term_group,
)
);
}
}
/*
* Prevent the creation of terms with duplicate names at the same level of a taxonomy hierarchy,
* unless a unique slug has been explicitly provided.
*/
$name_matches = get_terms(
array(
'taxonomy' => $taxonomy,
'name' => $name,
'hide_empty' => false,
'parent' => $args['parent'],
'update_term_meta_cache' => false,
)
);
/*
* The `name` match in `get_terms()` doesn't differentiate accented characters,
* so we do a stricter comparison here.
*/
$name_match = null;
if ( $name_matches ) {
foreach ( $name_matches as $_match ) {
if ( strtolower( $name ) === strtolower( $_match->name ) ) {
$name_match = $_match;
break;
}
}
}
if ( $name_match ) {
$slug_match = get_term_by( 'slug', $slug, $taxonomy );
if ( ! $slug_provided || $name_match->slug === $slug || $slug_match ) {
if ( is_taxonomy_hierarchical( $taxonomy ) ) {
$siblings = get_terms(
array(
'taxonomy' => $taxonomy,
'get' => 'all',
'parent' => $parent,
'update_term_meta_cache' => false,
)
);
$existing_term = null;
$sibling_names = wp_list_pluck( $siblings, 'name' );
$sibling_slugs = wp_list_pluck( $siblings, 'slug' );
if ( ( ! $slug_provided || $name_match->slug === $slug ) && in_array( $name, $sibling_names, true ) ) {
$existing_term = $name_match;
} elseif ( $slug_match && in_array( $slug, $sibling_slugs, true ) ) {
$existing_term = $slug_match;
}
if ( $existing_term ) {
return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id );
}
} else {
return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id );
}
}
}
$slug = wp_unique_term_slug( $slug, (object) $args );
$data = compact( 'name', 'slug', 'term_group' );
/**
* Filters term data before it is inserted into the database.
*
* @since 4.7.0
*
* @param array $data Term data to be inserted.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_insert_term().
*/
$data = apply_filters( 'wp_insert_term_data', $data, $taxonomy, $args );
if ( false === $wpdb->insert( $wpdb->terms, $data ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not insert term into the database.' ), $wpdb->last_error );
}
$term_id = (int) $wpdb->insert_id;
// Seems unreachable. However, is used in the case that a term name is provided, which sanitizes to an empty string.
if ( empty( $slug ) ) {
$slug = sanitize_title( $slug, $term_id );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edit_terms', $term_id, $taxonomy );
$wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edited_terms', $term_id, $taxonomy );
}
$tt_id = $wpdb->get_var( $wpdb->prepare( "SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d", $taxonomy, $term_id ) );
if ( ! empty( $tt_id ) ) {
return array(
'term_id' => $term_id,
'term_taxonomy_id' => $tt_id,
);
}
if ( false === $wpdb->insert( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ) + array( 'count' => 0 ) ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not insert term taxonomy into the database.' ), $wpdb->last_error );
}
$tt_id = (int) $wpdb->insert_id;
/*
* Sanity check: if we just created a term with the same parent + taxonomy + slug but a higher term_id than
* an existing term, then we have unwittingly created a duplicate term. Delete the dupe, and use the term_id
* and term_taxonomy_id of the older term instead. Then return out of the function so that the "create" hooks
* are not fired.
*/
$duplicate_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.term_id, t.slug, tt.term_taxonomy_id, tt.taxonomy FROM $wpdb->terms t INNER JOIN $wpdb->term_taxonomy tt ON ( tt.term_id = t.term_id ) WHERE t.slug = %s AND tt.parent = %d AND tt.taxonomy = %s AND t.term_id < %d AND tt.term_taxonomy_id != %d", $slug, $parent, $taxonomy, $term_id, $tt_id ) );
/**
* Filters the duplicate term check that takes place during term creation.
*
* Term parent+taxonomy+slug combinations are meant to be unique, and wp_insert_term()
* performs a last-minute confirmation of this uniqueness before allowing a new term
* to be created. Plugins with different uniqueness requirements may use this filter
* to bypass or modify the duplicate-term check.
*
* @since 5.1.0
*
* @param object $duplicate_term Duplicate term row from terms table, if found.
* @param string $term Term being inserted.
* @param string $taxonomy Taxonomy name.
* @param array $args Term arguments passed to the function.
* @param int $tt_id term_taxonomy_id for the newly created term.
*/
$duplicate_term = apply_filters( 'wp_insert_term_duplicate_term_check', $duplicate_term, $term, $taxonomy, $args, $tt_id );
if ( $duplicate_term ) {
$wpdb->delete( $wpdb->terms, array( 'term_id' => $term_id ) );
$wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) );
$term_id = (int) $duplicate_term->term_id;
$tt_id = (int) $duplicate_term->term_taxonomy_id;
clean_term_cache( $term_id, $taxonomy );
return array(
'term_id' => $term_id,
'term_taxonomy_id' => $tt_id,
);
}
/**
* Fires immediately after a new term is created, before the term cache is cleaned.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'create_term', $term_id, $tt_id, $taxonomy );
/**
* Fires after a new term is created for a specific taxonomy.
*
* The dynamic portion of the hook name, `$taxonomy`, refers
* to the slug of the taxonomy the term was created for.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
*/
do_action( "create_{$taxonomy}", $term_id, $tt_id );
/**
* Filters the term ID after a new term is created.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
*/
$term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );
clean_term_cache( $term_id, $taxonomy );
/**
* Fires after a new term is created, and after the term cache has been cleaned.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'created_term', $term_id, $tt_id, $taxonomy );
/**
* Fires after a new term in a specific taxonomy is created, and after the term
* cache has been cleaned.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
*/
do_action( "created_{$taxonomy}", $term_id, $tt_id );
/**
* Fires after a term has been saved, and the term cache has been cleared.
*
* @since 5.5.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param bool $update Whether this is an existing term being updated.
*/
do_action( 'saved_term', $term_id, $tt_id, $taxonomy, false );
/**
* Fires after a term in a specific taxonomy has been saved, and the term
* cache has been cleared.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
*
* @since 5.5.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param bool $update Whether this is an existing term being updated.
*/
do_action( "saved_{$taxonomy}", $term_id, $tt_id, false );
return array(
'term_id' => $term_id,
'term_taxonomy_id' => $tt_id,
);
}
/**
* Create Term and Taxonomy Relationships.
*
* Relates an object (post, link etc) to a term and taxonomy type. Creates the
* term and taxonomy relationship if it doesn't already exist. Creates a term if
* it doesn't exist (using the slug).
*
* A relationship means that the term is grouped in or belongs to the taxonomy.
* A term has no meaning until it is given context by defining which taxonomy it
* exists under.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $object_id The object to relate to.
* @param string|int|array $terms A single term slug, single term ID, or array of either term slugs or IDs.
* Will replace all existing related terms in this taxonomy. Passing an
* empty value will remove all related terms.
* @param string $taxonomy The context in which to relate the term to the object.
* @param bool $append Optional. If false will delete difference of terms. Default false.
* @return array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.
*/
function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
global $wpdb;
$object_id = (int) $object_id;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
if ( ! is_array( $terms ) ) {
$terms = array( $terms );
}
if ( ! $append ) {
$old_tt_ids = wp_get_object_terms(
$object_id,
$taxonomy,
array(
'fields' => 'tt_ids',
'orderby' => 'none',
'update_term_meta_cache' => false,
)
);
} else {
$old_tt_ids = array();
}
$tt_ids = array();
$term_ids = array();
$new_tt_ids = array();
foreach ( (array) $terms as $term ) {
if ( '' === trim( $term ) ) {
continue;
}
$term_info = term_exists( $term, $taxonomy );
if ( ! $term_info ) {
// Skip if a non-existent term ID is passed.
if ( is_int( $term ) ) {
continue;
}
$term_info = wp_insert_term( $term, $taxonomy );
}
if ( is_wp_error( $term_info ) ) {
return $term_info;
}
$term_ids[] = $term_info['term_id'];
$tt_id = $term_info['term_taxonomy_id'];
$tt_ids[] = $tt_id;
if ( $wpdb->get_var( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d", $object_id, $tt_id ) ) ) {
continue;
}
/**
* Fires immediately before an object-term relationship is added.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy );
$wpdb->insert(
$wpdb->term_relationships,
array(
'object_id' => $object_id,
'term_taxonomy_id' => $tt_id,
)
);
/**
* Fires immediately after an object-term relationship is added.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy );
$new_tt_ids[] = $tt_id;
}
if ( $new_tt_ids ) {
wp_update_term_count( $new_tt_ids, $taxonomy );
}
if ( ! $append ) {
$delete_tt_ids = array_diff( $old_tt_ids, $tt_ids );
if ( $delete_tt_ids ) {
$in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'";
$delete_term_ids = $wpdb->get_col( $wpdb->prepare( "SELECT tt.term_id FROM $wpdb->term_taxonomy AS tt WHERE tt.taxonomy = %s AND tt.term_taxonomy_id IN ($in_delete_tt_ids)", $taxonomy ) );
$delete_term_ids = array_map( 'intval', $delete_term_ids );
$remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy );
if ( is_wp_error( $remove ) ) {
return $remove;
}
}
}
$t = get_taxonomy( $taxonomy );
if ( ! $append && isset( $t->sort ) && $t->sort ) {
$values = array();
$term_order = 0;
$final_tt_ids = wp_get_object_terms(
$object_id,
$taxonomy,
array(
'fields' => 'tt_ids',
'update_term_meta_cache' => false,
)
);
foreach ( $tt_ids as $tt_id ) {
if ( in_array( (int) $tt_id, $final_tt_ids, true ) ) {
$values[] = $wpdb->prepare( '(%d, %d, %d)', $object_id, $tt_id, ++$term_order );
}
}
if ( $values ) {
if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . join( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database.' ), $wpdb->last_error );
}
}
}
wp_cache_delete( $object_id, $taxonomy . '_relationships' );
wp_cache_delete( 'last_changed', 'terms' );
/**
* Fires after an object's terms have been set.
*
* @since 2.8.0
*
* @param int $object_id Object ID.
* @param array $terms An array of object terms.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
* @param bool $append Whether to append new terms to the old terms.
* @param array $old_tt_ids Old array of term taxonomy IDs.
*/
do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids );
return $tt_ids;
}
/**
* Add term(s) associated with a given object.
*
* @since 3.6.0
*
* @param int $object_id The ID of the object to which the terms will be added.
* @param string|int|array $terms The slug(s) or ID(s) of the term(s) to add.
* @param array|string $taxonomy Taxonomy name.
* @return array|WP_Error Term taxonomy IDs of the affected terms.
*/
function wp_add_object_terms( $object_id, $terms, $taxonomy ) {
return wp_set_object_terms( $object_id, $terms, $taxonomy, true );
}
/**
* Remove term(s) associated with a given object.
*
* @since 3.6.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $object_id The ID of the object from which the terms will be removed.
* @param string|int|array $terms The slug(s) or ID(s) of the term(s) to remove.
* @param array|string $taxonomy Taxonomy name.
* @return bool|WP_Error True on success, false or WP_Error on failure.
*/
function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
global $wpdb;
$object_id = (int) $object_id;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
if ( ! is_array( $terms ) ) {
$terms = array( $terms );
}
$tt_ids = array();
foreach ( (array) $terms as $term ) {
if ( '' === trim( $term ) ) {
continue;
}
$term_info = term_exists( $term, $taxonomy );
if ( ! $term_info ) {
// Skip if a non-existent term ID is passed.
if ( is_int( $term ) ) {
continue;
}
}
if ( is_wp_error( $term_info ) ) {
return $term_info;
}
$tt_ids[] = $term_info['term_taxonomy_id'];
}
if ( $tt_ids ) {
$in_tt_ids = "'" . implode( "', '", $tt_ids ) . "'";
/**
* Fires immediately before an object-term relationship is deleted.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'delete_term_relationships', $object_id, $tt_ids, $taxonomy );
$deleted = $wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ($in_tt_ids)", $object_id ) );
wp_cache_delete( $object_id, $taxonomy . '_relationships' );
wp_cache_delete( 'last_changed', 'terms' );
/**
* Fires immediately after an object-term relationship is deleted.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'deleted_term_relationships', $object_id, $tt_ids, $taxonomy );
wp_update_term_count( $tt_ids, $taxonomy );
return (bool) $deleted;
}
return false;
}
/**
* Will make slug unique, if it isn't already.
*
* The `$slug` has to be unique global to every taxonomy, meaning that one
* taxonomy term can't have a matching slug with another taxonomy term. Each
* slug has to be globally unique for every taxonomy.
*
* The way this works is that if the taxonomy that the term belongs to is
* hierarchical and has a parent, it will append that parent to the $slug.
*
* If that still doesn't return a unique slug, then it tries to append a number
* until it finds a number that is truly unique.
*
* The only purpose for `$term` is for appending a parent, if one exists.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $slug The string that will be tried for a unique slug.
* @param object $term The term object that the `$slug` will belong to.
* @return string Will return a true unique slug.
*/
function wp_unique_term_slug( $slug, $term ) {
global $wpdb;
$needs_suffix = true;
$original_slug = $slug;
// As of 4.1, duplicate slugs are allowed as long as they're in different taxonomies.
if ( ! term_exists( $slug ) || get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
$needs_suffix = false;
}
/*
* If the taxonomy supports hierarchy and the term has a parent, make the slug unique
* by incorporating parent slugs.
*/
$parent_suffix = '';
if ( $needs_suffix && is_taxonomy_hierarchical( $term->taxonomy ) && ! empty( $term->parent ) ) {
$the_parent = $term->parent;
while ( ! empty( $the_parent ) ) {
$parent_term = get_term( $the_parent, $term->taxonomy );
if ( is_wp_error( $parent_term ) || empty( $parent_term ) ) {
break;
}
$parent_suffix .= '-' . $parent_term->slug;
if ( ! term_exists( $slug . $parent_suffix ) ) {
break;
}
if ( empty( $parent_term->parent ) ) {
break;
}
$the_parent = $parent_term->parent;
}
}
// If we didn't get a unique slug, try appending a number to make it unique.
/**
* Filters whether the proposed unique term slug is bad.
*
* @since 4.3.0
*
* @param bool $needs_suffix Whether the slug needs to be made unique with a suffix.
* @param string $slug The slug.
* @param object $term Term object.
*/
if ( apply_filters( 'wp_unique_term_slug_is_bad_slug', $needs_suffix, $slug, $term ) ) {
if ( $parent_suffix ) {
$slug .= $parent_suffix;
}
if ( ! empty( $term->term_id ) ) {
$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
} else {
$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
}
if ( $wpdb->get_var( $query ) ) { // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
$num = 2;
do {
$alt_slug = $slug . "-$num";
$num++;
$slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
} while ( $slug_check );
$slug = $alt_slug;
}
}
/**
* Filters the unique term slug.
*
* @since 4.3.0
*
* @param string $slug Unique term slug.
* @param object $term Term object.
* @param string $original_slug Slug originally passed to the function for testing.
*/
return apply_filters( 'wp_unique_term_slug', $slug, $term, $original_slug );
}
/**
* Update term based on arguments provided.
*
* The `$args` will indiscriminately override all values with the same field name.
* Care must be taken to not override important information need to update or
* update will fail (or perhaps create a new term, neither would be acceptable).
*
* Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not
* defined in `$args` already.
*
* 'alias_of' will create a term group, if it doesn't already exist, and
* update it for the `$term`.
*
* If the 'slug' argument in `$args` is missing, then the 'name' will be used.
* If you set 'slug' and it isn't unique, then a WP_Error is returned.
* If you don't pass any slug, then a unique one will be created.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $term_id The ID of the term.
* @param string $taxonomy The taxonomy of the term.
* @param array|string $args {
* Optional. Array or string of arguments for updating a term.
*
* @type string $alias_of Slug of the term to make this term an alias of.
* Default empty string. Accepts a term slug.
* @type string $description The term description. Default empty string.
* @type int $parent The id of the parent term. Default 0.
* @type string $slug The term slug to use. Default empty string.
* }
* @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
* WP_Error otherwise.
*/
function wp_update_term( $term_id, $taxonomy, $args = array() ) {
global $wpdb;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
$term_id = (int) $term_id;
// First, get all of the original args.
$term = get_term( $term_id, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( ! $term ) {
return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
}
$term = (array) $term->data;
// Escape data pulled from DB.
$term = wp_slash( $term );
// Merge old and new args with new args overwriting old ones.
$args = array_merge( $term, $args );
$defaults = array(
'alias_of' => '',
'description' => '',
'parent' => 0,
'slug' => '',
);
$args = wp_parse_args( $args, $defaults );
$args = sanitize_term( $args, $taxonomy, 'db' );
$parsed_args = $args;
// expected_slashed ($name)
$name = wp_unslash( $args['name'] );
$description = wp_unslash( $args['description'] );
$parsed_args['name'] = $name;
$parsed_args['description'] = $description;
if ( '' === trim( $name ) ) {
return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );
}
if ( $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) {
return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );
}
$empty_slug = false;
if ( empty( $args['slug'] ) ) {
$empty_slug = true;
$slug = sanitize_title( $name );
} else {
$slug = $args['slug'];
}
$parsed_args['slug'] = $slug;
$term_group = isset( $parsed_args['term_group'] ) ? $parsed_args['term_group'] : 0;
if ( $args['alias_of'] ) {
$alias = get_term_by( 'slug', $args['alias_of'], $taxonomy );
if ( ! empty( $alias->term_group ) ) {
// The alias we want is already in a group, so let's use that one.
$term_group = $alias->term_group;
} elseif ( ! empty( $alias->term_id ) ) {
/*
* The alias is not in a group, so we create a new one
* and add the alias to it.
*/
$term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1;
wp_update_term(
$alias->term_id,
$taxonomy,
array(
'term_group' => $term_group,
)
);
}
$parsed_args['term_group'] = $term_group;
}
/**
* Filters the term parent.
*
* Hook to this filter to see if it will cause a hierarchy loop.
*
* @since 3.1.0
*
* @param int $parent ID of the parent term.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
* @param array $parsed_args An array of potentially altered update arguments for the given term.
* @param array $args An array of update arguments for the given term.
*/
$parent = (int) apply_filters( 'wp_update_term_parent', $args['parent'], $term_id, $taxonomy, $parsed_args, $args );
// Check for duplicate slug.
$duplicate = get_term_by( 'slug', $slug, $taxonomy );
if ( $duplicate && $duplicate->term_id !== $term_id ) {
// If an empty slug was passed or the parent changed, reset the slug to something unique.
// Otherwise, bail.
if ( $empty_slug || ( $parent !== (int) $term['parent'] ) ) {
$slug = wp_unique_term_slug( $slug, (object) $args );
} else {
/* translators: %s: Taxonomy term slug. */
return new WP_Error( 'duplicate_term_slug', sprintf( __( 'The slug ā%sā is already in use by another term.' ), $slug ) );
}
}
$tt_id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d", $taxonomy, $term_id ) );
// Check whether this is a shared term that needs splitting.
$_term_id = _split_shared_term( $term_id, $tt_id );
if ( ! is_wp_error( $_term_id ) ) {
$term_id = $_term_id;
}
/**
* Fires immediately before the given terms are edited.
*
* @since 2.9.0
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edit_terms', $term_id, $taxonomy );
$data = compact( 'name', 'slug', 'term_group' );
/**
* Filters term data before it is updated in the database.
*
* @since 4.7.0
*
* @param array $data Term data to be updated.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
$data = apply_filters( 'wp_update_term_data', $data, $term_id, $taxonomy, $args );
$wpdb->update( $wpdb->terms, $data, compact( 'term_id' ) );
if ( empty( $slug ) ) {
$slug = sanitize_title( $name, $term_id );
$wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );
}
/**
* Fires immediately after the given terms are edited.
*
* @since 2.9.0
*
* @param int $term_id Term ID
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edited_terms', $term_id, $taxonomy );
/**
* Fires immediate before a term-taxonomy relationship is updated.
*
* @since 2.9.0
*
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edit_term_taxonomy', $tt_id, $taxonomy );
$wpdb->update( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ), array( 'term_taxonomy_id' => $tt_id ) );
/**
* Fires immediately after a term-taxonomy relationship is updated.
*
* @since 2.9.0
*
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edited_term_taxonomy', $tt_id, $taxonomy );
/**
* Fires after a term has been updated, but before the term cache has been cleaned.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edit_term', $term_id, $tt_id, $taxonomy );
/**
* Fires after a term in a specific taxonomy has been updated, but before the term
* cache has been cleaned.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
*/
do_action( "edit_{$taxonomy}", $term_id, $tt_id );
/** This filter is documented in wp-includes/taxonomy.php */
$term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );
clean_term_cache( $term_id, $taxonomy );
/**
* Fires after a term has been updated, and the term cache has been cleaned.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edited_term', $term_id, $tt_id, $taxonomy );
/**
* Fires after a term for a specific taxonomy has been updated, and the term
* cache has been cleaned.
*
* The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
*
* @since 2.3.0
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
*/
do_action( "edited_{$taxonomy}", $term_id, $tt_id );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'saved_term', $term_id, $tt_id, $taxonomy, true );
/** This action is documented in wp-includes/taxonomy.php */
do_action( "saved_{$taxonomy}", $term_id, $tt_id, true );
return array(
'term_id' => $term_id,
'term_taxonomy_id' => $tt_id,
);
}
/**
* Enable or disable term counting.
*
* @since 2.5.0
*
* @param bool $defer Optional. Enable if true, disable if false.
* @return bool Whether term counting is enabled or disabled.
*/
function wp_defer_term_counting( $defer = null ) {
static $_defer = false;
if ( is_bool( $defer ) ) {
$_defer = $defer;
// Flush any deferred counts.
if ( ! $defer ) {
wp_update_term_count( null, null, true );
}
}
return $_defer;
}
/**
* Updates the amount of terms in taxonomy.
*
* If there is a taxonomy callback applied, then it will be called for updating
* the count.
*
* The default action is to count what the amount of terms have the relationship
* of term ID. Once that is done, then update the database.
*
* @since 2.3.0
*
* @param int|array $terms The term_taxonomy_id of the terms.
* @param string $taxonomy The context of the term.
* @param bool $do_deferred Whether to flush the deferred term counts too. Default false.
* @return bool If no terms will return false, and if successful will return true.
*/
function wp_update_term_count( $terms, $taxonomy, $do_deferred = false ) {
static $_deferred = array();
if ( $do_deferred ) {
foreach ( (array) array_keys( $_deferred ) as $tax ) {
wp_update_term_count_now( $_deferred[ $tax ], $tax );
unset( $_deferred[ $tax ] );
}
}
if ( empty( $terms ) ) {
return false;
}
if ( ! is_array( $terms ) ) {
$terms = array( $terms );
}
if ( wp_defer_term_counting() ) {
if ( ! isset( $_deferred[ $taxonomy ] ) ) {
$_deferred[ $taxonomy ] = array();
}
$_deferred[ $taxonomy ] = array_unique( array_merge( $_deferred[ $taxonomy ], $terms ) );
return true;
}
return wp_update_term_count_now( $terms, $taxonomy );
}
/**
* Perform term count update immediately.
*
* @since 2.5.0
*
* @param array $terms The term_taxonomy_id of terms to update.
* @param string $taxonomy The context of the term.
* @return true Always true when complete.
*/
function wp_update_term_count_now( $terms, $taxonomy ) {
$terms = array_map( 'intval', $terms );
$taxonomy = get_taxonomy( $taxonomy );
if ( ! empty( $taxonomy->update_count_callback ) ) {
call_user_func( $taxonomy->update_count_callback, $terms, $taxonomy );
} else {
$object_types = (array) $taxonomy->object_type;
foreach ( $object_types as &$object_type ) {
if ( 0 === strpos( $object_type, 'attachment:' ) ) {
list( $object_type ) = explode( ':', $object_type );
}
}
if ( array_filter( $object_types, 'post_type_exists' ) == $object_types ) {
// Only post types are attached to this taxonomy.
_update_post_term_count( $terms, $taxonomy );
} else {
// Default count updater.
_update_generic_term_count( $terms, $taxonomy );
}
}
clean_term_cache( $terms, '', false );
return true;
}
//
// Cache.
//
/**
* Removes the taxonomy relationship to terms from the cache.
*
* Will remove the entire taxonomy relationship containing term `$object_id`. The
* term IDs have to exist within the taxonomy `$object_type` for the deletion to
* take place.
*
* @since 2.3.0
*
* @global bool $_wp_suspend_cache_invalidation
*
* @see get_object_taxonomies() for more on $object_type.
*
* @param int|array $object_ids Single or list of term object ID(s).
* @param array|string $object_type The taxonomy object type.
*/
function clean_object_term_cache( $object_ids, $object_type ) {
global $_wp_suspend_cache_invalidation;
if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
return;
}
if ( ! is_array( $object_ids ) ) {
$object_ids = array( $object_ids );
}
$taxonomies = get_object_taxonomies( $object_type );
foreach ( $object_ids as $id ) {
foreach ( $taxonomies as $taxonomy ) {
wp_cache_delete( $id, "{$taxonomy}_relationships" );
}
}
/**
* Fires after the object term cache has been cleaned.
*
* @since 2.5.0
*
* @param array $object_ids An array of object IDs.
* @param string $object_type Object type.
*/
do_action( 'clean_object_term_cache', $object_ids, $object_type );
}
/**
* Will remove all of the term IDs from the cache.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
* @global bool $_wp_suspend_cache_invalidation
*
* @param int|int[] $ids Single or array of term IDs.
* @param string $taxonomy Optional. Taxonomy slug. Can be empty, in which case the taxonomies of the passed
* term IDs will be used. Default empty.
* @param bool $clean_taxonomy Optional. Whether to clean taxonomy wide caches (true), or just individual
* term object caches (false). Default true.
*/
function clean_term_cache( $ids, $taxonomy = '', $clean_taxonomy = true ) {
global $wpdb, $_wp_suspend_cache_invalidation;
if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
return;
}
if ( ! is_array( $ids ) ) {
$ids = array( $ids );
}
$taxonomies = array();
// If no taxonomy, assume tt_ids.
if ( empty( $taxonomy ) ) {
$tt_ids = array_map( 'intval', $ids );
$tt_ids = implode( ', ', $tt_ids );
$terms = $wpdb->get_results( "SELECT term_id, taxonomy FROM $wpdb->term_taxonomy WHERE term_taxonomy_id IN ($tt_ids)" );
$ids = array();
foreach ( (array) $terms as $term ) {
$taxonomies[] = $term->taxonomy;
$ids[] = $term->term_id;
wp_cache_delete( $term->term_id, 'terms' );
}
$taxonomies = array_unique( $taxonomies );
} else {
$taxonomies = array( $taxonomy );
foreach ( $taxonomies as $taxonomy ) {
foreach ( $ids as $id ) {
wp_cache_delete( $id, 'terms' );
}
}
}
foreach ( $taxonomies as $taxonomy ) {
if ( $clean_taxonomy ) {
clean_taxonomy_cache( $taxonomy );
}
/**
* Fires once after each taxonomy's term cache has been cleaned.
*
* @since 2.5.0
* @since 4.5.0 Added the `$clean_taxonomy` parameter.
*
* @param array $ids An array of term IDs.
* @param string $taxonomy Taxonomy slug.
* @param bool $clean_taxonomy Whether or not to clean taxonomy-wide caches
*/
do_action( 'clean_term_cache', $ids, $taxonomy, $clean_taxonomy );
}
wp_cache_set( 'last_changed', microtime(), 'terms' );
}
/**
* Clean the caches for a taxonomy.
*
* @since 4.9.0
*
* @param string $taxonomy Taxonomy slug.
*/
function clean_taxonomy_cache( $taxonomy ) {
wp_cache_delete( 'all_ids', $taxonomy );
wp_cache_delete( 'get', $taxonomy );
// Regenerate cached hierarchy.
delete_option( "{$taxonomy}_children" );
_get_term_hierarchy( $taxonomy );
/**
* Fires after a taxonomy's caches have been cleaned.
*
* @since 4.9.0
*
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'clean_taxonomy_cache', $taxonomy );
}
/**
* Retrieves the cached term objects for the given object ID.
*
* Upstream functions (like get_the_terms() and is_object_in_term()) are
* responsible for populating the object-term relationship cache. The current
* function only fetches relationship data that is already in the cache.
*
* @since 2.3.0
* @since 4.7.0 Returns a `WP_Error` object if there's an error with
* any of the matched terms.
*
* @param int $id Term object ID, for example a post, comment, or user ID.
* @param string $taxonomy Taxonomy name.
* @return bool|WP_Term[]|WP_Error Array of `WP_Term` objects, if cached.
* False if cache is empty for `$taxonomy` and `$id`.
* WP_Error if get_term() returns an error object for any term.
*/
function get_object_term_cache( $id, $taxonomy ) {
$_term_ids = wp_cache_get( $id, "{$taxonomy}_relationships" );
// We leave the priming of relationship caches to upstream functions.
if ( false === $_term_ids ) {
return false;
}
// Backward compatibility for if a plugin is putting objects into the cache, rather than IDs.
$term_ids = array();
foreach ( $_term_ids as $term_id ) {
if ( is_numeric( $term_id ) ) {
$term_ids[] = intval( $term_id );
} elseif ( isset( $term_id->term_id ) ) {
$term_ids[] = intval( $term_id->term_id );
}
}
// Fill the term objects.
_prime_term_caches( $term_ids );
$terms = array();
foreach ( $term_ids as $term_id ) {
$term = get_term( $term_id, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
$terms[] = $term;
}
return $terms;
}
/**
* Updates the cache for the given term object ID(s).
*
* Note: Due to performance concerns, great care should be taken to only update
* term caches when necessary. Processing time can increase exponentially depending
* on both the number of passed term IDs and the number of taxonomies those terms
* belong to.
*
* Caches will only be updated for terms not already cached.
*
* @since 2.3.0
*
* @param string|int[] $object_ids Comma-separated list or array of term object IDs.
* @param string|string[] $object_type The taxonomy object type or array of the same.
* @return void|false False if all of the terms in `$object_ids` are already cached.
*/
function update_object_term_cache( $object_ids, $object_type ) {
if ( empty( $object_ids ) ) {
return;
}
if ( ! is_array( $object_ids ) ) {
$object_ids = explode( ',', $object_ids );
}
$object_ids = array_map( 'intval', $object_ids );
$non_cached_ids = array();
$taxonomies = get_object_taxonomies( $object_type );
foreach ( $taxonomies as $taxonomy ) {
$cache_values = wp_cache_get_multiple( (array) $object_ids, "{$taxonomy}_relationships" );
foreach ( $cache_values as $id => $value ) {
if ( false === $value ) {
$non_cached_ids[] = $id;
}
}
}
if ( empty( $non_cached_ids ) ) {
return false;
}
$non_cached_ids = array_unique( $non_cached_ids );
$terms = wp_get_object_terms(
$non_cached_ids,
$taxonomies,
array(
'fields' => 'all_with_object_id',
'orderby' => 'name',
'update_term_meta_cache' => false,
)
);
$object_terms = array();
foreach ( (array) $terms as $term ) {
$object_terms[ $term->object_id ][ $term->taxonomy ][] = $term->term_id;
}
foreach ( $non_cached_ids as $id ) {
foreach ( $taxonomies as $taxonomy ) {
if ( ! isset( $object_terms[ $id ][ $taxonomy ] ) ) {
if ( ! isset( $object_terms[ $id ] ) ) {
$object_terms[ $id ] = array();
}
$object_terms[ $id ][ $taxonomy ] = array();
}
}
}
foreach ( $object_terms as $id => $value ) {
foreach ( $value as $taxonomy => $terms ) {
wp_cache_add( $id, $terms, "{$taxonomy}_relationships" );
}
}
}
/**
* Updates Terms to Taxonomy in cache.
*
* @since 2.3.0
*
* @param WP_Term[] $terms Array of term objects to change.
* @param string $taxonomy Not used.
*/
function update_term_cache( $terms, $taxonomy = '' ) {
foreach ( (array) $terms as $term ) {
// Create a copy in case the array was passed by reference.
$_term = clone $term;
// Object ID should not be cached.
unset( $_term->object_id );
wp_cache_add( $term->term_id, $_term, 'terms' );
}
}
//
// Private.
//
/**
* Retrieves children of taxonomy as Term IDs.
*
* @access private
* @since 2.3.0
*
* @param string $taxonomy Taxonomy name.
* @return array Empty if $taxonomy isn't hierarchical or returns children as Term IDs.
*/
function _get_term_hierarchy( $taxonomy ) {
if ( ! is_taxonomy_hierarchical( $taxonomy ) ) {
return array();
}
$children = get_option( "{$taxonomy}_children" );
if ( is_array( $children ) ) {
return $children;
}
$children = array();
$terms = get_terms(
array(
'taxonomy' => $taxonomy,
'get' => 'all',
'orderby' => 'id',
'fields' => 'id=>parent',
'update_term_meta_cache' => false,
)
);
foreach ( $terms as $term_id => $parent ) {
if ( $parent > 0 ) {
$children[ $parent ][] = $term_id;
}
}
update_option( "{$taxonomy}_children", $children );
return $children;
}
/**
* Get the subset of $terms that are descendants of $term_id.
*
* If `$terms` is an array of objects, then _get_term_children() returns an array of objects.
* If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs.
*
* @access private
* @since 2.3.0
*
* @param int $term_id The ancestor term: all returned terms should be descendants of `$term_id`.
* @param array $terms The set of terms - either an array of term objects or term IDs - from which those that
* are descendants of $term_id will be chosen.
* @param string $taxonomy The taxonomy which determines the hierarchy of the terms.
* @param array $ancestors Optional. Term ancestors that have already been identified. Passed by reference, to keep
* track of found terms when recursing the hierarchy. The array of located ancestors is used
* to prevent infinite recursion loops. For performance, `term_ids` are used as array keys,
* with 1 as value. Default empty array.
* @return array|WP_Error The subset of $terms that are descendants of $term_id.
*/
function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() ) {
$empty_array = array();
if ( empty( $terms ) ) {
return $empty_array;
}
$term_id = (int) $term_id;
$term_list = array();
$has_children = _get_term_hierarchy( $taxonomy );
if ( $term_id && ! isset( $has_children[ $term_id ] ) ) {
return $empty_array;
}
// Include the term itself in the ancestors array, so we can properly detect when a loop has occurred.
if ( empty( $ancestors ) ) {
$ancestors[ $term_id ] = 1;
}
foreach ( (array) $terms as $term ) {
$use_id = false;
if ( ! is_object( $term ) ) {
$term = get_term( $term, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
$use_id = true;
}
// Don't recurse if we've already identified the term as a child - this indicates a loop.
if ( isset( $ancestors[ $term->term_id ] ) ) {
continue;
}
if ( (int) $term->parent === $term_id ) {
if ( $use_id ) {
$term_list[] = $term->term_id;
} else {
$term_list[] = $term;
}
if ( ! isset( $has_children[ $term->term_id ] ) ) {
continue;
}
$ancestors[ $term->term_id ] = 1;
$children = _get_term_children( $term->term_id, $terms, $taxonomy, $ancestors );
if ( $children ) {
$term_list = array_merge( $term_list, $children );
}
}
}
return $term_list;
}
/**
* Add count of children to parent count.
*
* Recalculates term counts by including items from child terms. Assumes all
* relevant children are already in the $terms argument.
*
* @access private
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param array $terms List of term objects (passed by reference).
* @param string $taxonomy Term context.
*/
function _pad_term_counts( &$terms, $taxonomy ) {
global $wpdb;
// This function only works for hierarchical taxonomies like post categories.
if ( ! is_taxonomy_hierarchical( $taxonomy ) ) {
return;
}
$term_hier = _get_term_hierarchy( $taxonomy );
if ( empty( $term_hier ) ) {
return;
}
$term_items = array();
$terms_by_id = array();
$term_ids = array();
foreach ( (array) $terms as $key => $term ) {
$terms_by_id[ $term->term_id ] = & $terms[ $key ];
$term_ids[ $term->term_taxonomy_id ] = $term->term_id;
}
// Get the object and term IDs and stick them in a lookup table.
$tax_obj = get_taxonomy( $taxonomy );
$object_types = esc_sql( $tax_obj->object_type );
$results = $wpdb->get_results( "SELECT object_id, term_taxonomy_id FROM $wpdb->term_relationships INNER JOIN $wpdb->posts ON object_id = ID WHERE term_taxonomy_id IN (" . implode( ',', array_keys( $term_ids ) ) . ") AND post_type IN ('" . implode( "', '", $object_types ) . "') AND post_status = 'publish'" );
foreach ( $results as $row ) {
$id = $term_ids[ $row->term_taxonomy_id ];
$term_items[ $id ][ $row->object_id ] = isset( $term_items[ $id ][ $row->object_id ] ) ? ++$term_items[ $id ][ $row->object_id ] : 1;
}
// Touch every ancestor's lookup row for each post in each term.
foreach ( $term_ids as $term_id ) {
$child = $term_id;
$ancestors = array();
while ( ! empty( $terms_by_id[ $child ] ) && $parent = $terms_by_id[ $child ]->parent ) {
$ancestors[] = $child;
if ( ! empty( $term_items[ $term_id ] ) ) {
foreach ( $term_items[ $term_id ] as $item_id => $touches ) {
$term_items[ $parent ][ $item_id ] = isset( $term_items[ $parent ][ $item_id ] ) ? ++$term_items[ $parent ][ $item_id ] : 1;
}
}
$child = $parent;
if ( in_array( $parent, $ancestors, true ) ) {
break;
}
}
}
// Transfer the touched cells.
foreach ( (array) $term_items as $id => $items ) {
if ( isset( $terms_by_id[ $id ] ) ) {
$terms_by_id[ $id ]->count = count( $items );
}
}
}
/**
* Adds any terms from the given IDs to the cache that do not already exist in cache.
*
* @since 4.6.0
* @access private
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param array $term_ids Array of term IDs.
* @param bool $update_meta_cache Optional. Whether to update the meta cache. Default true.
*/
function _prime_term_caches( $term_ids, $update_meta_cache = true ) {
global $wpdb;
$non_cached_ids = _get_non_cached_ids( $term_ids, 'terms' );
if ( ! empty( $non_cached_ids ) ) {
$fresh_terms = $wpdb->get_results( sprintf( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE t.term_id IN (%s)", join( ',', array_map( 'intval', $non_cached_ids ) ) ) );
update_term_cache( $fresh_terms, $update_meta_cache );
if ( $update_meta_cache ) {
update_termmeta_cache( $non_cached_ids );
}
}
}
//
// Default callbacks.
//
/**
* Will update term count based on object types of the current taxonomy.
*
* Private function for the default callback for post_tag and category
* taxonomies.
*
* @access private
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int[] $terms List of Term taxonomy IDs.
* @param WP_Taxonomy $taxonomy Current taxonomy object of terms.
*/
function _update_post_term_count( $terms, $taxonomy ) {
global $wpdb;
$object_types = (array) $taxonomy->object_type;
foreach ( $object_types as &$object_type ) {
list( $object_type ) = explode( ':', $object_type );
}
$object_types = array_unique( $object_types );
$check_attachments = array_search( 'attachment', $object_types, true );
if ( false !== $check_attachments ) {
unset( $object_types[ $check_attachments ] );
$check_attachments = true;
}
if ( $object_types ) {
$object_types = esc_sql( array_filter( $object_types, 'post_type_exists' ) );
}
foreach ( (array) $terms as $term ) {
$count = 0;
// Attachments can be 'inherit' status, we need to base count off the parent's status if so.
if ( $check_attachments ) {
$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts p1 WHERE p1.ID = $wpdb->term_relationships.object_id AND ( post_status = 'publish' OR ( post_status = 'inherit' AND post_parent > 0 AND ( SELECT post_status FROM $wpdb->posts WHERE ID = p1.post_parent ) = 'publish' ) ) AND post_type = 'attachment' AND term_taxonomy_id = %d", $term ) );
}
if ( $object_types ) {
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.QuotedDynamicPlaceholderGeneration
$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts WHERE $wpdb->posts.ID = $wpdb->term_relationships.object_id AND post_status = 'publish' AND post_type IN ('" . implode( "', '", $object_types ) . "') AND term_taxonomy_id = %d", $term ) );
}
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edit_term_taxonomy', $term, $taxonomy->name );
$wpdb->update( $wpdb->term_taxonomy, compact( 'count' ), array( 'term_taxonomy_id' => $term ) );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edited_term_taxonomy', $term, $taxonomy->name );
}
}
/**
* Will update term count based on number of objects.
*
* Default callback for the 'link_category' taxonomy.
*
* @since 3.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int[] $terms List of term taxonomy IDs.
* @param WP_Taxonomy $taxonomy Current taxonomy object of terms.
*/
function _update_generic_term_count( $terms, $taxonomy ) {
global $wpdb;
foreach ( (array) $terms as $term ) {
$count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $term ) );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edit_term_taxonomy', $term, $taxonomy->name );
$wpdb->update( $wpdb->term_taxonomy, compact( 'count' ), array( 'term_taxonomy_id' => $term ) );
/** This action is documented in wp-includes/taxonomy.php */
do_action( 'edited_term_taxonomy', $term, $taxonomy->name );
}
}
/**
* Create a new term for a term_taxonomy item that currently shares its term
* with another term_taxonomy.
*
* @ignore
* @since 4.2.0
* @since 4.3.0 Introduced `$record` parameter. Also, `$term_id` and
* `$term_taxonomy_id` can now accept objects.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int|object $term_id ID of the shared term, or the shared term object.
* @param int|object $term_taxonomy_id ID of the term_taxonomy item to receive a new term, or the term_taxonomy object
* (corresponding to a row from the term_taxonomy table).
* @param bool $record Whether to record data about the split term in the options table. The recording
* process has the potential to be resource-intensive, so during batch operations
* it can be beneficial to skip inline recording and do it just once, after the
* batch is processed. Only set this to `false` if you know what you are doing.
* Default: true.
* @return int|WP_Error When the current term does not need to be split (or cannot be split on the current
* database schema), `$term_id` is returned. When the term is successfully split, the
* new term_id is returned. A WP_Error is returned for miscellaneous errors.
*/
function _split_shared_term( $term_id, $term_taxonomy_id, $record = true ) {
global $wpdb;
if ( is_object( $term_id ) ) {
$shared_term = $term_id;
$term_id = intval( $shared_term->term_id );
}
if ( is_object( $term_taxonomy_id ) ) {
$term_taxonomy = $term_taxonomy_id;
$term_taxonomy_id = intval( $term_taxonomy->term_taxonomy_id );
}
// If there are no shared term_taxonomy rows, there's nothing to do here.
$shared_tt_count = (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy tt WHERE tt.term_id = %d AND tt.term_taxonomy_id != %d", $term_id, $term_taxonomy_id ) );
if ( ! $shared_tt_count ) {
return $term_id;
}
/*
* Verify that the term_taxonomy_id passed to the function is actually associated with the term_id.
* If there's a mismatch, it may mean that the term is already split. Return the actual term_id from the db.
*/
$check_term_id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
if ( $check_term_id !== $term_id ) {
return $check_term_id;
}
// Pull up data about the currently shared slug, which we'll use to populate the new one.
if ( empty( $shared_term ) ) {
$shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) );
}
$new_term_data = array(
'name' => $shared_term->name,
'slug' => $shared_term->slug,
'term_group' => $shared_term->term_group,
);
if ( false === $wpdb->insert( $wpdb->terms, $new_term_data ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not split shared term.' ), $wpdb->last_error );
}
$new_term_id = (int) $wpdb->insert_id;
// Update the existing term_taxonomy to point to the newly created term.
$wpdb->update(
$wpdb->term_taxonomy,
array( 'term_id' => $new_term_id ),
array( 'term_taxonomy_id' => $term_taxonomy_id )
);
// Reassign child terms to the new parent.
if ( empty( $term_taxonomy ) ) {
$term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
}
$children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE parent = %d AND taxonomy = %s", $term_id, $term_taxonomy->taxonomy ) );
if ( ! empty( $children_tt_ids ) ) {
foreach ( $children_tt_ids as $child_tt_id ) {
$wpdb->update(
$wpdb->term_taxonomy,
array( 'parent' => $new_term_id ),
array( 'term_taxonomy_id' => $child_tt_id )
);
clean_term_cache( (int) $child_tt_id, '', false );
}
} else {
// If the term has no children, we must force its taxonomy cache to be rebuilt separately.
clean_term_cache( $new_term_id, $term_taxonomy->taxonomy, false );
}
clean_term_cache( $term_id, $term_taxonomy->taxonomy, false );
/*
* Taxonomy cache clearing is delayed to avoid race conditions that may occur when
* regenerating the taxonomy's hierarchy tree.
*/
$taxonomies_to_clean = array( $term_taxonomy->taxonomy );
// Clean the cache for term taxonomies formerly shared with the current term.
$shared_term_taxonomies = $wpdb->get_col( $wpdb->prepare( "SELECT taxonomy FROM $wpdb->term_taxonomy WHERE term_id = %d", $term_id ) );
$taxonomies_to_clean = array_merge( $taxonomies_to_clean, $shared_term_taxonomies );
foreach ( $taxonomies_to_clean as $taxonomy_to_clean ) {
clean_taxonomy_cache( $taxonomy_to_clean );
}
// Keep a record of term_ids that have been split, keyed by old term_id. See wp_get_split_term().
if ( $record ) {
$split_term_data = get_option( '_split_terms', array() );
if ( ! isset( $split_term_data[ $term_id ] ) ) {
$split_term_data[ $term_id ] = array();
}
$split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id;
update_option( '_split_terms', $split_term_data );
}
// If we've just split the final shared term, set the "finished" flag.
$shared_terms_exist = $wpdb->get_results(
"SELECT tt.term_id, t.*, count(*) as term_tt_count FROM {$wpdb->term_taxonomy} tt
LEFT JOIN {$wpdb->terms} t ON t.term_id = tt.term_id
GROUP BY t.term_id
HAVING term_tt_count > 1
LIMIT 1"
);
if ( ! $shared_terms_exist ) {
update_option( 'finished_splitting_shared_terms', true );
}
/**
* Fires after a previously shared taxonomy term is split into two separate terms.
*
* @since 4.2.0
*
* @param int $term_id ID of the formerly shared term.
* @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
* @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
* @param string $taxonomy Taxonomy for the split term.
*/
do_action( 'split_shared_term', $term_id, $new_term_id, $term_taxonomy_id, $term_taxonomy->taxonomy );
return $new_term_id;
}
/**
* Splits a batch of shared taxonomy terms.
*
* @since 4.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*/
function _wp_batch_split_terms() {
global $wpdb;
$lock_name = 'term_split.lock';
// Try to lock.
$lock_result = $wpdb->query( $wpdb->prepare( "INSERT IGNORE INTO `$wpdb->options` ( `option_name`, `option_value`, `autoload` ) VALUES (%s, %s, 'no') /* LOCK */", $lock_name, time() ) );
if ( ! $lock_result ) {
$lock_result = get_option( $lock_name );
// Bail if we were unable to create a lock, or if the existing lock is still valid.
if ( ! $lock_result || ( $lock_result > ( time() - HOUR_IN_SECONDS ) ) ) {
wp_schedule_single_event( time() + ( 5 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
return;
}
}
// Update the lock, as by this point we've definitely got a lock, just need to fire the actions.
update_option( $lock_name, time() );
// Get a list of shared terms (those with more than one associated row in term_taxonomy).
$shared_terms = $wpdb->get_results(
"SELECT tt.term_id, t.*, count(*) as term_tt_count FROM {$wpdb->term_taxonomy} tt
LEFT JOIN {$wpdb->terms} t ON t.term_id = tt.term_id
GROUP BY t.term_id
HAVING term_tt_count > 1
LIMIT 10"
);
// No more terms, we're done here.
if ( ! $shared_terms ) {
update_option( 'finished_splitting_shared_terms', true );
delete_option( $lock_name );
return;
}
// Shared terms found? We'll need to run this script again.
wp_schedule_single_event( time() + ( 2 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
// Rekey shared term array for faster lookups.
$_shared_terms = array();
foreach ( $shared_terms as $shared_term ) {
$term_id = intval( $shared_term->term_id );
$_shared_terms[ $term_id ] = $shared_term;
}
$shared_terms = $_shared_terms;
// Get term taxonomy data for all shared terms.
$shared_term_ids = implode( ',', array_keys( $shared_terms ) );
$shared_tts = $wpdb->get_results( "SELECT * FROM {$wpdb->term_taxonomy} WHERE `term_id` IN ({$shared_term_ids})" );
// Split term data recording is slow, so we do it just once, outside the loop.
$split_term_data = get_option( '_split_terms', array() );
$skipped_first_term = array();
$taxonomies = array();
foreach ( $shared_tts as $shared_tt ) {
$term_id = intval( $shared_tt->term_id );
// Don't split the first tt belonging to a given term_id.
if ( ! isset( $skipped_first_term[ $term_id ] ) ) {
$skipped_first_term[ $term_id ] = 1;
continue;
}
if ( ! isset( $split_term_data[ $term_id ] ) ) {
$split_term_data[ $term_id ] = array();
}
// Keep track of taxonomies whose hierarchies need flushing.
if ( ! isset( $taxonomies[ $shared_tt->taxonomy ] ) ) {
$taxonomies[ $shared_tt->taxonomy ] = 1;
}
// Split the term.
$split_term_data[ $term_id ][ $shared_tt->taxonomy ] = _split_shared_term( $shared_terms[ $term_id ], $shared_tt, false );
}
// Rebuild the cached hierarchy for each affected taxonomy.
foreach ( array_keys( $taxonomies ) as $tax ) {
delete_option( "{$tax}_children" );
_get_term_hierarchy( $tax );
}
update_option( '_split_terms', $split_term_data );
delete_option( $lock_name );
}
/**
* In order to avoid the _wp_batch_split_terms() job being accidentally removed,
* check that it's still scheduled while we haven't finished splitting terms.
*
* @ignore
* @since 4.3.0
*/
function _wp_check_for_scheduled_split_terms() {
if ( ! get_option( 'finished_splitting_shared_terms' ) && ! wp_next_scheduled( 'wp_split_shared_term_batch' ) ) {
wp_schedule_single_event( time() + MINUTE_IN_SECONDS, 'wp_split_shared_term_batch' );
}
}
/**
* Check default categories when a term gets split to see if any of them need to be updated.
*
* @ignore
* @since 4.2.0
*
* @param int $term_id ID of the formerly shared term.
* @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
* @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
* @param string $taxonomy Taxonomy for the split term.
*/
function _wp_check_split_default_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
if ( 'category' !== $taxonomy ) {
return;
}
foreach ( array( 'default_category', 'default_link_category', 'default_email_category' ) as $option ) {
if ( (int) get_option( $option, -1 ) === $term_id ) {
update_option( $option, $new_term_id );
}
}
}
/**
* Check menu items when a term gets split to see if any of them need to be updated.
*
* @ignore
* @since 4.2.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $term_id ID of the formerly shared term.
* @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
* @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
* @param string $taxonomy Taxonomy for the split term.
*/
function _wp_check_split_terms_in_menus( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
global $wpdb;
$post_ids = $wpdb->get_col(
$wpdb->prepare(
"SELECT m1.post_id
FROM {$wpdb->postmeta} AS m1
INNER JOIN {$wpdb->postmeta} AS m2 ON ( m2.post_id = m1.post_id )
INNER JOIN {$wpdb->postmeta} AS m3 ON ( m3.post_id = m1.post_id )
WHERE ( m1.meta_key = '_menu_item_type' AND m1.meta_value = 'taxonomy' )
AND ( m2.meta_key = '_menu_item_object' AND m2.meta_value = %s )
AND ( m3.meta_key = '_menu_item_object_id' AND m3.meta_value = %d )",
$taxonomy,
$term_id
)
);
if ( $post_ids ) {
foreach ( $post_ids as $post_id ) {
update_post_meta( $post_id, '_menu_item_object_id', $new_term_id, $term_id );
}
}
}
/**
* If the term being split is a nav_menu, change associations.
*
* @ignore
* @since 4.3.0
*
* @param int $term_id ID of the formerly shared term.
* @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
* @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
* @param string $taxonomy Taxonomy for the split term.
*/
function _wp_check_split_nav_menu_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
if ( 'nav_menu' !== $taxonomy ) {
return;
}
// Update menu locations.
$locations = get_nav_menu_locations();
foreach ( $locations as $location => $menu_id ) {
if ( $term_id === $menu_id ) {
$locations[ $location ] = $new_term_id;
}
}
set_theme_mod( 'nav_menu_locations', $locations );
}
/**
* Get data about terms that previously shared a single term_id, but have since been split.
*
* @since 4.2.0
*
* @param int $old_term_id Term ID. This is the old, pre-split term ID.
* @return array Array of new term IDs, keyed by taxonomy.
*/
function wp_get_split_terms( $old_term_id ) {
$split_terms = get_option( '_split_terms', array() );
$terms = array();
if ( isset( $split_terms[ $old_term_id ] ) ) {
$terms = $split_terms[ $old_term_id ];
}
return $terms;
}
/**
* Get the new term ID corresponding to a previously split term.
*
* @since 4.2.0
*
* @param int $old_term_id Term ID. This is the old, pre-split term ID.
* @param string $taxonomy Taxonomy that the term belongs to.
* @return int|false If a previously split term is found corresponding to the old term_id and taxonomy,
* the new term_id will be returned. If no previously split term is found matching
* the parameters, returns false.
*/
function wp_get_split_term( $old_term_id, $taxonomy ) {
$split_terms = wp_get_split_terms( $old_term_id );
$term_id = false;
if ( isset( $split_terms[ $taxonomy ] ) ) {
$term_id = (int) $split_terms[ $taxonomy ];
}
return $term_id;
}
/**
* Determine whether a term is shared between multiple taxonomies.
*
* Shared taxonomy terms began to be split in 4.3, but failed cron tasks or
* other delays in upgrade routines may cause shared terms to remain.
*
* @since 4.4.0
*
* @param int $term_id Term ID.
* @return bool Returns false if a term is not shared between multiple taxonomies or
* if splitting shared taxonomy terms is finished.
*/
function wp_term_is_shared( $term_id ) {
global $wpdb;
if ( get_option( 'finished_splitting_shared_terms' ) ) {
return false;
}
$tt_count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE term_id = %d", $term_id ) );
return $tt_count > 1;
}
/**
* Generate a permalink for a taxonomy term archive.
*
* @since 2.5.0
*
* @global WP_Rewrite $wp_rewrite WordPress rewrite component.
*
* @param WP_Term|int|string $term The term object, ID, or slug whose link will be retrieved.
* @param string $taxonomy Optional. Taxonomy. Default empty.
* @return string|WP_Error URL of the taxonomy term archive on success, WP_Error if term does not exist.
*/
function get_term_link( $term, $taxonomy = '' ) {
global $wp_rewrite;
if ( ! is_object( $term ) ) {
if ( is_int( $term ) ) {
$term = get_term( $term, $taxonomy );
} else {
$term = get_term_by( 'slug', $term, $taxonomy );
}
}
if ( ! is_object( $term ) ) {
$term = new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
}
if ( is_wp_error( $term ) ) {
return $term;
}
$taxonomy = $term->taxonomy;
$termlink = $wp_rewrite->get_extra_permastruct( $taxonomy );
/**
* Filters the permalink structure for a terms before token replacement occurs.
*
* @since 4.9.0
*
* @param string $termlink The permalink structure for the term's taxonomy.
* @param WP_Term $term The term object.
*/
$termlink = apply_filters( 'pre_term_link', $termlink, $term );
$slug = $term->slug;
$t = get_taxonomy( $taxonomy );
if ( empty( $termlink ) ) {
if ( 'category' === $taxonomy ) {
$termlink = '?cat=' . $term->term_id;
} elseif ( $t->query_var ) {
$termlink = "?$t->query_var=$slug";
} else {
$termlink = "?taxonomy=$taxonomy&term=$slug";
}
$termlink = home_url( $termlink );
} else {
if ( $t->rewrite['hierarchical'] ) {
$hierarchical_slugs = array();
$ancestors = get_ancestors( $term->term_id, $taxonomy, 'taxonomy' );
foreach ( (array) $ancestors as $ancestor ) {
$ancestor_term = get_term( $ancestor, $taxonomy );
$hierarchical_slugs[] = $ancestor_term->slug;
}
$hierarchical_slugs = array_reverse( $hierarchical_slugs );
$hierarchical_slugs[] = $slug;
$termlink = str_replace( "%$taxonomy%", implode( '/', $hierarchical_slugs ), $termlink );
} else {
$termlink = str_replace( "%$taxonomy%", $slug, $termlink );
}
$termlink = home_url( user_trailingslashit( $termlink, 'category' ) );
}
// Back compat filters.
if ( 'post_tag' === $taxonomy ) {
/**
* Filters the tag link.
*
* @since 2.3.0
* @since 2.5.0 Deprecated in favor of {@see 'term_link'} filter.
* @since 5.4.1 Restored (un-deprecated).
*
* @param string $termlink Tag link URL.
* @param int $term_id Term ID.
*/
$termlink = apply_filters( 'tag_link', $termlink, $term->term_id );
} elseif ( 'category' === $taxonomy ) {
/**
* Filters the category link.
*
* @since 1.5.0
* @since 2.5.0 Deprecated in favor of {@see 'term_link'} filter.
* @since 5.4.1 Restored (un-deprecated).
*
* @param string $termlink Category link URL.
* @param int $term_id Term ID.
*/
$termlink = apply_filters( 'category_link', $termlink, $term->term_id );
}
/**
* Filters the term link.
*
* @since 2.5.0
*
* @param string $termlink Term link URL.
* @param WP_Term $term Term object.
* @param string $taxonomy Taxonomy slug.
*/
return apply_filters( 'term_link', $termlink, $term, $taxonomy );
}
/**
* Display the taxonomies of a post with available options.
*
* This function can be used within the loop to display the taxonomies for a
* post without specifying the Post ID. You can also use it outside the Loop to
* display the taxonomies for a specific post.
*
* @since 2.5.0
*
* @param array $args {
* Arguments about which post to use and how to format the output. Shares all of the arguments
* supported by get_the_taxonomies(), in addition to the following.
*
* @type int|WP_Post $post Post ID or object to get taxonomies of. Default current post.
* @type string $before Displays before the taxonomies. Default empty string.
* @type string $sep Separates each taxonomy. Default is a space.
* @type string $after Displays after the taxonomies. Default empty string.
* }
*/
function the_taxonomies( $args = array() ) {
$defaults = array(
'post' => 0,
'before' => '',
'sep' => ' ',
'after' => '',
);
$parsed_args = wp_parse_args( $args, $defaults );
echo $parsed_args['before'] . join( $parsed_args['sep'], get_the_taxonomies( $parsed_args['post'], $parsed_args ) ) . $parsed_args['after'];
}
/**
* Retrieve all taxonomies associated with a post.
*
* This function can be used within the loop. It will also return an array of
* the taxonomies with links to the taxonomy and name.
*
* @since 2.5.0
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @param array $args {
* Optional. Arguments about how to format the list of taxonomies. Default empty array.
*
* @type string $template Template for displaying a taxonomy label and list of terms.
* Default is "Label: Terms."
* @type string $term_template Template for displaying a single term in the list. Default is the term name
* linked to its archive.
* }
* @return array List of taxonomies.
*/
function get_the_taxonomies( $post = 0, $args = array() ) {
$post = get_post( $post );
$args = wp_parse_args(
$args,
array(
/* translators: %s: Taxonomy label, %l: List of terms formatted as per $term_template. */
'template' => __( '%s: %l.' ),
'term_template' => '%2$s ',
)
);
$taxonomies = array();
if ( ! $post ) {
return $taxonomies;
}
foreach ( get_object_taxonomies( $post ) as $taxonomy ) {
$t = (array) get_taxonomy( $taxonomy );
if ( empty( $t['label'] ) ) {
$t['label'] = $taxonomy;
}
if ( empty( $t['args'] ) ) {
$t['args'] = array();
}
if ( empty( $t['template'] ) ) {
$t['template'] = $args['template'];
}
if ( empty( $t['term_template'] ) ) {
$t['term_template'] = $args['term_template'];
}
$terms = get_object_term_cache( $post->ID, $taxonomy );
if ( false === $terms ) {
$terms = wp_get_object_terms( $post->ID, $taxonomy, $t['args'] );
}
$links = array();
foreach ( $terms as $term ) {
$links[] = wp_sprintf( $t['term_template'], esc_attr( get_term_link( $term ) ), $term->name );
}
if ( $links ) {
$taxonomies[ $taxonomy ] = wp_sprintf( $t['template'], $t['label'], $links, $terms );
}
}
return $taxonomies;
}
/**
* Retrieve all taxonomy names for the given post.
*
* @since 2.5.0
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @return string[] An array of all taxonomy names for the given post.
*/
function get_post_taxonomies( $post = 0 ) {
$post = get_post( $post );
return get_object_taxonomies( $post );
}
/**
* Determine if the given object is associated with any of the given terms.
*
* The given terms are checked against the object's terms' term_ids, names and slugs.
* Terms given as integers will only be checked against the object's terms' term_ids.
* If no terms are given, determines if object is associated with any terms in the given taxonomy.
*
* @since 2.7.0
*
* @param int $object_id ID of the object (post ID, link ID, ...).
* @param string $taxonomy Single taxonomy name.
* @param int|string|array $terms Optional. Term term_id, name, slug or array of said. Default null.
* @return bool|WP_Error WP_Error on input error.
*/
function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
$object_id = (int) $object_id;
if ( ! $object_id ) {
return new WP_Error( 'invalid_object', __( 'Invalid object ID.' ) );
}
$object_terms = get_object_term_cache( $object_id, $taxonomy );
if ( false === $object_terms ) {
$object_terms = wp_get_object_terms( $object_id, $taxonomy, array( 'update_term_meta_cache' => false ) );
if ( is_wp_error( $object_terms ) ) {
return $object_terms;
}
wp_cache_set( $object_id, wp_list_pluck( $object_terms, 'term_id' ), "{$taxonomy}_relationships" );
}
if ( is_wp_error( $object_terms ) ) {
return $object_terms;
}
if ( empty( $object_terms ) ) {
return false;
}
if ( empty( $terms ) ) {
return ( ! empty( $object_terms ) );
}
$terms = (array) $terms;
$ints = array_filter( $terms, 'is_int' );
if ( $ints ) {
$strs = array_diff( $terms, $ints );
} else {
$strs =& $terms;
}
foreach ( $object_terms as $object_term ) {
// If term is an int, check against term_ids only.
if ( $ints && in_array( $object_term->term_id, $ints, true ) ) {
return true;
}
if ( $strs ) {
// Only check numeric strings against term_id, to avoid false matches due to type juggling.
$numeric_strs = array_map( 'intval', array_filter( $strs, 'is_numeric' ) );
if ( in_array( $object_term->term_id, $numeric_strs, true ) ) {
return true;
}
if ( in_array( $object_term->name, $strs, true ) ) {
return true;
}
if ( in_array( $object_term->slug, $strs, true ) ) {
return true;
}
}
}
return false;
}
/**
* Determine if the given object type is associated with the given taxonomy.
*
* @since 3.0.0
*
* @param string $object_type Object type string.
* @param string $taxonomy Single taxonomy name.
* @return bool True if object is associated with the taxonomy, otherwise false.
*/
function is_object_in_taxonomy( $object_type, $taxonomy ) {
$taxonomies = get_object_taxonomies( $object_type );
if ( empty( $taxonomies ) ) {
return false;
}
return in_array( $taxonomy, $taxonomies, true );
}
/**
* Get an array of ancestor IDs for a given object.
*
* @since 3.1.0
* @since 4.1.0 Introduced the `$resource_type` argument.
*
* @param int $object_id Optional. The ID of the object. Default 0.
* @param string $object_type Optional. The type of object for which we'll be retrieving
* ancestors. Accepts a post type or a taxonomy name. Default empty.
* @param string $resource_type Optional. Type of resource $object_type is. Accepts 'post_type'
* or 'taxonomy'. Default empty.
* @return int[] An array of IDs of ancestors from lowest to highest in the hierarchy.
*/
function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' ) {
$object_id = (int) $object_id;
$ancestors = array();
if ( empty( $object_id ) ) {
/** This filter is documented in wp-includes/taxonomy.php */
return apply_filters( 'get_ancestors', $ancestors, $object_id, $object_type, $resource_type );
}
if ( ! $resource_type ) {
if ( is_taxonomy_hierarchical( $object_type ) ) {
$resource_type = 'taxonomy';
} elseif ( post_type_exists( $object_type ) ) {
$resource_type = 'post_type';
}
}
if ( 'taxonomy' === $resource_type ) {
$term = get_term( $object_id, $object_type );
while ( ! is_wp_error( $term ) && ! empty( $term->paren