Element PHP
Use protected server-side presentation resources with explicit permissions and owner-bound references.
Server code that produces one element's public content, where no native setting and no registered provider does. It is full PHP, run as trusted code. It is not a sandbox, and nothing here claims it is.
Native first. Before writing element PHP, use:
- a native setting or component;
- a registered live source (an application's own provider: forms, payments, membership, listings, calendars);
- element CSS for appearance, or element JavaScript for browser behavior.
Element PHP is for the remaining case: server-side presentation for one element. Application logic, data writes, forms and anything with its own native owner stay in that owner. Advanced shows such owners read-only (below).
Files: includes/element-php.php (server), assets/element-php.js (editor), and the tests
tests/element-php-test.php, tests/element-php-process.mjs and tests/element-php-browser.mjs.
Where the code lives (source confidentiality)#
Markup holds only an opaque reference on the element:
<p class="hours" data-ke-php="p1.3f0c9a1e5b7d4c2a8e6f1b0d9c7a5e3f.<64 hex>">Opening hours</p>
- The element's children are its placeholder, shown in the editor and wherever code does not run.
- The source is an immutable private resource: one post of the type
cantata_php_codeper applied version, with the source in protected meta. That type has no REST route, no admin screen, no export and no capability any role holds. Core REST (content.raw), wp-admin, custom fields, XML-RPC and WXR export never return the source. The only source read isPOST cantata-edit/v1/element-php/read, for PHP authors. - Applying new code creates a new resource and reference. Drafts, revisions and History keep their references and still resolve.
Who may write it#
To add or change element PHP, an account needs all of:
unfiltered_html,edit_themesand Developer mode;- file edits allowed (no
DISALLOW_FILE_EDITorDISALLOW_FILE_MODS, andwp_is_file_mod_allowedtrue); - the site's wp-config salts configured.
The filter cantata_edit_can_author_php can only narrow this. The panel says which requirement is missing.
| Account | Add or change | Keep | Delete | Duplicate | See the source |
|---|---|---|---|---|---|
| PHP author | yes | yes | yes | yes | yes |
| Others who can edit the page | no (403) | yes | yes | no (403) | no |
| AI and generic code paths | no | yes | yes | no | no |
| wp-admin, REST posts, History restore (non-author) | references not currently held are removed | yes | yes | extra copies removed | no |
Signing and running#
- The only signing path is Apply. The server checks the code, stores the resource and signs the reference with an
HMAC. The key is derived from the eight wp-config salt constants, or from
CANTATA_EDIT_ELEMENT_PHP_KEY, never from the database. The HMAC covers the owner (post:<ID>orpart:<slug>), the resource, the signer and the source hash. - A reference runs only when its resource exists for the owner being rendered, the signature recomputes and the
signer's role still has
unfiltered_html,edit_themesand Developer mode. - These never run: planted database rows, edited resource meta, references copied to another page or part, hand typed references, and references from a site whose salts changed.
- Without salts the feature fails closed.
CANTATA_EDIT_ELEMENT_PHP_DISABLEturns it off. - It runs only on the public front end. It never runs in
?edit, admin, AJAX, REST, feeds, embeds, the customizer, cron, CLI, revision views or ordinary previews. A preview runs it only through the panel's preview link (an intent nonce) for a PHP author.
Writing the code#
The code is the body of static function ( array $kindly ). $kindly holds owner, post_id, tag and
placeholder. Return or echo the element's inner HTML, and escape what you print:
$open = (int) current_time( 'G' ) < 17;
return '<strong>' . esc_html( $open ? __( 'Open now', 'site' ) : __( 'Closed', 'site' ) ) . '</strong>';
Apply runs PHP's tokenizer, so syntax errors show with their line. It also refuses:
- PHP tags and inline HTML;
exitanddie,eval,includeandrequire,declare;- named functions, classes, interfaces, traits and enums;
- calls that change the whole response (
header, cookies,session_*, redirects,wp_die, output flushing, time limits, shutdown/error/exception handlers,ini_set,putenv); - anything that looks like a secret key.
These checks catch mistakes, not malice.
Output is cleaned to plain HTML:
script,style, frames and form controls are removed;wp_ksesruns with Kindly's ordinary list;- every
data-ke-*,data-ce-*anddata-kindly*attribute is removed.
So element PHP can never create CSS, JavaScript, PHP or live-slot authority, and its output is never stored.
Errors and limits#
- Its own output buffer; any
Throwableis caught; warnings are recorded, never shown. An error gives the element no content publicly; the author sees "Recent error" in the panel, andwp kindly element-php loglists errors with paths, source and values removed. - A fatal error (memory, max_execution_time) ends that request: PHP cannot catch it. WordPress's fatal handler lets
element PHP stop that resource, so the next request renders the placeholder until the code is applied again or
wp kindly element-php clear-stop <id>. Kindly disables PHP error display while the code runs, restoring the host setting after normal completion. If the host prevents disabling error display, the code does not run. - No per-element time limit is enforced. An endless loop ends at the host's
max_execution_time. - Limits: 16 KB of source per element, 32 PHP elements per page or part, 256 KB of output per element.
Placement#
Allowed on: div section article aside header footer main nav figure figcaption span p blockquote h1-h6 li dd dt td th small strong em b i.
Refused (whole save, with the element's number):
- on, inside or around a live slot;
- forms and form controls, or anything inside or containing them;
- page and part wrappers;
- inside SVG or MathML;
- nested PHP elements;
- breadcrumbs and linked section fields.
Component templates never carry element PHP (stripped). Theme part files must not either.
Native providers (read-only provenance)#
The filter cantata_edit_native_providers maps a live source slug to [ title, owner, file (relative to wp-content), symbol (function or Class::method), manage (admin URL) ]. On a live slot, Advanced > PHP shows "Provided by
Caching#
When the page or a published part holds element PHP and the request may run it, the response gets:
nocache_headers()andCache-Control: private, no-store;DONOTCACHEPAGE;litespeed_control_set_nocache.
The filter cantata_edit_element_php_nocache can opt out for code known to be cacheable. Other cache layers (CDN
rules, server caches) must respect these headers; that is not proved here for every host. Purge the page after
publishing changes, as for any content change.
API and CLI#
REST under
cantata-edit/v1:POST element-php/check{ source };POST element-php/stage{ owner, source }returns{ ref, source };POST element-php/read{ owner, refs };GET element-php/provider?slug=.
check, stage and read are for PHP authors only (stage and read also need edit rights on the owner).
Abilities for connected builders (root's
includes/advanced-php-api.php):cantata-edit/get-element-phpreads a page's or part's element owners, revision and protected PHP source (PHP authors only, throughelement-php/read);cantata-edit/set-element-phptakes{ page_id, part?, rev, element, intent: "server-php", php }. It validates, stages a protected signed resource and saves a draft only (empty PHP removes it).
The generic element-code abilities carry CSS and JavaScript, plus a PHP reference/state summary, never PHP source.
wp kindly element-php check <file|->,status <html-file|-> --owner=,resources [--owner=],log,clear-stop <resource id>. All are read-only except clear-stop.
Recovery and portable components#
After security-key rotation or removal of a signer permission, existing references stay in place and render their placeholders. Normal content edits can preserve or remove them, but cannot create or duplicate unverified references. A developer with server-code permissions can inspect the protected source, review it and Apply it again to create a new approval. No read or ordinary save re-approves code.
Existing approved code continues under file-edit and unfiltered-HTML restrictions that prevent new authoring, matching how installed theme PHP keeps running. Role permission revocation stops that signer code. The explicit element-PHP disable constant stops all element code.
Portable component files cannot contain owner-bound PHP references. The catalog retains the invalid source with a contract error; the picker, structured insertion and theme validation refuse it. Use a registered native provider for reusable server behavior. Linked pages retain their stored instance until the invalid template is corrected.
Use meaningful placeholder text. Non-executing views, including derived search descriptions and structured data, may use the placeholder. Runtime warnings are kept in the bounded private error log; repeatedly failing code should be corrected. Shared-part PHP conservatively disables page caching across front-end views because that part can appear throughout the site.