Kindly EditDocumentationTry the editor

rest.php

Registers the core editor REST endpoints and coordinates content validation, atomic save operations, revisions, conflict detection, publication, discard, and restore.

Responsibility#

Registers the core editor REST endpoints and coordinates content validation, atomic save operations, revisions, conflict detection, publication, discard, and restore.

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.

blocks-mode, blocks, editor, element-js, element-php, kindly-menu, linked-components, page-model, parts, render, sanitize, seo, template-code, theme.

Module constants#

const CANTATA_EDIT_DRAFT_TITLE = '_cantata_edit_draft_title';

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#

page_on_front, time_format. 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
add_action rest_api_init
apply_filters cantata_edit_transactional_storage
apply_filters cantata_edit_content_owner_check
do_action cantata_edit_saved
apply_filters the_content
apply_filters cantata_edit_build_template
apply_filters the_content

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_without_kses#

function cantata_edit_without_kses( callable $fn )

wp_insert_post runs kses on content for users without unfiltered_html, with a list that has no SVG. Ours already ran.

Implementation connections: cantata_edit_element_js_internal.

Source location: includes/rest.php:204.

cantata_edit_page_rev#

function cantata_edit_page_rev( int $id ): string

A fingerprint of everything the editor shows for a page, to notice when someone else saved it meanwhile.

Implementation connections: cantata_edit_linked_render, cantata_edit_seo_live.

Source location: includes/rest.php:225.

cantata_edit_revs#

function cantata_edit_revs( int $id, array $parts ): array

The revs of every region the editor can save, keyed the way the editor names them.

Implementation connections: cantata_edit_page_rev, cantata_edit_part_rev.

Source location: includes/rest.php:238.

cantata_edit_already_saved#

function cantata_edit_already_saved( WP_Post $post, WP_REST_Request $req, bool $publish ): bool

A save the server already has: the same words (and title) are what's live (publish) or the saved draft. That's the editor trying again after the connection dropped before the answer came back, not someone else's change.

Implementation connections: cantata_edit_same_html, cantata_edit_sanitize_saved_content, cantata_edit_sanitize_seo, cantata_edit_seo_live, cantata_edit_seo_values, cantata_edit_without_kses.

Source location: includes/rest.php:251.

cantata_edit_part_already_saved#

function cantata_edit_part_already_saved( string $slug, $html, bool $publish, string $grant_owner = '' ): bool

The same for a header or footer: what it would save is already what's published (or its saved draft).

Implementation connections: cantata_edit_part_draft, cantata_edit_part_post, cantata_edit_part_published, cantata_edit_same_html, cantata_edit_sanitize_saved_content, cantata_edit_without_kses.

Source location: includes/rest.php:281.

cantata_edit_storage_error#

function cantata_edit_storage_error(): WP_Error

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/rest.php:291.

cantata_edit_put_meta#

function cantata_edit_put_meta( int $id, string $key, $value )

update_post_meta, telling a failed write apart from "already that value" (both return false).

Implementation connections: cantata_edit_storage_error.

Source location: includes/rest.php:296.

cantata_edit_drop_meta#

function cantata_edit_drop_meta( int $id, string $key )

delete_post_meta, telling a failed delete apart from "wasn't there".

Implementation connections: cantata_edit_atomic, cantata_edit_storage_error.

Source location: includes/rest.php:307.

cantata_edit_transactional#

function cantata_edit_transactional(): bool

Can this database undo a save? Only core wpdb on MySQL/MariaDB with transactional posts and postmeta tables (InnoDB), on one connection. SQLite drop-ins, read/write-splitting drop-ins (HyperDB, LudicrousDB) and MyISAM tables are undone by cantata_edit_atomic()'s own snapshot instead. A site can say otherwise with the filter.

Source location: includes/rest.php:316.

cantata_edit_atomic#

function cantata_edit_atomic( callable $fn, array $ids )

Run writes that belong together (a page with its title, SEO, drafts and shared parts) so they land together or not at all. $fn returns a WP_Error to have every write it made undone; $ids are the existing posts it may change.

