Skip to content

Block Supports: Add PHP helpers for block support classes and styles #14094

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Draft
aaronrobertshaw wants to merge 2 commits into
base: trunk
Choose a base branch
from
Draft

Block Supports: Add PHP helpers for block support classes and styles #14094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6d8ee2a
Editor: Add a background clip block support
aaronrobertshaw Sep 11, 2026
fee7818
Block Supports: Add PHP helpers for block support classes and styles.
aaronrobertshaw Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 84 additions & 25 deletions src/wp-includes/block-supports/background.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,60 @@ function wp_register_background_support( $block_type ) {
}
}

/**
* Returns background classes and inline styles for block attributes, like the JS
* `getBackgroundClassesAndStyles()`. Does not check block support or skipped
* serialization.
*
* @since 7.2.0
*
* @param array $block_attributes Block attributes.
* @return array Array with `class` and `style` keys, each present only when non-empty.
*/
function wp_get_background_classes_and_styles( $block_attributes ) {
$background = $block_attributes['style']['background'] ?? null;

if ( ! is_array( $background ) ) {
return array();
}

$background_styles = array(
'backgroundImage' => $background['backgroundImage'] ?? null,
'backgroundSize' => $background['backgroundSize'] ?? null,
'backgroundPosition' => $background['backgroundPosition'] ?? null,
'backgroundRepeat' => $background['backgroundRepeat'] ?? null,
'backgroundAttachment' => $background['backgroundAttachment'] ?? null,
'gradient' => $background['gradient'] ?? null,
'backgroundClip' => $background['backgroundClip'] ?? null,
);

if ( ! empty( $background_styles['backgroundImage'] ) ) {
$background_styles['backgroundSize'] ??= 'cover';
if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
$background_styles['backgroundPosition'] = '50% 50%';
}
}

$styles = wp_style_engine_get_styles( array( 'background' => $background_styles ) );

if ( empty( $styles['css'] ) ) {
return array();
}

$classes_and_styles = array();

$has_background = ! empty( $background_styles['backgroundImage'] ) || ! empty( $background_styles['gradient'] );

// A text clip paints the glyphs, not the box, so there is no block background.
if ( $has_background && 'text' !== $background_styles['backgroundClip'] ) {
$classes_and_styles['class'] = 'has-background';
}

$classes_and_styles['style'] = $styles['css'];

return $classes_and_styles;
}

