<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[59328] trunk/src/wp-includes/class-wp-theme-json.php: Docs: Correct DocBlock formatting in `wp-includes/class-wp-theme-json.php`.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/59328">59328</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/59328","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>SergeyBiryukov</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2024-10-30 23:50:03 +0000 (Wed, 30 Oct 2024)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Docs: Correct DocBlock formatting in `wp-includes/class-wp-theme-json.php`.
Follow-up to <a href="https://core.trac.wordpress.org/changeset/52049">[52049]</a>, <a href="https://core.trac.wordpress.org/changeset/54118">[54118]</a>, <a href="https://core.trac.wordpress.org/changeset/54162">[54162]</a>, <a href="https://core.trac.wordpress.org/changeset/55008">[55008]</a>, <a href="https://core.trac.wordpress.org/changeset/55349">[55349]</a>, <a href="https://core.trac.wordpress.org/changeset/55959">[55959]</a>, <a href="https://core.trac.wordpress.org/changeset/55986">[55986]</a>, <a href="https://core.trac.wordpress.org/changeset/56058">[56058]</a>, <a href="https://core.trac.wordpress.org/changeset/57496">[57496]</a>, <a href="https://core.trac.wordpress.org/changeset/58354">[58354]</a>, <a href="https://core.trac.wordpress.org/changeset/58413">[58413]</a>.
Props mukesh27, ramonopoly.
See <a href="https://core.trac.wordpress.org/ticket/62279">#62279</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesclasswpthemejsonphp">trunk/src/wp-includes/class-wp-theme-json.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesclasswpthemejsonphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/class-wp-theme-json.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/class-wp-theme-json.php 2024-10-30 23:45:53 UTC (rev 59327)
+++ trunk/src/wp-includes/class-wp-theme-json.php 2024-10-30 23:50:03 UTC (rev 59328)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -227,7 +227,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.5.0 Added `aspect-ratio` property.
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.6.0 Added `background-[image|position|repeat|size]` properties.
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.7.0 Added `background-attachment` property.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @var array
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const PROPERTIES_METADATA = array(
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -307,7 +306,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.2.0
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.6.0 Added background-image properties.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @var array
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const INDIRECT_PROPERTIES_METADATA = array(
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -339,6 +337,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * setting key.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 5.9.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @var array
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const PROTECTED_PROPERTIES = array(
</span><span class="cx" style="display: block; padding: 0 10px"> 'spacing.blockGap' => array( 'spacing', 'blockGap' ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -475,7 +474,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * The valid properties for fontFamilies under settings key.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.5.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @var array
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const FONT_FAMILY_SCHEMA = array(
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -517,7 +515,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.3.0 Added support for `typography.textColumns`.
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.5.0 Added support for `dimensions.aspectRatio`.
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.6.0 Added `background` sub properties to top-level only.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @var array
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const VALID_STYLES = array(
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -591,6 +588,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.1.0
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.2.0 Added support for ':link' and ':any-link'.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @var array
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> const VALID_ELEMENT_PSEUDO_SELECTORS = array(
</span><span class="cx" style="display: block; padding: 0 10px"> 'link' => array( ':link', ':any-link', ':visited', ':hover', ':focus', ':active' ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -938,7 +936,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @return array The sanitized output.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> protected static function sanitize( $input, $valid_block_names, $valid_element_names, $valid_variations ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><span class="cx" style="display: block; padding: 0 10px"> $output = array();
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( ! is_array( $input ) ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -2311,7 +2308,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $theme_json Theme JSON array.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $selector The style block selector.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param boolean $use_root_padding Whether to add custom properties at root level.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @return array Returns the modified $declarations.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @return array Returns the modified $declarations.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> protected static function compute_style_properties( $styles, $settings = array(), $properties = null, $theme_json = null, $selector = null, $use_root_padding = null ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( empty( $styles ) ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -2815,7 +2812,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Fixed custom CSS output in block style variations.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $block_metadata Metadata about the block to get styles for.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @return string Styles for the block.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> public function get_styles_for_block( $block_metadata ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -3040,9 +3036,9 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $use_root_padding = isset( $this->theme_json['settings']['useRootPaddingAwareAlignments'] ) && true === $this->theme_json['settings']['useRootPaddingAwareAlignments'];
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /*
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * If there are content and wide widths in theme.json, output them
- * as custom properties on the body element so all blocks can use them.
- */
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * If there are content and wide widths in theme.json, output them
+ * as custom properties on the body element so all blocks can use them.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( isset( $settings['layout']['contentSize'] ) || isset( $settings['layout']['wideSize'] ) ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $content_size = isset( $settings['layout']['contentSize'] ) ? $settings['layout']['contentSize'] : $settings['layout']['wideSize'];
</span><span class="cx" style="display: block; padding: 0 10px"> $content_size = static::is_safe_css_declaration( 'max-width', $content_size ) ? $content_size : 'initial';
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -3053,13 +3049,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /*
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * Reset default browser margin on the body element.
- * This is set on the body selector **before** generating the ruleset
- * from the `theme.json`. This is to ensure that if the `theme.json` declares
- * `margin` in its `spacing` declaration for the `body` element then these
- * user-generated values take precedence in the CSS cascade.
- * @link https://github.com/WordPress/gutenberg/issues/36147.
- */
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Reset default browser margin on the body element.
+ * This is set on the body selector **before** generating the ruleset
+ * from the `theme.json`. This is to ensure that if the `theme.json` declares
+ * `margin` in its `spacing` declaration for the `body` element then these
+ * user-generated values take precedence in the CSS cascade.
+ * @link https://github.com/WordPress/gutenberg/issues/36147.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $css .= ':where(body) { margin: 0; }';
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( $use_root_padding ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -3469,8 +3465,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.6.0 Updated to allow variation element styles and $origin parameter.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $theme_json Structure to sanitize.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param string $origin Optional. What source of data this object represents.
- * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param string $origin Optional. What source of data this object represents.
+ * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @return array Sanitized structure.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> public static function remove_insecure_properties( $theme_json, $origin = 'theme' ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4202,6 +4198,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * For example, `var:preset|color|vivid-green-cyan` becomes `var(--wp--preset--color--vivid-green-cyan)`.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.3.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ *
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param string $value The variable such as var:preset|color|vivid-green-cyan to convert.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return string The converted variable.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4227,7 +4224,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * It is recursive and modifies the input in-place.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.3.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param array $tree Input to process.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ *
+ * @param array $tree Input to process.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @return array The modified $tree.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> private static function resolve_custom_css_format( $tree ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4251,7 +4249,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param object $block_type The block type.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $root_selector The block's root selector.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @return array The custom selectors set by the block.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> protected static function get_block_selectors( $block_type, $root_selector ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4310,9 +4307,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param object $metadata The related block metadata containing selectors.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param object $node A merged theme.json node for block or variation.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @return array The style declarations for the node's features with custom
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * selectors.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * selectors.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> protected function get_feature_declarations_for_node( $metadata, &$node ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $declarations = array();
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4470,8 +4466,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Resolves the values of CSS variables in the given styles.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 6.3.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ *
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param WP_Theme_JSON $theme_json The theme json resolver.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- *
</del><span class="cx" style="display: block; padding: 0 10px"> * @return WP_Theme_JSON The $theme_json with resolved variables.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> public static function resolve_variables( $theme_json ) {
</span></span></pre>
</div>
</div>
</body>
</html>