element-php.php
Stores immutable PHP source resources privately, checks native code permissions and signatures, validates and stages code, and renders authorized owners with explicit execution guards.
Responsibility#
Stores immutable PHP source resources privately, checks native code permissions and signatures, validates and stages code, and renders authorized owners with explicit execution guards.
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.
Related modules#
blocks, editor, element-js, render, sanitize.
Module constants#
const CANTATA_EDIT_ELEMENT_PHP_MAX = 16384;
const CANTATA_EDIT_ELEMENT_PHP_COUNT = 32;
const CANTATA_EDIT_ELEMENT_PHP_OUTPUT = 262144;
const CANTATA_EDIT_ELEMENT_PHP_TYPE = 'cantata_php_code';
const CANTATA_EDIT_ELEMENT_PHP_REF = '/^p1\.([0-9a-f]{32})\.([0-9a-f]{64})$/D';
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.
Literal option and cache keys#
cantata_edit_element_php_log, cantata_edit_element_php_stopped. These are direct literal keys found in this module; dynamically constructed keys and metadata constants are covered by the storage reference.
WordPress hooks#
| Operation | Hook |
|---|---|
apply_filters |
cantata_edit_can_author_php |
add_action |
init |
add_filter |
wxr_export_skip_postmeta |
apply_filters |
cantata_edit_element_php_conflict |
add_filter |
wp_insert_post_data |
add_filter |
cantata_edit_components |
add_filter |
wp_should_handle_php_error |
add_action |
template_redirect |
apply_filters |
cantata_edit_element_php_nocache |
do_action |
litespeed_control_set_nocache |
apply_filters |
cantata_edit_native_providers |
add_action |
rest_api_init |
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_element_php_key#
function cantata_edit_element_php_key(): string
The signing key, or '' (the feature then fails closed). CANTATA_EDIT_ELEMENT_PHP_KEY when defined (32+ bytes), else derived from the eight wp-config salt constants read directly: wp_salt() falls back to database options, and a database write must never be able to make code that runs. Values are never printed or stored.
Source location: includes/element-php.php:33.
cantata_edit_element_php_author_reason#
function cantata_edit_element_php_author_reason( int $user_id = 0 ): string
The first reason this account may not write element PHP, or '' when it may.
Implementation connections: cantata_edit_can_dev, cantata_edit_element_php_key.
Source location: includes/element-php.php:51.
cantata_edit_can_author_php#
function cantata_edit_can_author_php( int $user_id = 0 ): bool
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_php_author_reason.
Source location: includes/element-php.php:75.
cantata_edit_element_php_signer_ok#
function cantata_edit_element_php_signer_ok( int $signer, bool $fresh = false ): bool
Whether code signed by $signer may still run: the signer's role still has unfiltered_html and edit_themes (role capabilities, read without map_meta_cap, so DISALLOW_FILE_EDIT stops new authoring but not already signed code) and Developer mode. A deleted or demoted signer stops their code.
Implementation connections: cantata_edit_can_dev.
Source location: includes/element-php.php:84.
cantata_edit_element_php_normalize#
function cantata_edit_element_php_normalize( string $source ): 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-php.php:101.
cantata_edit_element_php_lifecycle_functions#
function cantata_edit_element_php_lifecycle_functions(): array
Functions whose direct call would change the response or the request's lifecycle, not the element's content.
Source location: includes/element-php.php:106.
cantata_edit_element_php_validate#
function cantata_edit_element_php_validate( string $source ): array
Check one source without running it. Returns [ 'ok', 'source' (canonical, '' when not ok), 'errors' => [ [ code, message, line ] ] ]. The tokenizer parses it as the body of the function it will run in, so syntax errors are found here; then the presentation contract. Not a sandbox.
Implementation connections: cantata_edit_can_author_php, cantata_edit_element_js_secret_patterns, cantata_edit_element_php_lifecycle_functions, cantata_edit_element_php_normalize.
Source location: includes/element-php.php:119.
cantata_edit_element_php_ref_parse#
function cantata_edit_element_php_ref_parse( $ref ): ?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-php.php:262.
cantata_edit_element_php_signature#
function cantata_edit_element_php_signature( string $owner, string $id, int $signer, string $source ): 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_php_key.
Source location: includes/element-php.php:266.
cantata_edit_element_php_resource#
function cantata_edit_element_php_resource( string $id, bool $fresh = false ): ?array
A resource by id, from the private store, or null. Internal: its source is returned only to PHP authors.
Source location: includes/element-php.php:272.
cantata_edit_element_php_stopped#
function cantata_edit_element_php_stopped( ?string $add = null, ?string $clear = null ): array
Resources stopped after a fatal error, until applied again or cleared.
Source location: includes/element-php.php:287.
cantata_edit_element_php_verify#
function cantata_edit_element_php_verify( $ref, string $owner ): string
The state of a reference for the owner being rendered or saved: verified (its resource exists for this owner, the signature recomputes and the signer still has authority), stopped (verified, but quarantined after a fatal error), unavailable (the feature cannot run here: no key, or turned off), or unverified (anything else).
Implementation connections: cantata_edit_element_php_key, cantata_edit_element_php_ref_parse, cantata_edit_element_php_resource, cantata_edit_element_php_signature, cantata_edit_element_php_signer_ok, cantata_edit_element_php_stopped.
Source location: includes/element-php.php:303.
cantata_edit_element_php_can_edit_owner#
function cantata_edit_element_php_can_edit_owner( string $owner ): bool
Whether the current account may edit the owner (a page it can edit, or the shared parts).
Source location: includes/element-php.php:314.
cantata_edit_element_php_stage#
function cantata_edit_element_php_stage( string $source, string $owner, int $user_id = 0 )
Explicit Apply by a PHP author: validate, store an immutable resource for this owner and sign it. The only path that signs. Returns [ 'ref' => reference, 'source' => canonical source ] or WP_Error. The page changes only when the editor's normal save stores the reference.
Implementation connections: cantata_edit_element_php_author_reason, cantata_edit_element_php_can_edit_owner, cantata_edit_element_php_signature, cantata_edit_element_php_validate.
Source location: includes/element-php.php:325.
cantata_edit_element_php_values#
function cantata_edit_element_php_values( string $html ): array
Every element carrying data-ke-php, in document order, with its placement conflict ('' when native): [ [ 'index' (1-based element number), 'tag', 'ref', 'conflict' ] ].
Implementation connections: cantata_edit_element_php_native_conflict.
Source location: includes/element-php.php:362.
cantata_edit_element_php_allowed_tags#
function cantata_edit_element_php_allowed_tags(): 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-php.php:377.
cantata_edit_element_php_native_conflict#
function cantata_edit_element_php_native_conflict( string $html ): array
Placement of every data-ke-php element: element index => reason ('' when native). Parsed with DOMDocument for the ancestors and descendants (read-only: the output HTML is never re-serialized from it). Element numbering follows WP_HTML_Tag_Processor's opening tags, which DOM order matches for the sanitized markup Kindly stores.
Implementation connections: cantata_edit_element_php_allowed_tags, cantata_edit_element_php_conflict_reason.
Source location: includes/element-php.php:387.
cantata_edit_element_php_conflict_reason#
function cantata_edit_element_php_conflict_reason( DOMElement $el, array $allowed ): 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-php.php:414.
cantata_edit_element_php_counts#
function cantata_edit_element_php_counts( string $html ): array
Each reference and how many times it appears.
Implementation connections: cantata_edit_element_php_values.
Source location: includes/element-php.php:438.
cantata_edit_element_php_check_submission#
function cantata_edit_element_php_check_submission( string $html, string $stored, string $owner, ?bool $can_author = null )
The save paths' check, before anything is written (cantata_edit_sanitize_saved_content). Every reference must be well formed, verify for $owner and sit in a native placement (400 with the element's number otherwise, whoever saves). An account that may not author PHP may keep or delete references, never add or multiply them beyond what $stored holds (403). Changes nothing.
Implementation connections: cantata_edit_can_author_php, cantata_edit_element_php_counts, cantata_edit_element_php_ref_parse, cantata_edit_element_php_values, cantata_edit_element_php_verify.
Source location: includes/element-php.php:452.
cantata_edit_element_php_strip#
function cantata_edit_element_php_strip( string $html ): string
Remove every data-ke-php (component templates, build and new-page sources, any public copy).
Source location: includes/element-php.php:497.
cantata_edit_element_php_strip_unverified#
function cantata_edit_element_php_strip_unverified( string $html, string $owner, ?array $allowed = null, array $preserve_inert = [] ): string
Keep only references that verify (or are stopped) for $owner; $allowed, when given, caps each one's count.
Implementation connections: cantata_edit_element_php_ref_parse, cantata_edit_element_php_verify.
Source location: includes/element-php.php:507.
cantata_edit_element_php_held_counts#
function cantata_edit_element_php_held_counts( int $id ): array
Current approved copies exclude kept/archived draft blobs and draft bookkeeping metadata.
Implementation connections: cantata_edit_element_js_publishing_draft, cantata_edit_element_php_counts.
Source location: includes/element-php.php:537.
cantata_edit_element_php_held_html#
function cantata_edit_element_php_held_html( int $id ): string
Count-only source for a restore check: never code source and never an executable rendering.
Implementation connections: cantata_edit_can_author_php, cantata_edit_element_js_internal, cantata_edit_element_php_held_counts, cantata_edit_element_php_strip_unverified, cantata_edit_element_php_values.
Source location: includes/element-php.php:549.
cantata_edit_element_php_should_run#
function cantata_edit_element_php_should_run(): bool
Whether this request may execute element PHP: the public front end only, or an explicit privileged preview.
Implementation connections: cantata_edit_can_author_php, cantata_edit_element_php_key, cantata_edit_is_editing.
Source location: includes/element-php.php:581.
cantata_edit_element_php_log#
function cantata_edit_element_php_log( ?array $entry = null ): array
Sanitized audit entries (no paths, no source, no values), newest last, at most 50.
Source location: includes/element-php.php:598.
cantata_edit_element_php_running#
function cantata_edit_element_php_running( ?array $set = null, bool $clear = false ): ?array
The resource running now (for the shutdown handler that stops code which ended the request).
Source location: includes/element-php.php:615.
cantata_edit_element_php_fatal#
function cantata_edit_element_php_fatal( ?array $error ): void
A fatal error while element code ran: stop that resource and record it (once).
Implementation connections: cantata_edit_element_php_log, cantata_edit_element_php_running, cantata_edit_element_php_stopped.
Source location: includes/element-php.php:623.
cantata_edit_element_php_clean_output#
function cantata_edit_element_php_clean_output( string $html ): string
Element output, as plain HTML: no code, frames or forms, no Kindly authority attributes.
Implementation connections: cantata_edit_allowed_html.
Source location: includes/element-php.php:632.
cantata_edit_element_php_execute#
function cantata_edit_element_php_execute( array $res, array $kindly ): array
Run one verified resource. Returns [ 'ok' => bool, 'html' => string ]. Never throws, never displays errors.
Implementation connections: cantata_edit_element_php_clean_output, cantata_edit_element_php_fatal, cantata_edit_element_php_log, cantata_edit_element_php_running, cantata_edit_element_php_stopped, cantata_edit_element_php_validate.
Source location: includes/element-php.php:647.
cantata_edit_element_php_bounds#
function cantata_edit_element_php_bounds( string $html, int $start, string $tag ): ?array
The byte range of the element whose opening tag starts at $start (tag name $tag): [ inner start, inner end, end ], or null when it is not closed. Counts nested elements of the same name; stored markup is sanitized, so attribute values never hold a raw ">".
Source location: includes/element-php.php:717.
cantata_edit_element_php_render#
function cantata_edit_element_php_render( string $html, string $owner, ?bool $run = null ): string
Render element PHP for one owner's markup. Public front end (should_run): each verified reference in a native placement runs and its output replaces the element's children; the reference goes. Anything that does not run keeps its placeholder; a runtime error leaves the element empty. Editing: references stay, and data-ce-php-state says what would happen. Every other view: references are removed, placeholders kept.
Implementation connections: cantata_edit_element_php_bounds, cantata_edit_element_php_execute, cantata_edit_element_php_native_conflict, cantata_edit_element_php_ref_parse, cantata_edit_element_php_resource, cantata_edit_element_php_should_run, cantata_edit_element_php_strip, cantata_edit_element_php_verify, cantata_edit_is_built, cantata_edit_is_editing.
Source location: includes/element-php.php:736.
cantata_edit_element_php_providers#
function cantata_edit_element_php_providers(): array
Registered native providers, by live source slug: [ title, owner, file, symbol, manage ]. Root and themes supply them through the cantata_edit_native_providers filter. Shown read-only in Advanced: they are application code with their own owner, never copied into element PHP.
Source location: includes/element-php.php:826.
cantata_edit_element_php_provider_read#
function cantata_edit_element_php_provider_read( string $slug, bool $with_source )
A provider's file (relative to wp-content) and, for PHP authors, its function's source lines.
Implementation connections: cantata_edit_element_php_providers.
Source location: includes/element-php.php:843.
cantata_edit_element_php_editor_config#
function cantata_edit_element_php_editor_config( ?WP_Post $post = null ): 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.
Implementation connections: cantata_edit_element_php_author_reason, cantata_edit_element_php_key, cantata_edit_element_php_providers, cantata_edit_live_sources.
Source location: includes/element-php.php:888.
cantata_edit_element_php_rest_owner#
function cantata_edit_element_php_rest_owner( WP_REST_Request $req )
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_can_author_php, cantata_edit_element_php_can_edit_owner, cantata_edit_element_php_log, cantata_edit_element_php_provider_read, cantata_edit_element_php_ref_parse, cantata_edit_element_php_resource, cantata_edit_element_php_stage, cantata_edit_element_php_validate, cantata_edit_element_php_verify.
Source location: includes/element-php.php:911.
cantata_edit_element_php_contract_violations#
function cantata_edit_element_php_contract_violations( string $html, string $owner = '' ): array
Contract violations for the build contract's audit: [ [ code, index, tag, message ] ].
Implementation connections: cantata_edit_element_php_log, cantata_edit_element_php_stopped, cantata_edit_element_php_validate, cantata_edit_element_php_values, cantata_edit_element_php_verify.
Source location: includes/element-php.php:964.