Skip to content

Background: Add a PHP helper for block support classes and styles - #84209

Open
aaronrobertshaw wants to merge 7 commits into
trunkfrom
update/background-classes-and-styles-php-helper
Open

Background: Add a PHP helper for block support classes and styles#84209
aaronrobertshaw wants to merge 7 commits into
trunkfrom
update/background-classes-and-styles-php-helper

Conversation

@aaronrobertshaw

@aaronrobertshaw aaronrobertshaw commented Oct 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Follows up on #83122.
Core backport: wordpress-develop#14094.

Related:

What?

Adds a PHP helper that turns background attributes into classes and inline styles, like the JS getBackgroundClassesAndStyles().

wp_get_background_classes_and_styles( $block_attributes );
// array( 'class' => 'has-background', 'style' => 'background-image:var(--wp--preset--gradient--vivid-cyan-blue-to-vivid-purple);' )

Why?

Five blocks copied the background block support's image defaults and has-background rule, and the copies had started to drift. Button had the first copy. Four blocks that merged since added their own:

Tab List already uses the JS helper.

How?

The helper only builds output. Callers pass what they support.

  • Image defaults: cover, and a centred position for contain
  • has-background: for an image or gradient not clipped to text
  • Block support: keeps its checks
  • Button, Post Navigation Link, Icon: ignore the clip
  • Post Navigation Link: CSS order unchanged
  • Search: passes only the gradient
  • Build: added to prefixFunctions

No style changes for values the editor saves. has-background can sit in a different place in the class list.

Testing Instructions

  1. Add a Button with a contain background image and a gradient.
  2. Add a Group with a positioned background image and a gradient.
  3. On a single post template, add a Post Navigation Link with a background image and a border colour.
  4. Add an Icon with a preset gradient.
  5. Add a Search block with a gradient, with the button inside and outside.
  6. Compare the front end markup with trunk. Styles should match.
  7. Add a Heading with a gradient clipped to text. It has the clip styles and no has-background.

Use of AI Tools

Implemented and tested by a Claude Code agent.

@aaronrobertshaw aaronrobertshaw added [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Type] Enhancement A suggestion for improvement. labels Oct 8, 2026
@aaronrobertshaw aaronrobertshaw self-assigned this Oct 8, 2026
@aaronrobertshaw aaronrobertshaw added [Package] Block library /packages/block-library Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json labels Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026 •
edited
Loading

Copy link
Copy Markdown

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: 0 B

Total Size: 9.05 MB

5e11cb4 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 2ae4bb8 trunk % Change
timeToFirstByte 53.3 ms +12.29% -4.69% 52.8 ms +9.66% -2.37% 0.95%
largestContentfulPaint 92 ms +6.52% -8.7% 88 ms +6.82% -4.55% 4.55%
lcpMinusTtfb 33.4 ms +25% -2.84% 32.65 ms +14.4% -1.53% 2.3%
wpBeforeTemplate 28.35 ms +14.29% -2.08% 28.23 ms +12.58% -1.17% 0.43%
wpTemplate 21.47 ms +1.68% -8.24% 20.42 ms +6.81% -1.76% 5.14%
wpTotal 49.84 ms +12.56% -5.12% 49.23 ms +9.65% -2.66% 1.24%
wpMemoryUsage 7.65 MB +0% -0% 7.61 MB +0% -0% 0.46%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 2ae4bb8 trunk % Change
timeToFirstByte 41.1 ms +10.71% -1.7% 45.1 ms +7.32% -1.88% -8.87%
largestContentfulPaint 90 ms +2.22% -2.22% 100 ms +4% -4% -10%
lcpMinusTtfb 47.65 ms +1.47% -1.05% 54.25 ms +2.4% -4.24% -12.17%
wpBeforeTemplate 26.5 ms +11.43% -2.45% 26.11 ms +3.49% -1.53% 1.49%
wpTemplate 12.02 ms +5.66% -2.41% 15.93 ms +4.33% -2.2% -24.54%
wpTotal 38.33 ms +11.17% -1.67% 41.91 ms +7.28% -1.41% -8.54%
wpMemoryUsage 6.23 MB +0% -0% 6.30 MB +0% -0% -1.19%
wpDbQueries 9 +0% -0% 13 +0% -0% -30.77%

