(int) ( strlen( $cut ) / 2 ) ) {
$cut = substr( $cut, 0, $space );
}
return rtrim( $cut, " \t,.;:" ) . "\u{2026}";
}
/**
* Display context for a form, or for one entry of it.
*
* @param mixed $schema Form schema.
* @param array $extra Context (submission_id, links, signature).
* @param array|null $submission The entry, when the answers are one entry's.
* @return array
*/
public static function context( $schema, array $extra = array(), $submission = null ): array {
if ( ! function_exists( 'apply_filters' ) ) {
return $extra;
}
/**
* Filter the display context answers are formatted with. An add-on
* that formats its own field types (see `subtleforms/format/answer`)
* adds what it needs here.
*
* @param array $context Context.
* @param mixed $schema Form schema.
* @param array|null $submission The entry, or null.
* @since 2.7.2
*/
$context = apply_filters( 'subtleforms/format/context', $extra, $schema, is_array( $submission ) ? $submission : null );
return is_array( $context ) ? $context : $extra;
}
/**
* Display context for one entry.
*
* @param mixed $schema Form schema.
* @param mixed $submission Submission row.
* @param array $extra More context.
* @return array
*/
public static function entryContext( $schema, $submission, array $extra = array() ): array {
if ( is_array( $submission ) && isset( $submission['id'] ) && ! isset( $extra['submission_id'] ) ) {
$extra['submission_id'] = (int) $submission['id'];
}
return self::context( $schema, $extra, is_array( $submission ) ? $submission : null );
}
/**
* A stored answer as display text.
*
* Context keys:
* - submission_id (int) Entry ID, for upload download links.
* - links (bool) Add download links after file names.
* - signature (string) 'long' (default), 'short' ("Signed") or 'raw'
* (the image data, for renderers that draw it).
*
* Add-ons may add their own keys through `subtleforms/format/context`.
*
* @param mixed $value Stored value.
* @param array $field Field node.
* @param array $context Display context.
* @return string
*/
public static function text( $value, array $field, array $context = array() ): string {
$type = (string) ( $field['type'] ?? '' );
if ( function_exists( 'apply_filters' ) && '' !== $type ) {
/**
* Format an answer of a field type an add-on provides. Return a
* string to use it, or null to let this plugin format it.
*
* @param string|null $text Default null.
* @param mixed $value Stored value.
* @param array $field Field node.
* @param array $context Display context.
* @since 2.7.2
*/
$custom = apply_filters( 'subtleforms/format/answer', null, $value, $field, $context );
if ( is_string( $custom ) ) {
return $custom;
}
}
if ( EntryValues::isSignatureImage( $value ) ) {
$mode = (string) ( $context['signature'] ?? 'long' );
if ( 'raw' === $mode ) {
return (string) $value;
}
return 'short' === $mode
? __( 'Signed', 'subtleforms' )
: __( 'Signed (the signature image is in the entry)', 'subtleforms' );
}
if ( 'password' === $type ) {
return EntryValues::passwordLabel( $value );
}
if ( Repeater::TYPE === $type ) {
return Repeater::toText( $value, $field, $context );
}
if ( 'rich_text' === $type && is_string( $value ) ) {
$text = preg_replace( '#<\s*(br|/p|/li)\s*/?>#i', "\n", $value );
return trim( html_entity_decode( wp_strip_all_tags( (string) $text ), ENT_QUOTES, 'UTF-8' ) );
}
if ( 'checkbox_grid' === $type && is_array( $value ) ) {
return self::matrix( $value, $field );
}
if ( 'address_group' === $type && is_array( $value ) ) {
return self::address( $value, $field );
}
if ( 'name_group' === $type && is_array( $value ) ) {
return self::name( $value, $field );
}
// One choice may be stored on its own rather than in a list.
if ( 'chained_select' === $type && is_scalar( $value ) && '' !== (string) $value ) {
$value = array( $value );
}
$items = self::items( $value, $field, $context );
if ( null !== $items ) {
return implode( self::isUploadList( $value ) && ! empty( $context['links'] ) ? "\n" : ', ', $items );
}
if ( null === $value ) {
return '';
}
if ( in_array( $type, array( 'date', 'time', 'datetime' ), true ) && is_string( $value ) ) {
return self::date( $value, $type, $field );
}
if ( self::isYesNo( $field ) && ! is_array( $value ) ) {
if ( '' === $value && 'consent' !== $type ) {
return '';
}
return FieldMapper::isChecked( $value, $field ) ? __( 'Yes', 'subtleforms' ) : __( 'No', 'subtleforms' );
}
return FieldMapper::toText( FieldMapper::optionLabels( $value, $field ) );
}
/**
* An address answer as one line: its parts in builder order (street,
* street line 2, city, state, postal code, country, then parts an add-on
* appended) joined with ", ". Empty parts and data parts are left out.
* Older answer keys (`street`, `street2`, `postal`) read as the part they
* stand for.
*
* @param mixed $value Stored address.
* @param array $field Field node.
* @return string
*/
public static function address( $value, array $field = array() ): string {
if ( ! is_array( $value ) ) {
return FieldMapper::toText( $value );
}
$out = array();
foreach ( \SubtleForms\Fields\CompositeParts::textParts( 'address_group' ) as $part ) {
$v = $value[ $part['value'] ] ?? null;
if ( ( null === $v || '' === $v ) && null !== $part['alias'] ) {
$v = $value[ $part['alias'] ] ?? null;
}
if ( is_scalar( $v ) && '' !== trim( (string) $v ) ) {
$out[] = trim( (string) $v );
}
}
return implode( ', ', $out );
}
/**
* A name answer as one line: its parts in builder order (first, middle,
* last, suffix, then parts an add-on appended) joined with a space. Empty
* parts and data parts are left out.
*
* @param mixed $value Stored name.
* @param array $field Field node.
* @return string
*/
public static function name( $value, array $field = array() ): string {
if ( ! is_array( $value ) ) {
return FieldMapper::toText( $value );
}
$by_part = array();
foreach ( \SubtleForms\Fields\CompositeParts::textParts( 'name_group' ) as $part ) {
$v = $value[ $part['value'] ] ?? null;
if ( ( null === $v || '' === $v ) && null !== $part['alias'] ) {
$v = $value[ $part['alias'] ] ?? null;
}
if ( is_scalar( $v ) && '' !== trim( (string) $v ) ) {
$by_part[ $part['value'] ] = trim( (string) $v );
}
}
$drawing = array( 'first_name', 'middle_name', 'last_name', 'suffix' );
$out = array();
foreach ( $drawing as $key ) {
if ( isset( $by_part[ $key ] ) ) {
$out[] = $by_part[ $key ];
unset( $by_part[ $key ] );
}
}
return implode( ' ', array_merge( $out, array_values( $by_part ) ) );
}
/**
* A list answer as one display string per item, or null when the answer
* is not a list (or is a list that reads as one value, like a name).
*
* @param mixed $value Stored value.
* @param array $field Field node.
* @param array $context Display context.
* @return string[]|null
*/
public static function items( $value, array $field, array $context = array() ): ?array {
if ( ! is_array( $value ) || array() === $value || array_keys( $value ) !== range( 0, count( $value ) - 1 ) ) {
return null;
}
$type = (string) ( $field['type'] ?? '' );
if ( Repeater::TYPE === $type || Repeater::looksLikeGroups( $value ) && ! self::isUploadList( $value ) ) {
return null;
}
if ( function_exists( 'apply_filters' ) && '' !== $type ) {
/**
* Format a list answer of a field type an add-on provides, one
* string per item. Return an array to use it, or null.
*
* @param string[]|null $items Default null.
* @param array $value Stored list.
* @param array $field Field node.
* @param array $context Display context.
* @since 2.7.2
*/
$custom = apply_filters( 'subtleforms/format/items', null, $value, $field, $context );
if ( is_array( $custom ) ) {
return array_values( array_map( 'strval', $custom ) );
}
}
if ( self::isUploadList( $value ) ) {
$out = array();
foreach ( $value as $file ) {
$name = trim( (string) $file['name'] );
$id = (int) ( $context['submission_id'] ?? 0 );
$out[] = ! empty( $context['links'] ) && $id > 0 && class_exists( '\SubtleForms\Uploads\Uploads' ) && function_exists( 'admin_url' )
? sprintf( '%s (%s)', $name, \SubtleForms\Uploads\Uploads::downloadUrl( $id, (string) $file['id'] ) )
: $name;
}
return $out;
}
if ( 'chained_select' === $type ) {
return array_values( array_filter( self::chained( $value, $field ), static fn( $t ) => '' !== $t ) );
}
$labels = self::optionMap( $field );
$out = array();
foreach ( $value as $item ) {
if ( is_scalar( $item ) && isset( $labels[ (string) $item ] ) ) {
$text = $labels[ (string) $item ];
} elseif ( is_scalar( $item ) && self::isYesNo( $field ) && empty( $labels ) ) {
$text = FieldMapper::isChecked( $item, $field ) ? __( 'Yes', 'subtleforms' ) : __( 'No', 'subtleforms' );
} else {
$text = FieldMapper::toText( $item );
}
if ( '' !== $text ) {
$out[] = $text;
}
}
return $out;
}
/**
* A stored answer as HTML for an HTML email: line breaks become
,
* rich text keeps its allowed tags, everything else is escaped.
*
* @param mixed $value Stored value.
* @param array $field Field node.
* @param array $context Display context.
* @return string
*/
public static function html( $value, array $field, array $context = array() ): string {
$type = (string) ( $field['type'] ?? '' );
if ( EntryValues::isSignatureImage( $value ) ) {
return '
';
}
if ( 'rich_text' === $type && is_string( $value ) ) {
return \SubtleForms\Validation\Sanitizer::sanitizeRichText( $value );
}
if ( Repeater::TYPE === $type ) {
return Repeater::toHtml( $value, $field, $context );
}
return nl2br( esc_html( self::text( $value, $field, $context ) ) );
}
/**
* Display text for one field's answer, with the field found in a schema.
* Unknown keys fall back to schema-free text.
*
* @param array $schema Form schema.
* @param string $key Field key.
* @param mixed $value Stored value.
* @param array $context Display context.
* @return string
*/
public static function forKey( array $schema, string $key, $value, array $context = array() ): string {
foreach ( FieldMapper::fields( $schema ) as $entry ) {
if ( $entry['key'] === $key ) {
return self::text( $value, $entry['field'], $context );
}
}
return FieldMapper::toText( $value );
}
/**
* Entry screen data: per answer key, its field name, display text and,
* for list answers, one string per item. Repeater answers carry their
* columns and one row of cell text per group.
*
* @param array $schema Form schema.
* @param array $payload Stored answers.
* @param array $context Display context.
* @return array
*/
public static function display( array $schema, array $payload, array $context = array() ): array {
$fields = array();
foreach ( FieldMapper::fields( $schema ) as $entry ) {
$fields[ $entry['key'] ] = $entry;
}
$context = self::context( $schema, $context );
$out = array();
foreach ( $payload as $key => $value ) {
$key = (string) $key;
$entry = $fields[ $key ] ?? null;
$field = $entry ? $entry['field'] : array();
$row = array(
'label' => $entry ? $entry['label'] : $key,
'text' => $entry ? self::text( $value, $field, $context ) : FieldMapper::toText( $value ),
);
$items = $entry ? self::items( $value, $field, $context ) : null;
if ( null !== $items ) {
$row['items'] = $items;
}
if ( $entry && Repeater::TYPE === $entry['type'] ) {
$columns = array();
foreach ( Repeater::childFields( $field ) as $child ) {
$columns[] = array(
'key' => $child['key'],
'label' => '' !== $child['label'] ? $child['label'] : $child['key'],
);
}
$cells = array();
foreach ( Repeater::groups( $value ) as $group ) {
$line = array();
foreach ( Repeater::childFields( $field ) as $child ) {
$line[ $child['key'] ] = array_key_exists( $child['key'], $group )
? self::text( $group[ $child['key'] ], $child['field'], $context )
: '';
}
$cells[] = $line;
}
$row['columns'] = $columns;
$row['cells'] = $cells;
}
$out[ $key ] = $row;
}
return $out;
}
/**
* Answers with each dependent dropdown answer replaced by the label
* chosen at each level, including inside Repeater groups. Every other
* answer is left as stored. Used for the webhook "full" payload, which
* otherwise sends answers as stored.
*
* @param array $schema Form schema.
* @param array $payload Stored answers.
* @return array
*/
public static function withChainedLabels( array $schema, array $payload ): array {
foreach ( FieldMapper::fields( $schema ) as $entry ) {
$key = $entry['key'];
if ( ! array_key_exists( $key, $payload ) ) {
continue;
}
if ( 'chained_select' === $entry['type'] && is_array( $payload[ $key ] ) ) {
$payload[ $key ] = self::chained( $payload[ $key ], $entry['field'] );
continue;
}
if ( Repeater::TYPE === $entry['type'] && is_array( $payload[ $key ] ) ) {
foreach ( $payload[ $key ] as $index => $group ) {
if ( ! is_array( $group ) ) {
continue;
}
foreach ( Repeater::childFields( $entry['field'] ) as $child ) {
$childKey = $child['key'];
if ( 'chained_select' === $child['type'] && isset( $group[ $childKey ] ) && is_array( $group[ $childKey ] ) ) {
$payload[ $key ][ $index ][ $childKey ] = self::chained( $group[ $childKey ], $child['field'] );
}
}
}
}
}
return $payload;
}
// ── Field types ──────────────────────────────────────────────────────
/**
* Whether a field stores a yes/no answer: consent, toggle, or a single
* checkbox (an older checkbox with options is a checkbox group).
*
* @param array $field Field node.
*/
private static function isYesNo( array $field ): bool {
$type = (string) ( $field['type'] ?? '' );
if ( ! in_array( $type, self::YES_NO_TYPES, true ) ) {
return false;
}
return 'checkbox' !== $type || empty( self::optionMap( $field ) );
}
/**
* Whether a value is a list of stored upload records.
*
* @param mixed $value Value.
*/
private static function isUploadList( $value ): bool {
if ( ! is_array( $value ) || ! $value || ! class_exists( '\SubtleForms\Uploads\Uploads' ) ) {
return false;
}
foreach ( $value as $item ) {
if ( ! \SubtleForms\Uploads\Uploads::isRecord( $item ) ) {
return false;
}
}
return true;
}
/**
* Option value => label for a choice field.
*
* @param array $field Field node.
* @return array
*/
private static function optionMap( array $field ): array {
$options = EntryValues::attr( $field, 'options' );
$labels = array();
if ( ! is_array( $options ) ) {
return $labels;
}
foreach ( $options as $option ) {
if ( is_array( $option ) && isset( $option['value'] ) && is_scalar( $option['value'] ) ) {
$label = $option['label'] ?? $option['value'];
$labels[ (string) $option['value'] ] = wp_strip_all_tags( (string) ( '' !== (string) $label ? $label : $option['value'] ) );
}
}
return $labels;
}
/**
* A matrix answer with its row and column names.
*
* One answer per row (`{ row: column }`) reads "Speed: Good; Price: OK".
* Several per row (`{ row: { column: true } }`) reads "Mon: AM, PM".
* Rows and columns may be plain strings or { label, value } pairs.
*
* @param array $value Stored grid.
* @param array $field Field node.
* @return string
*/
private static function matrix( array $value, array $field ): string {
$rowNames = self::gridNames( EntryValues::attr( $field, 'rows' ) );
$colNames = self::gridNames( EntryValues::attr( $field, 'columns' ) );
// Rows in the order the form shows them, then any others stored.
$order = array_keys( $rowNames );
foreach ( array_keys( $value ) as $k ) {
if ( ! in_array( (string) $k, $order, true ) ) {
$order[] = (string) $k;
}
}
$lines = array();
foreach ( $order as $rowKey ) {
if ( ! array_key_exists( $rowKey, $value ) ) {
continue;
}
$answer = $value[ $rowKey ];
$chosen = array();
if ( is_array( $answer ) ) {
$isList = array_keys( $answer ) === range( 0, count( $answer ) - 1 );
foreach ( $answer as $col => $on ) {
$colKey = $isList ? $on : $col;
if ( ! $isList && ! FieldMapper::isChecked( $on ) ) {
continue;
}
if ( is_scalar( $colKey ) && '' !== (string) $colKey ) {
$chosen[] = $colNames[ (string) $colKey ] ?? (string) $colKey;
}
}
} elseif ( is_scalar( $answer ) && '' !== (string) $answer ) {
$chosen[] = $colNames[ (string) $answer ] ?? (string) $answer;
}
if ( $chosen ) {
$lines[] = ( $rowNames[ $rowKey ] ?? $rowKey ) . ': ' . implode( ', ', $chosen );
}
}
return implode( '; ', $lines );
}
/**
* Stored key => shown name for matrix rows or columns.
*
* @param mixed $list Rows or columns setting.
* @return array
*/
private static function gridNames( $list ): array {
$out = array();
foreach ( is_array( $list ) ? $list : array() as $item ) {
if ( is_array( $item ) ) {
$label = (string) ( $item['label'] ?? ( $item['value'] ?? '' ) );
$key = (string) ( $item['value'] ?? $label );
} elseif ( is_scalar( $item ) ) {
$label = (string) $item;
$key = $label;
} else {
continue;
}
if ( '' !== $key ) {
$out[ $key ] = wp_strip_all_tags( $label );
}
}
return $out;
}
/**
* Labels chosen at each level of a chained select.
*
* `levels` is a list of dropdowns, each with its own options. Without
* it, `options` is a tree and each choice's `children` are the next level.
*
* @param array $value Stored choices, one per level.
* @param array $field Field node.
* @return string[]
*/
private static function chained( array $value, array $field ): array {
$levels = EntryValues::attr( $field, 'levels' );
$levels = is_array( $levels ) && array() !== $levels ? array_values( $levels ) : null;
$nodes = EntryValues::attr( $field, 'options' );
$nodes = is_array( $nodes ) ? $nodes : array();
$out = array();
foreach ( array_values( $value ) as $depth => $chosen ) {
if ( ! is_scalar( $chosen ) || '' === (string) $chosen ) {
continue;
}
$options = null !== $levels
? ( isset( $levels[ $depth ]['options'] ) && is_array( $levels[ $depth ]['options'] ) ? $levels[ $depth ]['options'] : array() )
: $nodes;
$label = (string) $chosen;
$next = array();
foreach ( $options as $option ) {
if ( ! is_array( $option ) || (string) ( $option['value'] ?? '' ) !== (string) $chosen ) {
continue;
}
// A later level can repeat a value under different parents.
if ( null !== $levels && $depth > 0 && isset( $option['parent'] ) && '' !== (string) $option['parent']
&& (string) $option['parent'] !== (string) ( array_values( $value )[ $depth - 1 ] ?? '' ) ) {
continue;
}
$label = wp_strip_all_tags( (string) ( $option['label'] ?? $chosen ) );
$next = is_array( $option['children'] ?? null ) ? $option['children'] : array();
break;
}
$nodes = $next;
$out[] = $label;
}
return $out;
}
/**
* A date, time or date and time in the field's display format.
*
* Answers are stored as ISO values (2026-06-15, 09:30, 2026-06-15T14:30).
* Anything else is shown as stored.
*
* @param string $value Stored value.
* @param string $type date, time or datetime.
* @param array $field Field node.
* @return string
*/
private static function date( string $value, string $type, array $field ): string {
$value = trim( $value );
// The field's format may be a preset, "site" or "custom" (2.9.0), or the
// free text a 2.8 field saved: DateRules reads all of them.
$format = DateRules::format(
array(
'format' => EntryValues::attr( $field, 'format' ),
'customFormat' => EntryValues::attr( $field, 'customFormat' ),
),
$type
);
$patterns = array(
'date' => '/^\d{4}-\d{2}-\d{2}$/',
'time' => '/^\d{1,2}:\d{2}(:\d{2})?$/',
'datetime' => '/^\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2}(:\d{2})?$/',
);
if ( '' === $value || ! preg_match( $patterns[ $type ], $value ) ) {
return $value;
}
$utc = new \DateTimeZone( 'UTC' );
$date = 'time' === $type
? \DateTimeImmutable::createFromFormat( '!Y-m-d H:i', '2000-01-01 ' . substr( $value, 0, 5 ), $utc )
: new \DateTimeImmutable( str_replace( 'T', ' ', $value ), $utc );
if ( ! $date ) {
return $value;
}
// wp_date() translates month and day names; the zone is UTC so the
// answer is shown as typed, never shifted.
return function_exists( 'wp_date' )
? (string) wp_date( $format, $date->getTimestamp(), $utc )
: $date->format( $format );
}
// ── Strings ──────────────────────────────────────────────────────────
/**
* Character length, multibyte safe.
*
* @param string $text Text.
*/
private static function length( string $text ): int {
return function_exists( 'mb_strlen' ) ? mb_strlen( $text, 'UTF-8' ) : strlen( $text );
}
/**
* The first $length characters, multibyte safe.
*
* @param string $text Text.
* @param int $length Characters.
*/
private static function slice( string $text, int $length ): string {
return function_exists( 'mb_substr' ) ? mb_substr( $text, 0, $length, 'UTF-8' ) : substr( $text, 0, $length );
}
}