forms.php
Validates public submissions against the published form schema, stores private action settings and submission records, and coordinates email, redirects, webhooks, popups, and private files.
Responsibility#
Validates public submissions against the published form schema, stores private action settings and submission records, and coordinates email, redirects, webhooks, popups, and private files.
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#
Module constants#
const CANTATA_EDIT_FORMS_META = '_cantata_edit_forms';
const CANTATA_EDIT_SUBMISSION = 'kindly_submission';
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_forms_cap |
add_action |
init |
add_action |
cantata_edit_saved |
apply_filters |
cantata_edit_form_rate |
do_action |
cantata_edit_form_submitted |
add_action |
rest_api_init |
add_action |
admin_menu |
add_action |
admin_post_kindly_submissions |
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_form_url#
function cantata_edit_form_url( string $url, array $schemes = [ 'http', 'https' ] ): bool
An http(s) address written correctly (no lookup: an outgoing request checks where it goes when it is made).
Source location: includes/forms.php:29.
cantata_edit_forms_cap#
function cantata_edit_forms_cap(): 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/forms.php:33.
cantata_edit_form_defaults#
function cantata_edit_form_defaults(): array
The default settings of a form's after-submit actions.
Source location: includes/forms.php:46.
cantata_edit_form_settings_clean#
function cantata_edit_form_settings_clean( array $in )
A form's settings made safe: known keys only, addresses checked, a local or http(s) redirect, an https webhook.
Implementation connections: cantata_edit_form_defaults, cantata_edit_form_url.
Source location: includes/forms.php:52.
cantata_edit_forms_meta#
function cantata_edit_forms_meta( int $post_id ): array
A page's form settings: [ 'live' => [ form => settings ], 'draft' => [ form => settings ] ].
Source location: includes/forms.php:101.
cantata_edit_form_settings#
function cantata_edit_form_settings( int $post_id, string $form, bool $draft = false ): array
The settings a form uses: the live ones for visitors; the editor sees its draft's when there is one.
Implementation connections: cantata_edit_form_defaults, cantata_edit_forms_meta.
Source location: includes/forms.php:107.
cantata_edit_form_schema#
function cantata_edit_form_schema( string $html, string $form ): ?array
The form's schema from stored HTML: [ fields => [ name => field ], order => [ names ], label => form name ] or null. field: type (text email url tel number date time password hidden textarea select radio checkbox acceptance file), label, required, multiple, min, max, step, minlength, maxlength, options [ value => shown ], accept, size (MB), count.
Source location: includes/forms.php:130.
cantata_edit_form_check#
function cantata_edit_form_check( array $f, $raw ): array
One field's submitted value checked against its schema: [ value, error ]. Values are stored as text.
Implementation connections: cantata_edit_form_url.
Source location: includes/forms.php:220.
cantata_edit_forms_dir#
function cantata_edit_forms_dir(): string
Where uploads wait: a folder the web server is told to refuse, made once.
Source location: includes/forms.php:262.
cantata_edit_form_fill#
function cantata_edit_form_fill( string $text, array $rows, bool $html ): string
[all-fields] and [field id="name"] in an email's words: escaped values only (no shortcode runs).
Source location: includes/forms.php:273.
cantata_edit_form_submit#
function cantata_edit_form_submit( WP_REST_Request $req )
The visitor's submission: checked whole against the published page's form, then its actions, in order.
Implementation connections: cantata_edit_form_check, cantata_edit_form_files, cantata_edit_form_fill, cantata_edit_form_schema, cantata_edit_form_settings.
Source location: includes/forms.php:285.
cantata_edit_form_files#
function cantata_edit_form_files( array $f, $upload )
A file field's uploads checked (count, size, type) and moved into the protected folder.
Implementation connections: cantata_edit_form_settings, cantata_edit_form_settings_clean, cantata_edit_forms_cap, cantata_edit_forms_dir, cantata_edit_forms_meta, cantata_edit_menu_parent.
Source location: includes/forms.php:362.
cantata_edit_submission_rows#
function cantata_edit_submission_rows( array $ids = [] ): array
Submissions as rows: [ id, page, form, date, fields: [ label => shown ] ].
Source location: includes/forms.php:424.
cantata_edit_csv_cell#
function cantata_edit_csv_cell( string $v ): string
A CSV cell that a spreadsheet won't run as a formula.
Implementation connections: cantata_edit_forms_cap, cantata_edit_forms_dir, cantata_edit_submission_rows.
Source location: includes/forms.php:438.
cantata_edit_submissions_page#
function cantata_edit_submissions_page(): 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.
Implementation connections: cantata_edit_forms_cap, cantata_edit_submission_rows, cantata_edit_training_button.
Source location: includes/forms.php:486.