media-processing

Metric 2ae4bb8 trunk % Change
mediaProcessingJpeg 396.73 ms +2.06% -0.32% 397.34 ms +0.77% -0.11% -0.15%
mediaProcessingAvif 6070.41 ms +0.12% -0.52% 6064.11 ms +0.21% -0.17% 0.1%
mediaProcessingJpegToAvif 4192.43 ms +0.08% -0.19% 4201.8 ms +0.1% -0.04% -0.22%

media-upload

Metric 2ae4bb8 trunk % Change
jpegUploadProcessing 1682.44 ms +15.28% -14.19% 1423.98 ms +2.12% -0.48% 18.15%
pngUploadProcessing 205.56 ms +3.7% -17.46% 195.64 ms +8.51% -10.81% 5.07%
largeJpegUploadProcessing 1427.49 ms +0.92% -1.01% 1412.51 ms +0.61% -0.72% 1.06%
multipleImageUploadProcessing 2013.61 ms +1.96% -21.44% 1580.63 ms +1% -1.02% 27.39%

post-editor

Metric 2ae4bb8 trunk % Change
serverResponse 494.79 ms +6.07% -1.35% 489.64 ms +13.12% -4% 1.05%
firstPaint 428.42 ms +26.51% -25.34% 313.13 ms +38.66% -19.25% 36.82%
domContentLoaded 1225.21 ms +3.49% -2.91% 1270.5 ms +2.63% -4.31% -3.56%
loaded 1226.55 ms +3.5% -2.9% 1271.78 ms +2.65% -4.3% -3.56%
firstContentfulPaint 535.69 ms +1.27% -2.82% 550.93 ms +2.66% -21.19% -2.77%
firstBlock 3744.15 ms +1.79% -5.34% 3904.77 ms +3.05% -5.88% -4.11%
type 19.92 ms +4.57% -2.66% 20.8 ms +7.69% -4.81% -4.23%
typeWithoutInspector 21.34 ms +7.59% -1.17% 21.5 ms +2.65% -1.3% -0.74%
typeWithTopToolbar 26.14 ms +5.47% -3.4% 26.72 ms +5.54% -10.63% -2.17%
typeContainer 9.68 ms +4.86% -9.92% 9.79 ms +1.02% -13.38% -1.12%
focus 133.1 ms +5.42% -2.11% 129.79 ms +4.81% -4.33% 2.55%
firstFocus 285.81 ms +0% -0% 264.61 ms +0% -0% 8.01%
selectAll 607.13 ms +7.09% -0.97% 606.78 ms +1.87% -2.07% 0.06%
listViewOpen 90.03 ms +3.01% -12.1% 85.45 ms +7.41% -4.38% 5.36%
inserterOpen 40.79 ms +16.35% -7.4% 44.41 ms +7.88% -7.03% -8.15%
inserterHover 12.36 ms +7.28% -6.15% 12.38 ms +8.89% -7.03% -0.16%
inserterSearch 8.6 ms +1.51% -14.77% 8.13 ms +16.97% -4.43% 5.78%
loadPatterns 719.44 ms +2.64% -7.27% 678.8 ms +1.26% -2.63% 5.99%
wpTotal 485.24 ms +6.26% -1.35% 480.07 ms +13.32% -4.12% 1.08%
wpMemoryUsage 14.69 MB +0% -0% 14.65 MB +0% -0% 0.26%
wpDbQueries 55 +0% -1.82% 54.5 +0.92% -0.92% 0.92%

site-editor