On a transactional database this is a transaction of its own, or, inside one the caller already opened (or with autocommit off), only a savepoint: never a COMMIT the caller didn't ask for. Where the database can't undo it, or lost the transaction meanwhile (an implicit commit, a dropped connection, a deadlock), the rows of $ids read at the start are written back and posts created meanwhile (new parts, revisions) removed. Either way the object cache forgets every post touched. A failure that couldn't be undone says so rather than claiming nothing changed. What other plugins' hooks did outside these posts (emails, remote calls, other tables) is theirs.

Implementation connections: cantata_edit_forget_posts, cantata_edit_restore_snapshot, cantata_edit_snapshot, cantata_edit_storage_error, cantata_edit_transactional.

Source location: includes/rest.php:341.

cantata_edit_snapshot#

function cantata_edit_snapshot( array $ids ): array

The rows a failed save may have to put back: the posts themselves and all their meta.

Source location: includes/rest.php:439.

cantata_edit_restore_snapshot#

function cantata_edit_restore_snapshot( array $snap, array $log ): bool

Put back what a failed save changed on databases that can't roll back. True only if all of it went back. Only the columns and meta rows this save itself changed are restored, and only while they still hold what it wrote: a value another request stored meanwhile is kept, and the undo then reports itself incomplete instead of overwriting it.

Source location: includes/rest.php:459.

cantata_edit_forget_posts#

function cantata_edit_forget_posts( array $ids ): void

