[ * 'format' => [ * 'label' => 'Show as', * 'choices' => [ 'code' => 'Code (RO)', 'name' => 'Name (Romania)' ], * 'default' => 'code', * ], * ] * * The resolver then gets the chosen values (defaults filled in) as its last * argument. Values are only ever one of the declared choices, so no free-text * format string reaches a resolver. * * The normalise / values / sanitize / for_js helpers are pure PHP (unit * tested); the definitions and formatters below them need WooCommerce. */ final class FieldOptions { /** * Today's date output, kept as the default so existing exports don't change. */ public const DEFAULT_DATE = 'ymd_hi'; /** * Fixed date formats, by choice key. "site" and "site_time" read the * site's own format (Settings → General) when the file is written. * * @var array */ private const DATE_FORMATS = [ 'ymd_hi' => 'Y-m-d H:i', 'ymd' => 'Y-m-d', 'dmy' => 'd/m/Y', 'mdy' => 'm/d/Y', ]; /** * Clean option definitions from the registry (built-in or add-on). * * Accepts `choices` as `value => label` or as a plain list of values, and * the shorthand `'format' => [ 'code', 'name' ]`. An option needs at least * two choices; the default falls back to the first choice. * * @param mixed $options Raw `options` entry of a field. * @return array, default: string}> */ public static function normalise( mixed $options ): array { if ( ! is_array( $options ) ) { return []; } $out = []; foreach ( $options as $name => $def ) { if ( ! is_string( $name ) || '' === $name || ! is_array( $def ) ) { continue; } $raw = self::is_list( $def ) ? $def : ( $def['choices'] ?? [] ); $choices = []; if ( is_array( $raw ) ) { $list = self::is_list( $raw ); foreach ( $raw as $value => $label ) { if ( ! is_scalar( $label ) ) { continue; } $value = $list ? (string) $label : (string) $value; if ( '' !== $value ) { $choices[ $value ] = (string) $label; } } } if ( count( $choices ) < 2 ) { continue; } $default = isset( $def['default'] ) && is_scalar( $def['default'] ) ? (string) $def['default'] : ''; if ( ! isset( $choices[ $default ] ) ) { $default = (string) array_key_first( $choices ); } $out[ $name ] = [ 'label' => isset( $def['label'] ) && is_string( $def['label'] ) && '' !== $def['label'] ? $def['label'] : $name, 'choices' => $choices, 'default' => $default, ]; } return $out; } /** * The value of every declared option for one column: the chosen one when * it is a declared choice, otherwise the default. * * @param array, default: string}> $definitions Normalised definitions. * @param mixed $chosen Chosen values for this column. * @return array */ public static function values( array $definitions, mixed $chosen ): array { $chosen = self::to_array( $chosen ); $out = []; foreach ( $definitions as $name => $def ) { $value = $chosen[ $name ] ?? null; $out[ $name ] = is_string( $value ) && isset( $def['choices'][ $value ] ) ? $value : $def['default']; } return $out; } /** * Keep only declared options with declared values, for the given columns. * * @param mixed $raw Untrusted `options` from a request. * @param array, default: string}>> $definitions Definitions by field key (selected fields only). * @return array> */ public static function sanitize( mixed $raw, array $definitions ): array { $out = []; foreach ( self::to_array( $raw ) as $field => $values ) { if ( ! is_string( $field ) || ! isset( $definitions[ $field ] ) ) { continue; } foreach ( self::to_array( $values ) as $name => $value ) { if ( is_string( $name ) && is_string( $value ) && isset( $definitions[ $field ][ $name ]['choices'][ $value ] ) ) { $out[ $field ][ $name ] = $value; } } } return $out; } /** * Definitions as a JSON-friendly list for the admin app. * * @param array, default: string}> $definitions Normalised definitions. * @return array}> */ public static function for_js( array $definitions ): array { $out = []; foreach ( $definitions as $name => $def ) { $choices = []; foreach ( $def['choices'] as $value => $label ) { $choices[] = [ 'value' => (string) $value, 'label' => $label, ]; } $out[] = [ 'key' => (string) $name, 'label' => $def['label'], 'default' => $def['default'], 'choices' => $choices, ]; } return $out; } /** * "Show as" for a country column: code (default, today's output) or name. * * @return array{label: string, choices: array, default: string} */ public static function country_option(): array { $code = WC()->countries->get_base_country(); $code = '' !== $code ? $code : 'US'; return [ 'label' => __( 'Show as', 'modulary-export' ), 'choices' => [ /* translators: %s: example country code, e.g. "RO" */ 'code' => sprintf( __( 'Code (%s)', 'modulary-export' ), $code ), /* translators: %s: example country name, e.g. "Romania" */ 'name' => sprintf( __( 'Name (%s)', 'modulary-export' ), self::country_value( $code, 'name' ) ), ], 'default' => 'code', ]; } /** * "Show as" for a state column: code (default) or name. * * @return array{label: string, choices: array, default: string} */ public static function state_option(): array { $country = WC()->countries->get_base_country(); $state = WC()->countries->get_base_state(); $states = $country ? WC()->countries->get_states( $country ) : false; if ( ! is_array( $states ) || ! isset( $states[ $state ] ) ) { $country = 'US'; $state = 'CA'; } return [ 'label' => __( 'Show as', 'modulary-export' ), 'choices' => [ /* translators: %s: example state code, e.g. "CA" */ 'code' => sprintf( __( 'Code (%s)', 'modulary-export' ), $state ), /* translators: %s: example state name, e.g. "California" */ 'name' => sprintf( __( 'Name (%s)', 'modulary-export' ), self::state_value( $country, $state, 'name' ) ), ], 'default' => 'code', ]; } /** * "Date format" for a date column. A short fixed list; each label shows * 31 January of this year so day-first and month-first can't be confused. * * @return array{label: string, choices: array, default: string} */ public static function date_option(): array { $sample = ( new \DateTimeImmutable( gmdate( 'Y' ) . '-01-31 14:05:00', wp_timezone() ) )->getTimestamp(); $show = static fn( string $format ): string => (string) wp_date( $format, $sample ); return [ 'label' => __( 'Date format', 'modulary-export' ), 'choices' => [ 'ymd_hi' => $show( self::DATE_FORMATS['ymd_hi'] ), 'ymd' => $show( self::DATE_FORMATS['ymd'] ), /* translators: %s: example date, e.g. "31/01/2026" */ 'dmy' => sprintf( __( '%s (day first)', 'modulary-export' ), $show( self::DATE_FORMATS['dmy'] ) ), /* translators: %s: example date, e.g. "01/31/2026" */ 'mdy' => sprintf( __( '%s (month first)', 'modulary-export' ), $show( self::DATE_FORMATS['mdy'] ) ), /* translators: %s: example date in the site's date format */ 'site' => sprintf( __( 'Site format: %s', 'modulary-export' ), $show( self::site_format( false ) ) ), /* translators: %s: example date and time in the site's formats */ 'site_time' => sprintf( __( 'Site format with time: %s', 'modulary-export' ), $show( self::site_format( true ) ) ), ], 'default' => self::DEFAULT_DATE, ]; } /** * Country code → name ("RO" → "Romania"). Unknown or empty codes are * written as they are, so no data is lost. * * @param string $code ISO country code from the order. * @param string $format 'code' | 'name'. */ public static function country_value( string $code, string $format ): string { if ( 'name' !== $format || '' === $code ) { return $code; } $countries = WC()->countries->get_countries(); return isset( $countries[ $code ] ) ? self::plain( (string) $countries[ $code ] ) : $code; } /** * State code → name, looked up in the list of the order's own country * ("RO", "B" → "București"). Countries without a state list store free * text, which is written as it is; so are unknown codes. * * @param string $country ISO country code from the same address. * @param string $state State as stored on the order. * @param string $format 'code' | 'name'. */ public static function state_value( string $country, string $state, string $format ): string { if ( 'name' !== $format || '' === $state || '' === $country ) { return $state; } $states = WC()->countries->get_states( $country ); return is_array( $states ) && isset( $states[ $state ] ) ? self::plain( (string) $states[ $state ] ) : $state; } /** * A WooCommerce date in the chosen format, in the site's timezone and * language. Every format is plain digits, separators and words, so the * CSV writer and the money localising leave it alone. * * @param \WC_DateTime|null $date Date from the order. * @param string $choice Choice key (see date_option()). */ public static function date_value( ?\WC_DateTime $date, string $choice ): string { if ( ! $date ) { return ''; } if ( 'site' === $choice || 'site_time' === $choice ) { $format = self::site_format( 'site_time' === $choice ); } else { $format = self::DATE_FORMATS[ $choice ] ?? self::DATE_FORMATS[ self::DEFAULT_DATE ]; } return $date->date_i18n( $format ); } /** * The site's date format, optionally followed by its time format. * * @param bool $with_time Append the time format. */ private static function site_format( bool $with_time ): string { $date = (string) get_option( 'date_format' ); $date = '' !== $date ? $date : 'Y-m-d'; if ( ! $with_time ) { return $date; } $time = (string) get_option( 'time_format' ); return $date . ' ' . ( '' !== $time ? $time : 'H:i' ); } /** * WooCommerce stores some names with HTML entities ("București"). * * @param string $name Name from WC_Countries. */ private static function plain( string $name ): string { return html_entity_decode( wp_strip_all_tags( $name ), ENT_QUOTES | ENT_HTML5, 'UTF-8' ); } /** * Keys are 0, 1, 2... in order. Same as PHP 8.1's native list check, which * Plugin Check flags because WordPress polyfills it only from 6.5. * * @param array $value Array. */ private static function is_list( array $value ): bool { return array_keys( $value ) === array_keys( array_values( $value ) ); } /** * Arrays and decoded JSON objects (stored requests) as arrays. * * @param mixed $value Value. * @return array */ private static function to_array( mixed $value ): array { if ( is_object( $value ) ) { return get_object_vars( $value ); } return is_array( $value ) ? $value : []; } }