Metric 2ae4bb8 trunk % Change
serverResponse 506.92 ms +4% -6.54% 487.52 ms +4.48% -2.58% 3.98%
firstPaint 266.01 ms +8.71% -6.08% 264.18 ms +15.14% -5.79% 0.69%
domContentLoaded 1254.6 ms +1.23% -1.18% 1242.72 ms +1.76% -1.5% 0.96%
loaded 1255.86 ms +1.2% -1.18% 1243.93 ms +1.75% -1.49% 0.96%
firstContentfulPaint 501.78 ms +4.18% -5.23% 507.65 ms +2.1% -4.22% -1.16%
firstBlock 4738.65 ms +0.31% -0.81% 4666.15 ms +0.36% -0.88% 1.55%
type 18.6 ms +4.25% -6.02% 18.7 ms +2.62% -4.33% -0.53%
navigate 128.62 ms +3% -2.36% 125.72 ms +10.08% -3.79% 2.31%
loadPatterns 1223.15 ms +3.62% -12.42% 1203.91 ms +5.43% -8.68% 1.6%
loadPages 964.73 ms +5.24% -3.8% 983.82 ms +3.01% -3.83% -1.94%
wpTotal 496.88 ms +4.07% -6.58% 478.18 ms +4.54% -2.51% 3.91%
wpMemoryUsage 12.70 MB +0% -0% 12.67 MB +0% -0% 0.29%
wpDbQueries 44 +2.27% -0% 44 +2.27% -0% 0%

5e11cb4 Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Regression: updating a specific option will only change its value and will not corrupt others in /test/e2e/specs/editor/various/core-settings.spec.js, passed after 1 failed attempt. 
Error: expect(received).toStrictEqual(expected) // deep equality

- Expected  - 1
+ Received  + 1

  Array [
    "rewrite_rules",
-   "SERIALIZED DATA",
+   "",
  ]
    at forEach (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:46:26)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:43:35
keeps the blocks selected after dropping a multi-selection in /test/e2e/specs/editor/various/draggable-blocks.spec.js, passed after 1 failed attempt. 
TypeError: Cannot read properties of null (reading 'y')
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:824:57
    at dragSelectionBelowLanding (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:823:3)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:908:3
refuses the drop and uploads nothing in /test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js, passed after 1 failed attempt. 
Error: expect(received).toHaveLength(expected)

