wp_update_custom_css_post()

💡 云策文档标注

概述

wp_update_custom_css_post() 函数用于更新或创建指定主题的 custom_css 文章，以存储自定义 CSS 数据。它处理 CSS 字符串和可选参数，并返回 WP_Post 对象或 WP_Error。

关键要点

函数用于更新或插入 custom_css 文章，存储 CSS 到 post_content 和可选的预处理 CSS 到 post_content_filtered。
参数包括必需的 $css 字符串和可选的 $args 数组，其中可指定 preprocessed 和 stylesheet。
使用 wp_get_custom_css_post() 检查文章是否存在，然后调用 wp_update_post() 或 wp_insert_post() 进行更新或创建。
包含 update_custom_css_data 过滤器，允许插件修改 CSS 数据，适用于 CSS 预处理器场景。
返回类型为 WP_Post 或 WP_Error，成功时返回文章对象。

代码示例

function wp_update_custom_css_post( $css, $args = array() ) {
    $args = wp_parse_args(
        $args,
        array(
            'preprocessed' => '',
            'stylesheet'   => get_stylesheet(),
        )
    );

    $data = array(
        'css'          => $css,
        'preprocessed' => $args['preprocessed'],
    );

    $data = apply_filters( 'update_custom_css_data', $data, array_merge( $args, compact( 'css' ) ) );

    $post_data = array(
        'post_title'            => $args['stylesheet'],
        'post_name'             => sanitize_title( $args['stylesheet'] ),
        'post_type'             => 'custom_css',
        'post_status'           => 'publish',
        'post_content'          => $data['css'],
        'post_content_filtered' => $data['preprocessed'],
    );

    $post = wp_get_custom_css_post( $args['stylesheet'] );
    if ( $post ) {
        $post_data['ID'] = $post->ID;
        $r               = wp_update_post( wp_slash( $post_data ), true );
    } else {
        $r = wp_insert_post( wp_slash( $post_data ), true );

        if ( ! is_wp_error( $r ) ) {
            if ( get_stylesheet() === $args['stylesheet'] ) {
                set_theme_mod( 'custom_css_post_id', $r );
            }

            $revisions = wp_get_latest_revision_id_and_total_count( $r );
            if ( ! is_wp_error( $revisions ) && 0 === $revisions['count'] ) {
                wp_save_post_revision( $r );
            }
        }
    }

    if ( is_wp_error( $r ) ) {
        return $r;
    }
    return get_post( $r );
}

注意事项

函数在 WordPress 4.7.0 版本引入，主要用于自定义 CSS 设置。
使用 update_custom_css_data 过滤器时，插件可以存储预处理 CSS，并通过 customize_value_custom_css 过滤器提供设置值。
如果文章不存在，会创建新文章并可能设置主题修改和保存修订。

📄 原文内容

Updates the custom_css post for a given theme.

Description

Inserts a custom_css post when one doesn’t yet exist.

Parameters

$cssstringrequired

CSS, stored in post_content.

$argsarrayoptional

Args.

preprocessed string
Optional. Pre-processed CSS, stored in post_content_filtered.
Normally empty string.
stylesheet string
Optional. Stylesheet (child theme) to update.
Defaults to active theme/stylesheet.

Default:array()

Return

WP_Post|WP_Error Post on success, error on failure.

Source

