(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 '' . esc_attr__( 'Signature', 'subtleforms' ) . ''; } 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 ); } }