Expected length: 0
Received length: 1
Received array:  [{"_links": {"about": [{"href": "http://localhost:8889/wp-json/wp/v2/types/attachment"}], "author": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/users/1"}], "collection": [{"href": "http://localhost:8889/wp-json/wp/v2/media"}], "curies": [{"href": "https://api.w.org/{rel}", "name": "wp", "templated": true}], "replies": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/comments?post=223"}], "self": [{"href": "http://localhost:8889/wp-json/wp/v2/media/223", "targetHints": {"allow": ["GET", "POST", "PUT", "PATCH", "DELETE"]}}], "wp:attached-to": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/posts/222", "id": 222, "post_type": "post"}]}, "alt_text": "", "author": 1, "caption": {"rendered": ""}, "class_list": ["post-223", "attachment", "type-attachment", "status-inherit", "hentry", "entry"], "comment_status": "open", "date": "2026-10-21T12:57:58", "date_gmt": "2026-10-21T12:57:58", "description": {"rendered": "<p class=\"attachment\"><a href='http://localhost:8889/wp-content/uploads/2026/10/8184ad96-379d-4329-9e7e-afa5384db225.png'><img loading=\"lazy\" decoding=\"async\" width=\"10\" height=\"10\" src=\"http://localhost:8889/wp-content/uploads/2026/10/8184ad96-379d-4329-9e7e-afa5384db225.png\" class=\"attachment-medium size-medium\" alt=\"\" style=\"width:100%;height:100%;max-width:10px;\" /></a></p>
"}, "featured_media": 0, "filename": "8184ad96-379d-4329-9e7e-afa5384db225.png", "filesize": 80, "guid": {"rendered": "http://localhost:8889/wp-content/uploads/2026/10/8184ad96-379d-4329-9e7e-afa5384db225.png"}, "id": 223, "link": "http://localhost:8889/?attachment_id=223", "media_details": {"file": "2026/10/8184ad96-379d-4329-9e7e-afa5384db225.png", "filesize": 80, "height": 10, "image_meta": {"alt": "", "aperture": "0", "camera": "", "caption": "", "copyright": "", "created_timestamp": "0", "credit": "", "focal_length": "0", "iso": "0", "keywords": [], "orientation": "0", "shutter_speed": "0", "title": ""}, "sizes": {}, "width": 10}, "media_type": "image", "meta": [], "mime_type": "image/png", "modified": "2026-10-21T12:57:58", "modified_gmt": "2026-10-21T12:57:58", "ping_status": "closed", "post": 222, "slug": "8184ad96-379d-4329-9e7e-afa5384db225", "source_url": "http://localhost:8889/wp-content/uploads/2026/10/8184ad96-379d-4329-9e7e-afa5384db225.png", "status": "inherit", "template": "", "title": {"rendered": "8184ad96-379d-4329-9e7e-afa5384db225"}, "type": "attachment"}]
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js:71:45

5e11cb4 Run

@aaronrobertshaw
aaronrobertshaw force-pushed the update/background-classes-and-styles-php-helper branch 2 times, most recently from 3e80bc4 to e2d29dc Compare October 8, 2026 05:56
@aaronrobertshaw aaronrobertshaw added [Type] Code Quality Issues or PRs that relate to code quality and removed [Type] Enhancement A suggestion for improvement. Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json labels Oct 8, 2026
@github-actions github-actions Bot added the [Package] Block editor /packages/block-editor label Oct 8, 2026
@aaronrobertshaw aaronrobertshaw mentioned this pull request Oct 8, 2026
Draft
@aaronrobertshaw
aaronrobertshaw force-pushed the update/background-classes-and-styles-php-helper branch from 98b4dba to 3848408 Compare October 8, 2026 12:11
@aaronrobertshaw aaronrobertshaw mentioned this pull request Oct 13, 2026
Open
28 of 77 tasks
@aaronrobertshaw
aaronrobertshaw force-pushed the update/background-classes-and-styles-php-helper branch 4 times, most recently from d2d345d to 493a0bc Compare October 20, 2026 05:13
@aaronrobertshaw
aaronrobertshaw force-pushed the update/background-classes-and-styles-php-helper branch from 493a0bc to 52404fb Compare October 21, 2026 05:21
This was referenced Oct 21, 2026
Open
Open
Open
@aaronrobertshaw
Background: Add a PHP helper for block support classes and styles
475424b
@aaronrobertshaw
Address review feedback
21e5cb2
@aaronrobertshaw
Add backport changelog entry
e0b998a
@aaronrobertshaw
Filter by removing values before calling the helper
f60ca03
@aaronrobertshaw
Use named support and skip variables, and filter the attributes in place
21584ce
@aaronrobertshaw
Use the background helper in Post Navigation Link, Icon, Tab List and…
246ee4d 
… Search
@aaronrobertshaw
Guard non-array attributes in the background helper and trim its tests
5e11cb4 
Return early when the block attributes are not an array, like the colour
helper. Point the text clip comments at the helper and give the unset()
guard its reason. Drop tests that repeat block support coverage or lock in
PHP-only behaviour, and keep one Button test proving it ignores the clip.
@aaronrobertshaw
aaronrobertshaw force-pushed the update/background-classes-and-styles-php-helper branch from 9610ccd to 5e11cb4 Compare October 21, 2026 12:41
@aaronrobertshaw
aaronrobertshaw marked this pull request as ready for review October 21, 2026 13:16

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ramonjd ramonjd Awaiting requested review from ramonjd
@andrewserong andrewserong Awaiting requested review from andrewserong
@talldan talldan Awaiting requested review from talldan
@tellthemachines tellthemachines Awaiting requested review from tellthemachines tellthemachines is a code owner
@spacedmonkey spacedmonkey Awaiting requested review from spacedmonkey spacedmonkey is a code owner
@fabiankaegy fabiankaegy Awaiting requested review from fabiankaegy fabiankaegy is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@aaronrobertshaw aaronrobertshaw

Labels

[Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Package] Block editor /packages/block-editor [Package] Block library /packages/block-library [Type] Code Quality Issues or PRs that relate to code quality

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@aaronrobertshaw