After an undo: no cached copy (posts, meta, queries such as a part's lookup by name) may keep what was undone.

Source location: includes/rest.php:512.

cantata_edit_rest_save#

function cantata_edit_rest_save( 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_already_saved, cantata_edit_atomic, cantata_edit_blocks_mode, cantata_edit_has_draft, cantata_edit_history_url, cantata_edit_page_rev, cantata_edit_part_already_saved, cantata_edit_part_draft, cantata_edit_part_post, cantata_edit_part_published, cantata_edit_part_rev, cantata_edit_revs, cantata_edit_sanitize_saved_content, cantata_edit_save_blocks, cantata_edit_save_writes, cantata_edit_validate_part, cantata_edit_without_kses.

Source location: includes/rest.php:525.

cantata_edit_save_writes#

function cantata_edit_save_writes( WP_REST_Request $req, WP_Post $post, bool $publish, array $parts, array $base, ?string $blocks_html, ?string $prepared_content )

Every write of one save, already validated. Runs inside cantata_edit_atomic(): a WP_Error here undoes all of it, so the page's draft can go before wp_update_post (a draft still there would be copied over the new words by the publish hook in render.php) and still be back if anything after it fails.

Implementation connections: cantata_edit_drop_meta, cantata_edit_put_meta, cantata_edit_same_html, cantata_edit_sanitize_seo, cantata_edit_save_part, cantata_edit_save_seo, cantata_edit_seo_live, cantata_edit_seo_values, cantata_edit_storage_error.

Source location: includes/rest.php:651.

cantata_edit_rest_discard#

function cantata_edit_rest_discard( WP_REST_Request $req )

Throw away this page's draft and the current user's own header/footer drafts. Other people's are left alone.

Implementation connections: cantata_edit_atomic, cantata_edit_drop_meta, cantata_edit_page_rev, cantata_edit_part_draft_key.

Source location: includes/rest.php:734.

cantata_edit_rest_build#

function cantata_edit_rest_build( WP_REST_Request $req )

Keep an ordinary page's words and lay them out with the theme's "convert" template. Tokens: {{title}}, {{content}}, {{excerpt}} (its intro line), {{crumbs}} (Home / parents / page, as links) and {{children}} (a list of its child pages). Registered live sources used as shortcodes become live slots instead of frozen HTML. The page as it was is kept as a revision first, so History can put it back.

Implementation connections: cantata_edit_config, cantata_edit_is_built, cantata_edit_live_normalize, cantata_edit_live_sources, cantata_edit_sanitize_saved_content, cantata_edit_without_kses.

Source location: includes/rest.php:765.

cantata_edit_rest_new_page#

function cantata_edit_rest_new_page( WP_REST_Request $req )

A new built page (a WordPress draft until published). It starts with the theme's page heading (the "convert" template with the title filled in and no body), so it has its H1 and crumb from the first moment.

Implementation connections: cantata_edit_config, cantata_edit_element_js_finish, cantata_edit_element_js_values, cantata_edit_sanitize_saved_content, cantata_edit_url, cantata_edit_without_kses.

Source location: includes/rest.php:858.

cantata_edit_rest_address#

function cantata_edit_rest_address( WP_REST_Request $req )

The address WordPress would store for the typed text, readable (stored is percent-encoded), and its free variant.

Source location: includes/rest.php:911.

cantata_edit_url#

function cantata_edit_url( int $id ): string

Where to open the editor for a page: its permalink, or the preview link while it is still a draft.

Source location: includes/rest.php:929.

cantata_edit_history_url#

function cantata_edit_history_url( int $id ): string

WordPress's revisions screen for this page, once it has a revision.

Source location: includes/rest.php:937.

cantata_edit_rest_history#

function cantata_edit_rest_history( WP_REST_Request $req )

The page's published versions, newest first, described in words: when, who, and roughly what changed.

Implementation connections: cantata_edit_has_draft.

Source location: includes/rest.php:943.

cantata_edit_rest_restore#

function cantata_edit_rest_restore( WP_REST_Request $req )

Put a published version back (WordPress's own restore, so it's in History too); the editor draft goes with it.

Implementation connections: cantata_edit_element_js_core_write_refusal, cantata_edit_url.

Source location: includes/rest.php:1039.

cantata_edit_same_html#

function cantata_edit_same_html( string $a, string $b ): bool

Two versions of a page that read the same: ’ and ’, and , and whitespace between tags don't make a draft (they left permanent "Unpublished changes" on pages nobody had changed).

Source location: includes/rest.php:1063.

cantata_edit_rest_kept_draft#

function cantata_edit_rest_kept_draft( WP_REST_Request $req )

A draft that Put back set aside: restore it as the page's draft (restore=true), or drop it.

Implementation connections: cantata_edit_element_js_check_submission, cantata_edit_element_js_current_counts, cantata_edit_element_php_check_submission, cantata_edit_element_php_held_html, cantata_edit_has_draft, cantata_edit_sanitize_seo.

Source location: includes/rest.php:1073.

function cantata_edit_rest_links( WP_REST_Request $req )

The publish check's links to this site, answered from the database instead of loading each page: fast, the same every time, and no load on a small host. Each link is { path, hash }. 'gone': nothing lives at that address; 'nohash': the page is there but has no section with that link name; 'ok'; 'unknown': not a page or file the database knows (an archive, a custom route), which the editor may still check the slow way.

Implementation connections: cantata_edit_link_state.

Source location: includes/rest.php:1123.

cantata_edit_route_state#

function cantata_edit_route_state( string $rel ): string

An address that isn't a post, page or file: what WordPress's own rules make of it, as WordPress would, first rule first. A rule that asks for a post or page by name found nothing (the lookups above ran), so the answer is 'gone', final and the same every time: a typo like /find-a-schol/ is caught without loading anything. Categories, tags and authors are looked up; archives, feeds and searches are fine; only a route another plugin added stays 'unknown'.

Source location: includes/rest.php:1139.

function cantata_edit_link_state( string $path, string $hash, string $home ): 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_is_built, cantata_edit_route_state.

Source location: includes/rest.php:1182.

cantata_edit_rest_trash#

function cantata_edit_rest_trash( WP_REST_Request $req )

"Move this page to the Trash" (the ⋯ menu). WordPress's Trash, so it can be restored from Pages → Trash; never deleted for good here. Its unpublished draft, set-aside draft and edit lock go with it. Answers where to go next: the page it sat under, else the home page; a popup or template goes back to its Kindly list.

Implementation connections: cantata_edit_can_trash, cantata_edit_menu_list_for.

Source location: includes/rest.php:1231.

About this page

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

Type a word or phrase to search the full documentation.