Kindly EditDocumentationTry the editor

element-css.php

Parses and validates element-owned CSS, scopes selectors to the owner, generates output, and keeps visual settings and authored exceptions consistent.

Responsibility#

Parses and validates element-owned CSS, scopes selectors to the owner, generates output, and keeps visual settings and authored exceptions consistent.

This is an implementation reference for the released 0.9.13 module. Internal PHP helpers are not a compatibility promise for third-party callers. Prefer the documented REST, Abilities, theme, and filter contracts.

scoped-style-capture.

Module constants#

const CANTATA_EDIT_ELEMENT_CSS_MAX = 16384;
const CANTATA_EDIT_ELEMENT_CSS_RULES = 200;
const CANTATA_EDIT_ELEMENT_CSS_DECLS = 100;
const CANTATA_EDIT_ELEMENT_CSS_NESTING = 16;

These values describe this release. Defined configuration constants and generated identifiers can have different ownership; do not edit stored values directly without following the corresponding workflow.

WordPress hooks#

Operation Hook
apply_filters cantata_edit_element_css_cap
add_filter wp_insert_post_data

add_action and add_filter subscribe to a hook; do_action and apply_filters expose a hook. A subscription is not itself a new extension API. Dynamic hook names are not included in this literal inventory.

Function and method reference#

cantata_edit_can_author_css#

function cantata_edit_can_author_css( int $user_id = 0 ): bool

Who may write or change element CSS. Arbitrary CSS stays with the accounts that may already write arbitrary HTML.

Source location: includes/element-css.php:21.

cantata_edit_element_css_pseudo_classes#

function cantata_edit_element_css_pseudo_classes(): array

The pseudo-classes a selector may use. The functional ones take checked arguments (see the parser).

Source location: includes/element-css.php:27.

cantata_edit_element_css_pseudo_elements#

function cantata_edit_element_css_pseudo_elements(): array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:35.

cantata_edit_element_css_media_features#

function cantata_edit_element_css_media_features(): array

Media features, with the values each accepts ('length' for sizes; true where the bare form "(hover)" is allowed too).

Source location: includes/element-css.php:40.

cantata_edit_element_css_parse#

function cantata_edit_element_css_parse( string $css ): array

Parse element CSS. Returns [ 'ok' => bool, 'css' => canonical text ('' when not ok), 'errors' => [ [ line, message ] ], 'rules' => [ [ 'media' => '' | query, 'selectors' => [ canonical ], 'decls' => [ [ prop, value, important ] ], 'line' => n ] ] ].

Source location: includes/element-css.php:54.

cantata_edit_element_css_normalize#

function cantata_edit_element_css_normalize( string $css ): string

The canonical form of valid element CSS, or '' when it isn't valid (or says nothing).

Implementation connections: cantata_edit_element_css_parse.

Source location: includes/element-css.php:60.

cantata_edit_element_css_merge#

function cantata_edit_element_css_merge( string $existing, string $add )

Migration helper: existing element CSS with more appended (both validated). Later rules win, as in CSS.

Implementation connections: cantata_edit_element_css_parse.

Source location: includes/element-css.php:66.

cantata_edit_element_css_scope_selector#

function cantata_edit_element_css_scope_selector( string $selector, string $scope ): string

A canonical selector with "&" (outside quoted attribute values) replaced by the element's scope selector.

Source location: includes/element-css.php:75.

cantata_edit_element_css_stylesheet#

function cantata_edit_element_css_stylesheet( array $rules, string $scope ): string

The stylesheet for parsed element CSS, every selector scoped. Rules keep their authored order.

Implementation connections: cantata_edit_element_css_declarations, cantata_edit_element_css_scope_selector.

Source location: includes/element-css.php:95.

cantata_edit_element_css_declarations#

function cantata_edit_element_css_declarations( array $decls ): string

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:111.

cantata_edit_render_element_css#

function cantata_edit_render_element_css( string $html, ?callable $style_sink = null ): string

Public output: one rule set per distinct element CSS, keyed by a hash of it on a render-only data-ce-k attribute (data-ce-* is never stored: both sanitizers strip it). The scope's :not(#ke-css) lifts it over the theme's class rules; inline styles and the data-ke-* settings (!important) still win over it.

Implementation connections: cantata_edit_element_css_parse, cantata_edit_element_css_stylesheet, cantata_edit_scoped_style_capture_prefix.

Source location: includes/element-css.php:120.

cantata_edit_element_css_prepare#

function cantata_edit_element_css_prepare( string $html ): string

Before kses: every data-ke-css is rewritten in canonical form through the HTML API, which escapes it as an attribute value should be. kses splits tags on a literal ">", so a combinator left unescaped by some other client would otherwise cut the tag apart. Invalid values are removed here (the save endpoints refuse them first).

Implementation connections: cantata_edit_element_css_normalize.

Source location: includes/element-css.php:158.

cantata_edit_clean_element_css#

function cantata_edit_clean_element_css( string $html ): string

After kses: the same check again on what is actually kept.

Implementation connections: cantata_edit_element_css_prepare.

Source location: includes/element-css.php:179.

cantata_edit_element_css_values#

function cantata_edit_element_css_values( string $html ): array

