Kindly EditDocumentationTry the editor

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:

  1. a native setting or component;
  2. a registered live source (an application's own provider: forms, payments, membership, listings, calendars);
  3. 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_code per 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 is POST 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_themes and Developer mode;
  • file edits allowed (no DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS, and wp_is_file_mod_allowed true);
  • 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> or part:<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_themes and 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_DISABLE turns 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;
  • exit and die, eval, include and require, 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_kses runs with Kindly's ordinary list;
  • every data-ke-*, data-ce-* and data-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 Throwable is caught; warnings are recorded, never shown. An error gives the element no content publicly; the author sees "Recent error" in the panel, and wp kindly element-php log lists 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

(<owner>)" and the settings link. For PHP authors, it also shows the provider function's source, read-only, and only from the plugins, mu-plugins or themes folders. It is never an editor, and never a copy. <h2 id="caching">Caching<a class="heading-link" href="#caching" aria-label="Link to Caching">#</a></h2><p>When the page or a published part holds element PHP and the request may run it, the response gets:</p> <ul> <li><code>nocache_headers()</code> and <code>Cache-Control: private, no-store</code>;</li> <li><code>DONOTCACHEPAGE</code>;</li> <li><code>litespeed_control_set_nocache</code>.</li> </ul> <p>The filter <code>cantata_edit_element_php_nocache</code> 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.</p> <h2 id="api-and-cli">API and CLI<a class="heading-link" href="#api-and-cli" aria-label="Link to API and CLI">#</a></h2><ul> <li><p>REST under <code>cantata-edit/v1</code>:</p> <ul> <li><code>POST element-php/check</code> <code>{ source }</code>;</li> <li><code>POST element-php/stage</code> <code>{ owner, source }</code> returns <code>{ ref, source }</code>;</li> <li><code>POST element-php/read</code> <code>{ owner, refs }</code>;</li> <li><code>GET element-php/provider?slug=</code>.</li> </ul> <p>check, stage and read are for PHP authors only (stage and read also need edit rights on the owner).</p> </li> <li><p>Abilities for connected builders (root's <code>includes/advanced-php-api.php</code>):</p> <ul> <li><code>cantata-edit/get-element-php</code> reads a page's or part's element owners, revision and protected PHP source (PHP authors only, through <code>element-php/read</code>);</li> <li><code>cantata-edit/set-element-php</code> takes <code>{ page_id, part?, rev, element, intent: "server-php", php }</code>. It validates, stages a protected signed resource and saves a draft only (empty PHP removes it).</li> </ul> <p>The generic element-code abilities carry CSS and JavaScript, plus a PHP reference/state summary, never PHP source.</p> </li> <li><p><code>wp kindly element-php check <file|-></code>, <code>status <html-file|-> --owner=</code>, <code>resources [--owner=]</code>, <code>log</code>, <code>clear-stop <resource id></code>. All are read-only except clear-stop.</p> </li> </ul> <h2 id="recovery-and-portable-components">Recovery and portable components<a class="heading-link" href="#recovery-and-portable-components" aria-label="Link to Recovery and portable components">#</a></h2><p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p> </article><div class="page-sources"><strong>About this page</strong><p>Documents Kindly Edit 0.9.16. Source: <code>docs/ELEMENT-PHP.md</code>. Theme choices and account permissions can change which controls appear.</p></div><nav class="page-pagination" aria-label="Related pages"><a href="/docs/code/element-javascript/"><span>Previous</span>Element JavaScript</a><a href="/docs/code/native-behaviors/"><span>Next</span>Native interaction owners</a></nav><footer class="docs-footer"><a href="/">Kindly Edit</a><a href="/docs/reference/documentation-coverage/">Coverage and version notes</a><a href="/privacy.html">Privacy</a></footer></main><aside class="docs-toc" aria-label="On this page"><strong>On this page</strong><ol><li class="toc-2"><a href="#where-the-code-lives-source-confidentiality">Where the code lives (source confidentiality)</a></li><li class="toc-2"><a href="#who-may-write-it">Who may write it</a></li><li class="toc-2"><a href="#signing-and-running">Signing and running</a></li><li class="toc-2"><a href="#writing-the-code">Writing the code</a></li><li class="toc-2"><a href="#errors-and-limits">Errors and limits</a></li><li class="toc-2"><a href="#placement">Placement</a></li><li class="toc-2"><a href="#native-providers-read-only-provenance">Native providers (read-only provenance)</a></li><li class="toc-2"><a href="#caching">Caching</a></li><li class="toc-2"><a href="#api-and-cli">API and CLI</a></li><li class="toc-2"><a href="#recovery-and-portable-components">Recovery and portable components</a></li></ol><a class="back-top" href="#main">Back to top ↑</a></aside></div><dialog id="search-dialog" aria-labelledby="search-title"><div class="search-header"><label id="search-title" for="docs-search">Search documentation</label><button type="button" class="search-close" aria-label="Close search">×</button></div><input type="search" id="docs-search" autocomplete="off" placeholder="Try ‘button link’, ‘phone spacing’, or ‘PHP’"><p id="search-status" role="status">Type a word or phrase to search the full documentation.</p><div id="search-results"></div></dialog></body></html>