/**
* Renders the background styles to the block wrapper.
* This block support uses the `render_block` hook to ensure that
Expand All @@ -44,6 +98,7 @@ function wp_register_background_support( $block_type ) {
* @since 6.6.0 Removed requirement for `backgroundImage.source`. A file/url is the default.
* @since 6.7.0 Added support for `backgroundAttachment` output.
* @since 7.1.0 Added support for `background.gradient` output.
* @since 7.2.0 Added support for `background.backgroundClip` output.
*
* @access private
*
Expand All @@ -56,9 +111,10 @@ function wp_render_background_support( $block_content, $block ) {
$block_attributes = ( isset( $block['attrs'] ) && is_array( $block['attrs'] ) ) ? $block['attrs'] : array();
$has_background_image_support = block_has_support( $block_type, array( 'background', 'backgroundImage' ), false );
$has_background_gradient_support = block_has_support( $block_type, array( 'background', 'gradient' ), false );
$has_background_clip_support = block_has_support( $block_type, array( 'background', 'backgroundClip' ), false );

if (
( ! $has_background_image_support && ! $has_background_gradient_support ) ||
( ! $has_background_image_support && ! $has_background_gradient_support && ! $has_background_clip_support ) ||
! isset( $block_attributes['style']['background'] )
) {
return $block_content;
Expand All @@ -67,51 +123,54 @@ function wp_render_background_support( $block_content, $block ) {
// Check serialization skip for each feature individually.
$skip_background_image = ! $has_background_image_support || wp_should_skip_block_supports_serialization( $block_type, 'background', 'backgroundImage' );
$skip_background_gradient = ! $has_background_gradient_support || wp_should_skip_block_supports_serialization( $block_type, 'background', 'gradient' );
$skip_background_clip = ! $has_background_clip_support || wp_should_skip_block_supports_serialization( $block_type, 'background', 'backgroundClip' );

if ( $skip_background_image && $skip_background_gradient ) {
if ( $skip_background_image && $skip_background_gradient && $skip_background_clip ) {
return $block_content;
}

$background_styles = array();

if ( ! $skip_background_image ) {
$background_styles['backgroundImage'] = $block_attributes['style']['background']['backgroundImage'] ?? null;
$background_styles['backgroundSize'] = $block_attributes['style']['background']['backgroundSize'] ?? null;
$background_styles['backgroundPosition'] = $block_attributes['style']['background']['backgroundPosition'] ?? null;
$background_styles['backgroundRepeat'] = $block_attributes['style']['background']['backgroundRepeat'] ?? null;
$background_styles['backgroundAttachment'] = $block_attributes['style']['background']['backgroundAttachment'] ?? null;

if ( ! empty( $background_styles['backgroundImage'] ) ) {
$background_styles['backgroundSize'] ??= 'cover';
// The helper ignores a non-array background, so only an array needs filtering.
if ( is_array( $block_attributes['style']['background'] ) ) {
if ( $skip_background_image ) {
unset(
$block_attributes['style']['background']['backgroundImage'],
$block_attributes['style']['background']['backgroundSize'],
$block_attributes['style']['background']['backgroundPosition'],
$block_attributes['style']['background']['backgroundRepeat'],
$block_attributes['style']['background']['backgroundAttachment']
);
}

// If the background size is set to `contain` and no position is set, set the position to `center`.
if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
$background_styles['backgroundPosition'] = '50% 50%';
}
if ( $skip_background_gradient ) {
unset( $block_attributes['style']['background']['gradient'] );
}
}

if ( ! $skip_background_gradient ) {
$background_styles['gradient'] = $block_attributes['style']['background']['gradient'] ?? null;
// Serialized values only, so a skipped clip cannot drop `has-background`.
if ( $skip_background_clip ) {
unset( $block_attributes['style']['background']['backgroundClip'] );
}
}

$styles = wp_style_engine_get_styles( array( 'background' => $background_styles ) );
$styles = wp_get_background_classes_and_styles( $block_attributes );

if ( ! empty( $styles['css'] ) ) {
if ( ! empty( $styles['style'] ) ) {
// Inject background styles to the first element, presuming it's the wrapper, if it exists.
$tags = new WP_HTML_Tag_Processor( $block_content );

if ( $tags->next_tag() ) {
$existing_style = $tags->get_attribute( 'style' );
if ( is_string( $existing_style ) && '' !== $existing_style ) {
$separator = str_ends_with( $existing_style, ';' ) ? '' : ';';
$updated_style = "{$existing_style}{$separator}{$styles['css']}";
$updated_style = "{$existing_style}{$separator}{$styles['style']}";
} else {
$updated_style = $styles['css'];
$updated_style = $styles['style'];
}

$tags->set_attribute( 'style', $updated_style );
$tags->add_class( 'has-background' );

if ( ! empty( $styles['class'] ) ) {
$tags->add_class( $styles['class'] );
}
}

return $tags->get_updated_html();
Expand Down
150 changes: 92 additions & 58 deletions src/wp-includes/block-supports/border.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,76 +52,110 @@ function wp_apply_border_support( $block_type, $block_attributes ) {
return array();
}

$border_block_styles = array();
$has_border_color_support = wp_has_border_feature_support( $block_type, 'color' );
$has_border_width_support = wp_has_border_feature_support( $block_type, 'width' );

// Border radius.
if (
wp_has_border_feature_support( $block_type, 'radius' ) &&
isset( $block_attributes['style']['border']['radius'] ) &&
! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'radius' )
) {
$border_radius = $block_attributes['style']['border']['radius'];

if ( is_numeric( $border_radius ) ) {
$border_radius .= 'px';
}
$has_border_color_support = wp_has_border_feature_support( $block_type, 'color' );
$has_border_radius_support = wp_has_border_feature_support( $block_type, 'radius' );
$has_border_style_support = wp_has_border_feature_support( $block_type, 'style' );
$has_border_width_support = wp_has_border_feature_support( $block_type, 'width' );
$skip_color = wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'color' );
$skip_radius = wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'radius' );
$skip_style = wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'style' );
$skip_width = wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'width' );

// The helper reads only `style.border`, so a non-array value counts as no border styles.
if ( ! isset( $block_attributes['style']['border'] ) || ! is_array( $block_attributes['style']['border'] ) ) {
unset( $block_attributes['style'] );
}

if ( ! $has_border_radius_support || $skip_radius ) {
unset( $block_attributes['style']['border']['radius'] );
}

$border_block_styles['radius'] = $border_radius;
if ( ! $has_border_style_support || $skip_style ) {
unset( $block_attributes['style']['border']['style'] );
}

// Border style.
if (
wp_has_border_feature_support( $block_type, 'style' ) &&
isset( $block_attributes['style']['border']['style'] ) &&
! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'style' )
) {
$border_block_styles['style'] = $block_attributes['style']['border']['style'];
if ( ! $has_border_width_support || $skip_width ) {
unset( $block_attributes['style']['border']['width'] );
}

// Border width.
if (
$has_border_width_support &&
isset( $block_attributes['style']['border']['width'] ) &&
! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'width' )
) {
$border_width = $block_attributes['style']['border']['width'];
if ( ! $has_border_color_support || $skip_color ) {
unset( $block_attributes['style']['border']['color'], $block_attributes['borderColor'] );
}

// Sides are filtered by skipped serialization only, not by feature support.
foreach ( array( 'top', 'right', 'bottom', 'left' ) as $side ) {
$has_side = isset( $block_attributes['style']['border'][ $side ] ) && is_array( $block_attributes['style']['border'][ $side ] );

if ( ! $has_side || ( ! $has_border_color_support && ! $has_border_width_support ) ) {
unset( $block_attributes['style']['border'][ $side ] );
continue;
}

if ( $skip_width ) {
unset( $block_attributes['style']['border'][ $side ]['width'] );
}

// This check handles original unitless implementation.
if ( is_numeric( $border_width ) ) {
$border_width .= 'px';
if ( $skip_color ) {
unset( $block_attributes['style']['border'][ $side ]['color'] );
}

$border_block_styles['width'] = $border_width;
}

// Border color.
if (
$has_border_color_support &&
! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'color' )
) {
$preset_border_color = array_key_exists( 'borderColor', $block_attributes ) ? "var:preset|color|{$block_attributes['borderColor']}" : null;
$custom_border_color = $block_attributes['style']['border']['color'] ?? null;
$border_block_styles['color'] = $preset_border_color ? $preset_border_color : $custom_border_color;
}

// Generates styles for individual border sides.
if ( $has_border_color_support || $has_border_width_support ) {
foreach ( array( 'top', 'right', 'bottom', 'left' ) as $side ) {
$border = $block_attributes['style']['border'][ $side ] ?? null;
$border_side_values = array(
'width' => isset( $border['width'] ) && ! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'width' ) ? $border['width'] : null,
'color' => isset( $border['color'] ) && ! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'color' ) ? $border['color'] : null,
'style' => isset( $border['style'] ) && ! wp_should_skip_block_supports_serialization( $block_type, '__experimentalBorder', 'style' ) ? $border['style'] : null,
);
$border_block_styles[ $side ] = $border_side_values;
if ( $skip_style ) {
unset( $block_attributes['style']['border'][ $side ]['style'] );
}
}

// Collect classes and styles.
return wp_get_border_classes_and_styles( $block_attributes );
}

/**
* Returns border classes and inline styles for block attributes, like the JS
* `getBorderClassesAndStyles()`. Does not check block support or skipped
* serialization.
*
* @since 7.2.0
*
* @param array $block_attributes Block attributes.
* @return array Array with `class` and `style` keys, each present only when non-empty.
*/
function wp_get_border_classes_and_styles( $block_attributes ) {
if ( ! is_array( $block_attributes ) ) {
return array();
}

$border = isset( $block_attributes['style']['border'] ) && is_array( $block_attributes['style']['border'] )
? $block_attributes['style']['border']
: array();
$border_styles = array();

// Unitless radius and width are from the original implementation.
if ( isset( $border['radius'] ) ) {
$border_styles['radius'] = is_numeric( $border['radius'] ) ? "{$border['radius']}px" : $border['radius'];
}

if ( isset( $border['style'] ) ) {
$border_styles['style'] = $border['style'];
}

if ( isset( $border['width'] ) ) {
$border_styles['width'] = is_numeric( $border['width'] ) ? "{$border['width']}px" : $border['width'];
}

$preset_border_color = array_key_exists( 'borderColor', $block_attributes ) ? "var:preset|color|{$block_attributes['borderColor']}" : null;
$border_styles['color'] = $preset_border_color ? $preset_border_color : ( $border['color'] ?? null );

foreach ( array( 'top', 'right', 'bottom', 'left' ) as $side ) {
if ( ! isset( $border[ $side ] ) || ! is_array( $border[ $side ] ) ) {
continue;
}
$border_styles[ $side ] = array(
'width' => $border[ $side ]['width'] ?? null,
'color' => $border[ $side ]['color'] ?? null,
'style' => $border[ $side ]['style'] ?? null,
);
}

$attributes = array();
$styles = wp_style_engine_get_styles( array( 'border' => $border_block_styles ) );
$styles = wp_style_engine_get_styles( array( 'border' => $border_styles ) );

if ( ! empty( $styles['classnames'] ) ) {
$attributes['class'] = $styles['classnames'];
Expand Down
Loading
Loading