Every data-ke-css value in some HTML, as written (decoded), in document order.

Source location: includes/element-css.php:184.

cantata_edit_element_css_strip#

function cantata_edit_element_css_strip( string $html, array $keep = [] ): string

Remove every data-ke-css (an account that may not write CSS, with no stored copy to compare against).

Implementation connections: cantata_edit_element_css_normalize.

Source location: includes/element-css.php:200.

cantata_edit_element_css_known#

function cantata_edit_element_css_known( string ...$sources ): array

The canonical values present in stored HTML, as a set.

Implementation connections: cantata_edit_element_css_normalize, cantata_edit_element_css_values.

Source location: includes/element-css.php:219.

cantata_edit_element_css_check_submission#

function cantata_edit_element_css_check_submission( string $html, string $source )

The save endpoints' check, before anything is cleaned: element CSS that isn't valid is refused with its reason (never dropped while the rest saves), and an account that may not write CSS may keep or delete what is stored, exactly as stored, but not add or change it.

Implementation connections: cantata_edit_can_author_css, cantata_edit_element_css_known, cantata_edit_element_css_parse, cantata_edit_element_css_strip, cantata_edit_element_css_values.

Source location: includes/element-css.php:235.

__construct#

function __construct( string $css )

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:300.

line#

function line( int $at ): int

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:305.

fail#

function fail( int $at, string $message ): void

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:309.

run#

function run(): array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:315.

result#

function result( array $errors, string $css = '' ): array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:340.

strip_comments#

function strip_comments(): void

Comments become spaces (newlines kept, so error lines stay true).

Source location: includes/element-css.php:345.

until#

function until( string $stops ): array

Read up to the next top-level stop character, skipping strings and brackets. Returns [ text, stop char or '' ].

Source location: includes/element-css.php:377.

block#

function block( string $media, bool $nested ): void

Rules until the end (top level) or a closing brace (inside @media).

Source location: includes/element-css.php:405.

short#

function short( string $text ): string

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:462.

media#

function media( string $prelude, int $at ): ?string

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Implementation connections: cantata_edit_element_css_media_features.

Source location: includes/element-css.php:467.

split_commas#

function split_commas( string $text ): array

Split on top-level commas (outside brackets and strings).

Source location: includes/element-css.php:504.

selector_list#

function selector_list( string $prelude, int $at ): ?array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:530.

complex#

function complex( string $text, string &$error, string $mode = 'top', int $depth = 0, bool $in_has = false ): ?string

One selector. $mode 'top': [context combinator]* & own-part [combinator compound]* [pseudo-element], where the subject never leaves the element: after & only " " and ">" may follow & itself, and "+" or "~" only once the selector is already inside it (& .a + .b: .b shares .a's parent, which is & or inside it). $mode 'list' (inside :is/:not/:where) and 'relative' (inside :has, which may start with > + or ~): complex selectors without & or pseudo-elements; they only decide whether a compound matches, they never choose what is styled. $depth counts functional pseudo-classes around this selector (bounded, so hostile nesting is an error, not a stack overflow). Returns the canonical text or null with $error set.

Source location: includes/element-css.php:559.

compound#

function compound( string $text, int &$i, string $mode, int $depth, bool $in_has, string &$error ): ?array

A compound selector at $i (advanced past it). Outside 'top' mode (inside a functional pseudo-class) & and pseudo-elements are not allowed; inside :has(), another :has() is not (as in CSS).

Implementation connections: cantata_edit_element_css_pseudo_classes, cantata_edit_element_css_pseudo_elements.

Source location: includes/element-css.php:636.

attribute#

function attribute( string $text, int &$i, string &$error ): ?string

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:719.

pseudo_argument#

function pseudo_argument( string $text, int &$i, string $name, int $depth, bool $in_has, string &$error ): ?string

The argument of a functional pseudo-class at $i (the "("), canonical, or null with $error.

Source location: includes/element-css.php:735.

matching_paren#

function matching_paren( string $text, int $open ): int

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:776.

declarations#

function declarations( string $body, int $at ): ?array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:796.

split_semicolons#

function split_semicolons( string $body ): array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Source location: includes/element-css.php:837.

value#

function value( string $v, string &$error ): ?string

A declaration's value, canonical, or null with $error. Strings become double-quoted with "<" and ">" as escapes; url() is checked and quoted; whitespace collapses. Outside strings only ordinary value characters are allowed.

Source location: includes/element-css.php:867.

tidy#

function tidy( string $text ): string

Collapse spacing outside strings: none after "(" or around ",", none before ")"; single spaces elsewhere.

Source location: includes/element-css.php:954.

string#

function string( string $v, int &$k, string &$error ): ?string

A quoted string at $k (advanced past it), canonical: double quotes, escapes kept, < > " written as escapes.

Source location: includes/element-css.php:977.

url#

function url( string $v, int &$k, string &$error ): ?string

url( contents at $k (advanced past the closing bracket): checked, returned double-quoted.

Source location: includes/element-css.php:1015.

serialize#

function serialize(): string

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Implementation connections: cantata_edit_element_css_declarations.

Source location: includes/element-css.php:1056.

About this page

Documents Kindly Edit 0.9.16. Source: includes/element-css.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.