$labels Custom column headers, keyed by field. * @param string $format 'csv' or 'xlsx'. The delimiter applies to CSV only. * @param array $options Per-column options, field → option → value (e.g. `[ 'billing_country' => [ 'format' => 'name' ] ]`). */ public function __construct( public readonly Filters $filters, public readonly array $fields, public readonly string $delimiter = ',', public readonly string $rows = 'order', public readonly array $labels = [], public readonly string $format = Format::CSV, public readonly array $options = [], ) {} /** * Build from untrusted input. * * @param array $input Raw request body / query. */ public static function from_array( array $input ): self { $fields = Fields::sanitize_keys( (array) ( $input['fields'] ?? [] ) ); if ( ! $fields ) { $fields = Fields::default_keys(); } $rows = sanitize_key( (string) ( $input['rows'] ?? 'order' ) ); return new self( Filters::from_array( (array) ( $input['filters'] ?? [] ) ), $fields, CsvWriter::sanitize_delimiter( (string) ( $input['delimiter'] ?? ',' ) ), in_array( $rows, [ 'order', 'item' ], true ) ? $rows : 'order', self::sanitize_labels( (array) ( $input['labels'] ?? [] ), $fields ), Format::sanitize( $input['format'] ?? Format::CSV ), self::sanitize_options( $input['options'] ?? [], $fields ), ); } /** * Keep custom headers only for selected fields; plain text, 100 chars max. * Custom field keys (`meta:Gift note`) match exactly; built-in keys also * after sanitize_key(), as before. * * @param array $labels Raw labels. * @param string[] $fields Selected field keys. * @return array */ private static function sanitize_labels( array $labels, array $fields ): array { $out = []; foreach ( $labels as $key => $label ) { $key = in_array( (string) $key, $fields, true ) ? (string) $key : sanitize_key( (string) $key ); if ( ! in_array( $key, $fields, true ) || ! is_string( $label ) ) { continue; } $label = trim( sanitize_text_field( $label ) ); if ( '' !== $label ) { $out[ $key ] = mb_substr( $label, 0, 100 ); } } return $out; } /** * Keep options only for selected fields, and only option names and values * the field declares in the registry. Anything else is dropped. * * @param mixed $options Raw options: field → option → value. * @param string[] $fields Selected field keys. * @return array> */ private static function sanitize_options( mixed $options, array $fields ): array { $declared = []; foreach ( $fields as $key ) { $field_options = Fields::options( $key ); if ( $field_options ) { $declared[ $key ] = $field_options; } } return FieldOptions::sanitize( $options, $declared ); } /** * Column headers for the current field selection. * * @return string[] */ public function headers(): array { $labels = $this->labels; return array_map( static fn( string $k ) => $labels[ $k ] ?? (string) ( Fields::get( $k )['label'] ?? $k ), $this->fields ); } /** * Plain array for JSON / transient storage. * * @return array */ public function to_array(): array { return [ 'filters' => $this->filters->to_array(), 'fields' => $this->fields, 'delimiter' => $this->delimiter, 'rows' => $this->rows, 'labels' => (object) $this->labels, 'format' => $this->format, 'options' => (object) $this->options, ]; } }