function wp_update_custom_css_post( $css, $args = array() ) {
	$args = wp_parse_args(
		$args,
		array(
			'preprocessed' => '',
			'stylesheet'   => get_stylesheet(),
		)
	);

	$data = array(
		'css'          => $css,
		'preprocessed' => $args['preprocessed'],
	);

	/**
	 * Filters the `css` (`post_content`) and `preprocessed` (`post_content_filtered`) args
	 * for a `custom_css` post being updated.
	 *
	 * This filter can be used by plugin that offer CSS pre-processors, to store the original
	 * pre-processed CSS in `post_content_filtered` and then store processed CSS in `post_content`.
	 * When used in this way, the `post_content_filtered` should be supplied as the setting value
	 * instead of `post_content` via a the `customize_value_custom_css` filter, for example:
	 *
	 * <code>
	 * add_filter( 'customize_value_custom_css', function( $value, $setting ) {
	 *     $post = wp_get_custom_css_post( $setting->stylesheet );
	 *     if ( $post && ! empty( $post->post_content_filtered ) ) {
	 *         $css = $post->post_content_filtered;
	 *     }
	 *     return $css;
	 * }, 10, 2 );
	 * </code>
	 *
	 * @since 4.7.0
	 * @param array $data {
	 *     Custom CSS data.
	 *
	 *     @type string $css          CSS stored in `post_content`.
	 *     @type string $preprocessed Pre-processed CSS stored in `post_content_filtered`.
	 *                                Normally empty string.
	 * }
	 * @param array $args {
	 *     The args passed into `wp_update_custom_css_post()` merged with defaults.
	 *
	 *     @type string $css          The original CSS passed in to be updated.
	 *     @type string $preprocessed The original preprocessed CSS passed in to be updated.
	 *     @type string $stylesheet   The stylesheet (theme) being updated.
	 * }
	 */
	$data = apply_filters( 'update_custom_css_data', $data, array_merge( $args, compact( 'css' ) ) );

	$post_data = array(
		'post_title'            => $args['stylesheet'],
		'post_name'             => sanitize_title( $args['stylesheet'] ),
		'post_type'             => 'custom_css',
		'post_status'           => 'publish',
		'post_content'          => $data['css'],
		'post_content_filtered' => $data['preprocessed'],
	);

	// Update post if it already exists, otherwise create a new one.
	$post = wp_get_custom_css_post( $args['stylesheet'] );
	if ( $post ) {
		$post_data['ID'] = $post->ID;
		$r               = wp_update_post( wp_slash( $post_data ), true );
	} else {
		$r = wp_insert_post( wp_slash( $post_data ), true );

		if ( ! is_wp_error( $r ) ) {
			if ( get_stylesheet() === $args['stylesheet'] ) {
				set_theme_mod( 'custom_css_post_id', $r );
			}

			// Trigger creation of a revision. This should be removed once #30854 is resolved.
			$revisions = wp_get_latest_revision_id_and_total_count( $r );
			if ( ! is_wp_error( $revisions ) && 0 === $revisions['count'] ) {
				wp_save_post_revision( $r );
			}
		}
	}

	if ( is_wp_error( $r ) ) {
		return $r;
	}
	return get_post( $r );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘update_custom_css_data’, array $data, array $args ): Filters the css (post_content) and preprocessed (post_content_filtered) args for a custom_css post being updated.

Uses	Description
wp_get_latest_revision_id_and_total_count()`wp-includes/revision.php`	Returns the latest revision ID and count of revisions for a post.
wp_get_custom_css_post()`wp-includes/theme.php`	Fetches the `custom_css` post for a given theme.
set_theme_mod()`wp-includes/theme.php`	Updates theme modification value for the active theme.
get_stylesheet()`wp-includes/theme.php`	Retrieves name of the current stylesheet.
sanitize_title()`wp-includes/formatting.php`	Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
wp_update_post()`wp-includes/post.php`	Updates a post with new post data.
wp_insert_post()`wp-includes/post.php`	Inserts or update a post.
wp_save_post_revision()`wp-includes/revision.php`	Creates a revision for the current version of a post.
wp_slash()`wp-includes/formatting.php`	Adds slashes to a string or recursively adds slashes to strings within an array.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Show 8 more Show less

Used by	Description
WP_Customize_Custom_CSS_Setting::update()`wp-includes/customize/class-wp-customize-custom-css-setting.php`	Store the CSS setting value in the custom_css custom post type for the stylesheet.

Changelog

Version	Description
4.7.0	Introduced.

云策 WordPress 开发者社区

函数文档

wp_update_custom_css_post()

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Hooks

Changelog

函数文档

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Hooks

Related

Changelog