." (the * block's full or short name), ":" (a group of the product's blocks), "*." and * "", merged from the most general to the most specific; each value is a label or an array of: label, help, * type (skip|text|textarea|color|repeater), min, max, options, source, post_type, taxonomy, multiple, out (csv|array), * zero, condition, section, order, cast, fields (a repeater's properties), sanitize (a callable). Enum values take their * labels from the entry's options, else from the same map (".", ":", ""). * * @package RoosterBlocks */ namespace Rooster\Blocks\Elementor; defined( 'ABSPATH' ) || exit; /** * Control descriptions: key, type (switcher|number|select|select2|text|textarea|color|repeater), label, default, and * help, min, max, options, source, post_type, taxonomy, multiple, out, zero, condition, section, order, cast, fields, * sanitize where they apply. */ final class ControlMap { /** * The block supports' and the editor's attributes: never a control (Elementor's Style and Advanced tabs). */ public const SKIPPED = array( 'align', 'style', 'className', 'lock', 'metadata', 'anchor', 'backgroundColor', 'textColor', 'linkColor', 'gradient', 'fontSize', 'fontFamily', 'borderColor' ); /** * The control types. */ public const TYPES = array( 'switcher', 'number', 'select', 'select2', 'text', 'textarea', 'color', 'repeater' ); /** * The most posts or terms in a select2 list (the product may lower or raise it: `max`). */ public const MAX_ITEMS = 500; /** * The short name of a block: its name after the namespace ('aieo/toc' → 'toc'). * * @param string $block Block name. */ public static function short( string $block ): string { $at = strpos( $block, '/' ); return false === $at ? $block : substr( $block, $at + 1 ); } /** * The groups a block belongs to (the product's `groups`: group => short or full block names). * * @param string $block Block name. * @param array $rules The product's rules. * @return list */ public static function groups( string $block, array $rules ): array { $out = array(); foreach ( (array) ( $rules['groups'] ?? array() ) as $group => $members ) { if ( in_array( $block, (array) $members, true ) || in_array( self::short( $block ), (array) $members, true ) ) { $out[] = (string) $group; } } return $out; } /** * The keys under which the product's map may describe one name of a block, from the most general to the most * specific. * * @param string $block Block name. * @param string $name Attribute (or enum value). * @param array $rules The product's rules. * @return list */ private static function keys( string $block, string $name, array $rules ): array { $keys = array( $name, '*.' . $name ); foreach ( self::groups( $block, $rules ) as $group ) { $keys[] = $group . ':' . $name; } $keys[] = self::short( $block ) . '.' . $name; $keys[] = $block . '.' . $name; return array_values( array_unique( $keys ) ); } /** * The product's description of an attribute: every entry that names it, merged, the more specific over the more * general (a label from "columns", the bounds from "course-grid.columns"). * * @param string $block Block name. * @param string $key Attribute. * @param array $labels The product's map. * @param array $rules The product's rules (its groups). * @return array */ public static function spec( string $block, string $key, array $labels, array $rules = array() ): array { $out = array(); foreach ( self::keys( $block, $key, $rules ) as $at ) { if ( ! array_key_exists( $at, $labels ) ) { continue; } $entry = $labels[ $at ]; $out = array_merge( $out, is_array( $entry ) ? $entry : array( 'label' => (string) $entry ) ); } return $out; } /** * The label of an enum value: the entry's options, else the product's map, else the value itself. * * @param string $block Block name. * @param string $value The value. * @param array $spec The attribute's description. * @param array $labels The product's map. * @param array $rules The product's rules. */ private static function value_label( string $block, string $value, array $spec, array $labels, array $rules ): string { if ( isset( $spec['options'][ $value ] ) ) { return (string) $spec['options'][ $value ]; } foreach ( array_reverse( self::keys( $block, $value, $rules ) ) as $at ) { if ( '*.' . $value === $at ) { continue; } if ( isset( $labels[ $at ] ) && is_string( $labels[ $at ] ) ) { return $labels[ $at ]; } } return $value; } /** * "productIds" → "Product ids"; "showRating" → "Show rating". * * @param string $key Attribute. */ public static function label_from_key( string $key ): string { $words = (string) preg_replace( '/([a-z0-9])([A-Z])/', '$1 $2', $key ); $words = str_replace( array( '_', '-' ), ' ', $words ); return ucfirst( strtolower( trim( $words ) ) ); } /** * The product's map: its `labels` (an array, or a callable that returns one; the factory calls it once per request * and passes the array). * * @param array $rules The product's rules. * @return array */ public static function labels( array $rules ): array { $labels = $rules['labels'] ?? array(); if ( is_callable( $labels ) ) { $labels = call_user_func( $labels ); } return is_array( $labels ) ? $labels : array(); } /** * The controls of a block: one per attribute that maps, in the block's order (the widget groups them by section). * * @param string $block Block name ('aieo/toc', 'rooster-lms/course-grid'). * @param array $attributes The block's attributes (the registered type's, block supports included). * @param array $rules The product's rules: labels, groups, skip, describe. * @return list> */ public static function controls( string $block, array $attributes, array $rules = array() ): array { $labels = self::labels( $rules ); $skip = array_merge( self::SKIPPED, array_map( 'strval', (array) ( $rules['skip'] ?? array() ) ) ); $out = array(); foreach ( $attributes as $key => $schema ) { $key = (string) $key; if ( in_array( $key, $skip, true ) || ! is_array( $schema ) ) { continue; } $spec = self::spec( $block, $key, $labels, $rules ); $control = self::describe( $block, $key, $schema, $spec, $labels, $rules ); if ( null !== $control && isset( $rules['describe'] ) && is_callable( $rules['describe'] ) ) { $control = call_user_func( $rules['describe'], $control, $block, $attributes ); } if ( is_array( $control ) && in_array( $control['type'] ?? '', self::TYPES, true ) ) { $out[] = $control; } } return $out; } /** * One attribute's control, or null when the map cannot express it. * * @param string $block Block name. * @param string $key Attribute. * @param array $schema Its schema. * @param array $spec The product's description of it. * @param array $labels The product's map (enum values' labels). * @param array $rules The product's rules. * @return array|null */ private static function describe( string $block, string $key, array $schema, array $spec, array $labels, array $rules ): ?array { $force = (string) ( $spec['type'] ?? '' ); if ( 'skip' === $force || ( is_array( $schema['type'] ?? null ) && '' === $force ) ) { return null; // a union type (a nullable value the editor sets): the block keeps its default } $type = is_string( $schema['type'] ?? null ) ? $schema['type'] : 'string'; $default = $schema['default'] ?? null; $numeric = 'number' === $type || 'integer' === $type; $control = array( 'key' => $key, 'label' => isset( $spec['label'] ) ? (string) $spec['label'] : self::label_from_key( $key ), 'default' => $default, ); foreach ( array( 'help', 'condition', 'section', 'order', 'sanitize' ) as $extra ) { if ( isset( $spec[ $extra ] ) ) { $control[ $extra ] = $spec[ $extra ]; } } if ( 'color' === $force ) { $control['type'] = 'color'; $control['default'] = is_scalar( $default ) ? (string) $default : ''; return $control; } if ( 'repeater' === $force ) { $properties = $schema['items']['properties'] ?? null; if ( 'array' !== $type || ! is_array( $properties ) ) { return null; } $control['type'] = 'repeater'; $control['default'] = array(); $control['fields'] = self::fields( $block, $properties, (array) ( $spec['fields'] ?? array() ), $labels, $rules ); return array() === $control['fields'] ? null : $control; } if ( isset( $spec['source'] ) || ( ! empty( $spec['multiple'] ) && isset( $spec['options'] ) ) ) { $control['type'] = 'select2'; $control['multiple'] = ! empty( $spec['multiple'] ); foreach ( array( 'source', 'post_type', 'taxonomy', 'zero', 'options' ) as $extra ) { if ( isset( $spec[ $extra ] ) ) { $control[ $extra ] = $spec[ $extra ]; } } if ( $control['multiple'] ) { // A list is written back as the block reads it: an array attribute an array, a string one a CSV. $control['out'] = isset( $spec['out'] ) ? (string) $spec['out'] : ( 'array' === $type ? 'array' : 'csv' ); $control['default'] = array(); } else { $control['value'] = $numeric ? 'id' : 'key'; $control['default'] = $numeric ? (string) (int) $default : ( is_scalar( $default ) ? (string) $default : '' ); } return $control; } if ( 'boolean' === $type ) { $control['type'] = 'switcher'; $control['default'] = ! empty( $default ) ? 'yes' : ''; return $control; } if ( $numeric && is_array( $schema['enum'] ?? null ) ) { $control['type'] = 'select'; $control['cast'] = 'int'; $control['options'] = array(); foreach ( $schema['enum'] as $value ) { $control['options'][ (string) $value ] = self::value_label( $block, (string) $value, $spec, $labels, $rules ); } $control['default'] = (string) $default; return $control; } if ( $numeric ) { $control['type'] = 'number'; $control['min'] = isset( $spec['min'] ) ? (int) $spec['min'] : 0; if ( isset( $spec['max'] ) ) { $control['max'] = (int) $spec['max']; } return $control; } if ( 'string' === $type && ( is_array( $schema['enum'] ?? null ) || isset( $spec['options'] ) ) ) { $values = is_array( $schema['enum'] ?? null ) ? array_map( 'strval', $schema['enum'] ) : array_map( 'strval', array_keys( (array) $spec['options'] ) ); $control['type'] = 'select'; $control['options'] = array(); foreach ( $values as $value ) { $control['options'][ $value ] = self::value_label( $block, $value, $spec, $labels, $rules ); } $control['default'] = is_scalar( $default ) ? (string) $default : ''; return $control; } if ( 'string' === $type ) { $control['type'] = 'textarea' === $force ? 'textarea' : 'text'; $control['default'] = is_scalar( $default ) ? (string) $default : ''; return $control; } return null; // arrays and objects: the block keeps its default } /** * The fields of a repeater: one per property the map can express (a number, a string, a boolean, a select2), each * described by the repeater's `fields` entry, else by the product's map ("*." ...). * * @param string $block Block name. * @param array $properties The items schema's properties. * @param array $fields The repeater's own descriptions of its properties. * @param array $labels The product's map. * @param array $rules The product's rules. * @return list> */ private static function fields( string $block, array $properties, array $fields, array $labels, array $rules ): array { $out = array(); foreach ( $properties as $key => $schema ) { $key = (string) $key; if ( ! is_array( $schema ) || ! in_array( $schema['type'] ?? '', array( 'number', 'integer', 'string', 'boolean' ), true ) ) { continue; } $spec = array_merge( self::spec( $block, $key, $labels, $rules ), is_array( $fields[ $key ] ?? null ) ? $fields[ $key ] : array() ); $field = self::describe( $block, $key, $schema, $spec, $labels, $rules ); if ( null === $field || in_array( $field['type'], array( 'repeater', 'color' ), true ) || ! empty( $field['multiple'] ) ) { continue; } if ( 'number' === $field['type'] && ! isset( $schema['default'] ) ) { $field['default'] = $field['min']; // a new row starts at the lowest value } unset( $field['section'], $field['order'] ); $out[] = $field; } return $out; } /** * The controls grouped by section, in the product's order: `sections` (section key => label) first, then any other * section a control names (labelled by its key). Within a section, a control's `order` first (lowest first), then * the block's order. A control without a section is in the first section. * * @param list> $controls The controls. * @param array $sections Section key => label (at least one). * @return array>}> */ public static function sections( array $controls, array $sections ): array { $out = array(); foreach ( $sections as $key => $label ) { $out[ (string) $key ] = array( 'label' => (string) $label, 'controls' => array(), ); } $first = (string) array_key_first( $out ); $place = array(); foreach ( $controls as $i => $control ) { $section = isset( $control['section'] ) && '' !== $control['section'] ? (string) $control['section'] : $first; if ( ! isset( $out[ $section ] ) ) { $out[ $section ] = array( 'label' => self::label_from_key( $section ), 'controls' => array(), ); } $place[ $section ][] = array( isset( $control['order'] ) ? (int) $control['order'] : PHP_INT_MAX, $i, $control ); } foreach ( $place as $section => $list ) { usort( $list, static fn( array $a, array $b ): int => array( $a[0], $a[1] ) <=> array( $b[0], $b[1] ) ); $out[ $section ]['controls'] = array_column( $list, 2 ); } return $out; } /** * Block attributes from a widget's settings (the inverse of controls(), and the sanitiser). * * @param string $block Block name. * @param array $attributes The block's attributes. * @param array $settings The widget's settings for display. * @param array $rules The product's rules. * @return array */ public static function attrs( string $block, array $attributes, array $settings, array $rules = array() ): array { $out = array(); foreach ( self::controls( $block, $attributes, $rules ) as $control ) { $key = (string) $control['key']; if ( ! array_key_exists( $key, $settings ) ) { continue; } $value = self::value( $control, $settings[ $key ] ); if ( null !== $value ) { $out[ $key ] = $value; } } return $out; } /** * One setting as the block's attribute value; null leaves the block's default. * * @param array $control The control. * @param mixed $value The setting. * @return mixed */ public static function value( array $control, $value ) { if ( isset( $control['sanitize'] ) && is_callable( $control['sanitize'] ) ) { return call_user_func( $control['sanitize'], $value ); } switch ( $control['type'] ) { case 'switcher': return 'yes' === $value || true === $value || '1' === $value || 1 === $value; case 'number': if ( ! is_numeric( $value ) ) { return null; } $n = (int) $value; $n = isset( $control['min'] ) ? max( (int) $control['min'], $n ) : $n; return isset( $control['max'] ) ? min( (int) $control['max'], $n ) : $n; case 'select': if ( ( is_string( $value ) || is_int( $value ) ) && isset( $control['options'][ (string) $value ] ) ) { return 'int' === ( $control['cast'] ?? '' ) ? (int) $value : (string) $value; } return null; case 'select2': return self::picked( $control, $value ); case 'color': return is_string( $value ) ? sanitize_hex_color( $value ) : null; case 'repeater': return self::rows( $control, $value ); case 'textarea': return is_scalar( $value ) ? sanitize_textarea_field( (string) $value ) : null; default: return is_scalar( $value ) ? sanitize_text_field( (string) $value ) : null; // the block escapes it where it prints it } } /** * A select2 setting: one ID (or, for a string attribute, one key), or a list of IDs or option keys written as a * CSV or an array. A list may arrive as comma-separated IDs (the text field above the list limit). * * @param array $control The control. * @param mixed $value The setting. * @return mixed */ private static function picked( array $control, $value ) { if ( empty( $control['multiple'] ) ) { if ( 'key' === ( $control['value'] ?? 'id' ) ) { return is_scalar( $value ) ? sanitize_text_field( (string) $value ) : null; } return is_numeric( $value ) ? max( 0, (int) $value ) : null; } $list = is_array( $value ) ? $value : ( is_string( $value ) ? explode( ',', $value ) : array() ); $keep = array(); foreach ( $list as $one ) { if ( ! is_scalar( $one ) ) { continue; } $one = trim( (string) $one ); if ( isset( $control['options'] ) ) { if ( isset( $control['options'][ $one ] ) && ! in_array( $one, $keep, true ) ) { $keep[] = $one; } } elseif ( ctype_digit( $one ) && (int) $one > 0 && ! in_array( (int) $one, $keep, true ) ) { $keep[] = (int) $one; } } return 'array' === ( $control['out'] ?? 'csv' ) ? $keep : implode( ',', $keep ); } /** * A repeater's rows: each row an object of its fields, each field sanitised as a control; a field that is absent or * invalid takes its default. Rows that are not arrays are dropped; Elementor's row `_id` is not a field. * * @param array $control The repeater. * @param mixed $value The setting. * @return list> */ private static function rows( array $control, $value ): array { $rows = array(); foreach ( is_array( $value ) ? $value : array() as $row ) { if ( ! is_array( $row ) ) { continue; } $item = array(); foreach ( (array) ( $control['fields'] ?? array() ) as $field ) { $one = array_key_exists( $field['key'], $row ) ? self::value( $field, $row[ $field['key'] ] ) : null; if ( null === $one ) { $one = self::value( $field, $field['default'] ); } $item[ $field['key'] ] = $one; } $rows[] = $item; } return $rows; } }