'item'`) * use `resolve_item` instead, which gets one WC_Order_Item_Product. Add-ons * register more through the `modulary_export_fields` filter. * * Custom fields (order and line meta) are not in the registry: any valid * `meta:` / `item_meta:` column is a field too (see CustomFields). * Look a column up with get(), never with all()[ $key ]. */ final class Fields { /** * Cached registry. * * @var array}>|null */ private static ?array $registry = null; /** * Custom field entries built so far, by column key. Rebuilt with the registry. * * @var array}> */ private static array $custom = []; /** * The full registry. * * @return array}> */ public static function all(): array { if ( null !== self::$registry ) { return self::$registry; } $order = __( 'Order', 'modulary-export' ); $customer = __( 'Customer', 'modulary-export' ); $billing = __( 'Billing', 'modulary-export' ); $shipping = __( 'Shipping', 'modulary-export' ); $items = __( 'Items', 'modulary-export' ); $line = __( 'Line item', 'modulary-export' ); $country_option = [ 'format' => FieldOptions::country_option() ]; $state_option = [ 'format' => FieldOptions::state_option() ]; $fields = [ 'order_number' => [ 'label' => __( 'Order ID', 'modulary-export' ), 'group' => $order, 'default' => true, 'resolve' => static fn( \WC_Order $o ) => $o->get_order_number(), ], 'date_created' => [ 'label' => __( 'Date', 'modulary-export' ), 'group' => $order, 'default' => true, 'options' => [ 'format' => FieldOptions::date_option() ], 'resolve' => static fn( \WC_Order $o, array $opt = [] ) => FieldOptions::date_value( $o->get_date_created(), $opt['format'] ?? FieldOptions::DEFAULT_DATE ), ], 'status' => [ 'label' => __( 'Status', 'modulary-export' ), 'group' => $order, 'default' => true, 'resolve' => static fn( \WC_Order $o ) => wc_get_order_status_name( $o->get_status() ), ], 'total' => [ 'label' => __( 'Total', 'modulary-export' ), 'group' => $order, 'default' => true, 'money' => true, 'once' => true, 'resolve' => static fn( \WC_Order $o ) => wc_format_decimal( $o->get_total(), wc_get_price_decimals() ), ], 'subtotal' => [ 'label' => __( 'Subtotal', 'modulary-export' ), 'group' => $order, 'money' => true, 'once' => true, 'resolve' => static fn( \WC_Order $o ) => wc_format_decimal( $o->get_subtotal(), wc_get_price_decimals() ), ], 'total_tax' => [ 'label' => __( 'Tax', 'modulary-export' ), 'group' => $order, 'money' => true, 'once' => true, 'resolve' => static fn( \WC_Order $o ) => wc_format_decimal( $o->get_total_tax(), wc_get_price_decimals() ), ], 'shipping_total' => [ 'label' => __( 'Shipping cost', 'modulary-export' ), 'group' => $order, 'money' => true, 'once' => true, 'resolve' => static fn( \WC_Order $o ) => wc_format_decimal( $o->get_shipping_total(), wc_get_price_decimals() ), ], 'discount_total' => [ 'label' => __( 'Discount', 'modulary-export' ), 'group' => $order, 'money' => true, 'once' => true, 'resolve' => static fn( \WC_Order $o ) => wc_format_decimal( $o->get_discount_total(), wc_get_price_decimals() ), ], 'currency' => [ 'label' => __( 'Currency', 'modulary-export' ), 'group' => $order, 'resolve' => static fn( \WC_Order $o ) => $o->get_currency(), ], 'payment_method' => [ 'label' => __( 'Payment method', 'modulary-export' ), 'group' => $order, 'resolve' => static fn( \WC_Order $o ) => $o->get_payment_method_title(), ], 'shipping_method' => [ 'label' => __( 'Shipping method', 'modulary-export' ), 'group' => $order, 'resolve' => static fn( \WC_Order $o ) => $o->get_shipping_method(), ], 'coupons' => [ 'label' => __( 'Coupons', 'modulary-export' ), 'group' => $order, 'resolve' => static fn( \WC_Order $o ) => implode( ', ', $o->get_coupon_codes() ), ], 'customer_note' => [ 'label' => __( 'Customer note', 'modulary-export' ), 'group' => $order, 'resolve' => static fn( \WC_Order $o ) => $o->get_customer_note(), ], 'customer_name' => [ 'label' => __( 'Customer', 'modulary-export' ), 'group' => $customer, 'default' => true, 'resolve' => static fn( \WC_Order $o ) => $o->get_formatted_billing_full_name(), ], 'customer_email' => [ 'label' => __( 'Email', 'modulary-export' ), 'group' => $customer, 'resolve' => static fn( \WC_Order $o ) => $o->get_billing_email(), ], 'customer_phone' => [ 'label' => __( 'Phone', 'modulary-export' ), 'group' => $customer, 'resolve' => static fn( \WC_Order $o ) => $o->get_billing_phone(), ], 'customer_id' => [ 'label' => __( 'Customer ID', 'modulary-export' ), 'group' => $customer, 'resolve' => static fn( \WC_Order $o ) => $o->get_customer_id() ? $o->get_customer_id() : __( 'Guest', 'modulary-export' ), ], 'billing_company' => [ 'label' => __( 'Company', 'modulary-export' ), 'group' => $billing, 'resolve' => static fn( \WC_Order $o ) => $o->get_billing_company(), ], 'billing_address' => [ 'label' => __( 'Billing address', 'modulary-export' ), 'group' => $billing, 'resolve' => static fn( \WC_Order $o ) => self::one_line( $o->get_formatted_billing_address() ), ], 'billing_country' => [ 'label' => __( 'Billing country', 'modulary-export' ), 'group' => $billing, 'options' => $country_option, 'resolve' => static fn( \WC_Order $o, array $opt = [] ) => FieldOptions::country_value( $o->get_billing_country(), $opt['format'] ?? 'code' ), ], 'billing_state' => [ 'label' => __( 'Billing state', 'modulary-export' ), 'group' => $billing, 'options' => $state_option, 'resolve' => static fn( \WC_Order $o, array $opt = [] ) => FieldOptions::state_value( $o->get_billing_country(), $o->get_billing_state(), $opt['format'] ?? 'code' ), ], 'shipping_name' => [ 'label' => __( 'Ship to', 'modulary-export' ), 'group' => $shipping, 'resolve' => static fn( \WC_Order $o ) => $o->get_formatted_shipping_full_name(), ], 'shipping_address' => [ 'label' => __( 'Shipping address', 'modulary-export' ), 'group' => $shipping, 'resolve' => static fn( \WC_Order $o ) => self::one_line( $o->get_formatted_shipping_address() ), ], 'shipping_phone' => [ 'label' => __( 'Shipping phone', 'modulary-export' ), 'group' => $shipping, 'resolve' => static fn( \WC_Order $o ) => $o->get_shipping_phone(), ], 'shipping_country' => [ 'label' => __( 'Shipping country', 'modulary-export' ), 'group' => $shipping, 'options' => $country_option, 'resolve' => static fn( \WC_Order $o, array $opt = [] ) => FieldOptions::country_value( $o->get_shipping_country(), $opt['format'] ?? 'code' ), ], 'shipping_state' => [ 'label' => __( 'Shipping state', 'modulary-export' ), 'group' => $shipping, 'options' => $state_option, 'resolve' => static fn( \WC_Order $o, array $opt = [] ) => FieldOptions::state_value( $o->get_shipping_country(), $o->get_shipping_state(), $opt['format'] ?? 'code' ), ], 'item_count' => [ 'label' => __( 'Item count', 'modulary-export' ), 'group' => $items, 'resolve' => static fn( \WC_Order $o ) => $o->get_item_count(), ], 'items' => [ 'label' => __( 'Items', 'modulary-export' ), 'group' => $items, 'resolve' => static fn( \WC_Order $o ) => self::items_summary( $o ), ], 'skus' => [ 'label' => __( 'SKUs', 'modulary-export' ), 'group' => $items, 'resolve' => static fn( \WC_Order $o ) => self::skus( $o ), ], // Line-item fields: one value per product line. They are filled // when each row is a product line, and left empty otherwise. 'line_product' => [ 'label' => __( 'Product', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => $i->get_name(), ], 'line_sku' => [ 'label' => __( 'SKU', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => $i->get_product() ? (string) $i->get_product()->get_sku() : '', ], 'line_quantity' => [ 'label' => __( 'Quantity', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => $i->get_quantity(), ], 'line_price' => [ 'label' => __( 'Unit price', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'money' => true, 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => wc_format_decimal( $i->get_quantity() ? (float) $i->get_subtotal() / $i->get_quantity() : 0, wc_get_price_decimals() ), ], 'line_total' => [ 'label' => __( 'Line total', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'money' => true, 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => wc_format_decimal( $i->get_total(), wc_get_price_decimals() ), ], 'line_tax' => [ 'label' => __( 'Line tax', 'modulary-export' ), 'group' => $line, 'scope' => 'item', 'money' => true, 'resolve_item' => static fn( \WC_Order_Item_Product $i ) => wc_format_decimal( $i->get_total_tax(), wc_get_price_decimals() ), ], ]; /** * Filter the exportable fields. * * Order meta and line meta need no entry: any `meta:` / * `item_meta:` column resolves on its own. Register one here only * to give it a resolver of its own. Each entry: * `key => [ 'label' => string, 'group' => string, 'resolve' => callable(WC_Order): scalar, 'default' => bool ]`, * plus `'once' => true` for order money columns that must not repeat on * every product line, or for a per-line column * `key => [ 'label' => string, 'group' => string, 'scope' => 'item', 'resolve_item' => callable(WC_Order_Item_Product, WC_Order): scalar ]`. * A field with per-column choices (shown in the column editor) adds * `'options' => [ 'format' => [ 'label' => string, 'choices' => [ value => label ], 'default' => value ] ]`; * its resolver then gets the chosen values as a last argument, * `array` with defaults filled in (see FieldOptions). * * @param array}> $fields Registry. */ $registry = (array) apply_filters( 'modulary_export_fields', $fields ); foreach ( $registry as $key => $field ) { if ( ! is_array( $field ) ) { continue; } /** * Filter the per-column options one field offers in the column editor. * * Declare options on an add-on field, add or remove choices, or change * a default (e.g. country names instead of codes). Each entry: * `name => [ 'label' => string, 'choices' => [ value => label ], 'default' => value ]`. * The field's resolver receives the chosen values, so only declare * options a resolver understands. * * @param array $options Option definitions of this field. * @param string $key Field key. * @param array $field Field entry. */ $registry[ $key ]['options'] = FieldOptions::normalise( apply_filters( 'modulary_export_field_options', $field['options'] ?? [], (string) $key, $field ) ); } self::$registry = $registry; self::$custom = []; return self::$registry; } /** * One column's field: the registry entry, or for a custom field column * (`meta:`, `item_meta:`) an entry built from its meta key. * Null for unknown keys. * * @param string $key Column key. * @return array{label: string, group: string, resolve?: callable, resolve_item?: callable, scope?: string, once?: bool, money?: bool, default?: bool, options?: array, meta?: string}|null */ public static function get( string $key ): ?array { $registry = self::all(); if ( isset( $registry[ $key ] ) ) { return $registry[ $key ]; } if ( isset( self::$custom[ $key ] ) ) { return self::$custom[ $key ]; } $parsed = CustomFields::parse( $key ); if ( ! $parsed ) { return null; } [ $scope, $meta_key ] = $parsed; $field = [ 'label' => CustomFields::column_label( $meta_key, $scope ), 'group' => 'item' === $scope ? __( 'Custom fields (product lines)', 'modulary-export' ) : __( 'Custom fields', 'modulary-export' ), 'meta' => $meta_key, 'options' => [], ]; if ( 'item' === $scope ) { $field['scope'] = 'item'; $field['resolve_item'] = static fn( \WC_Order_Item_Product $i ) => CustomFields::value( $i, $meta_key ); } else { $field['resolve'] = static fn( \WC_Order $o ) => CustomFields::value( $o, $meta_key ); } self::$custom[ $key ] = $field; return $field; } /** * Registry without callables, for the JS app. * * @return array>}> */ public static function all_for_js(): array { $out = []; foreach ( self::all() as $key => $field ) { $out[] = [ 'key' => $key, 'label' => $field['label'], 'group' => $field['group'], 'default' => ! empty( $field['default'] ), 'scope' => self::scope( $key ), 'options' => FieldOptions::for_js( self::options( $key ) ), ]; } return $out; } /** * Order money columns (`once => true`) are written on an order's first * product line only, so summing the column in a spreadsheet gives the * real total instead of counting each order once per line. * * @param string $key Field key. */ public static function once( string $key ): bool { return ! empty( self::get( $key )['once'] ); } /** * Money columns get the store's decimal separator in the file (see Exporter). * * @param string $key Field key. */ public static function money( string $key ): bool { return ! empty( self::get( $key )['money'] ); } /** * 'item' for per-line fields, 'order' for everything else. * * @param string $key Field key. */ public static function scope( string $key ): string { return 'item' === ( self::get( $key )['scope'] ?? 'order' ) ? 'item' : 'order'; } /** * Per-column options a field declares (normalised), or [] for none. * * @param string $key Field key. * @return array, default: string}> */ public static function options( string $key ): array { return self::get( $key )['options'] ?? []; } /** * Keys flagged as default. * * @return string[] */ public static function default_keys(): array { return array_keys( array_filter( self::all(), static fn( $f ) => ! empty( $f['default'] ) ) ); } /** * Keep only known keys, in the order given: registry keys, and custom * field columns whose meta key is valid (kept exactly, case and all; at * most CustomFields::MAX_COLUMNS of them). * * @param array $keys Requested keys. * @return string[] */ public static function sanitize_keys( array $keys ): array { $known = self::all(); $out = []; $custom = 0; foreach ( $keys as $key ) { if ( ! is_string( $key ) ) { continue; } if ( isset( $known[ $key ] ) ) { $out[] = $key; } elseif ( null !== CustomFields::parse( $key ) ) { ++$custom; if ( $custom <= CustomFields::MAX_COLUMNS ) { $out[] = $key; } } elseif ( isset( $known[ sanitize_key( $key ) ] ) ) { $out[] = sanitize_key( $key ); } } return $out; } /** * Resolve one field for one order to a string. * * @param string $key Field key. * @param \WC_Order $order Order. * @param array $options Chosen options for this column; defaults fill the rest. */ public static function resolve( string $key, \WC_Order $order, array $options = [] ): string { $field = self::get( $key ); if ( ! $field || ! isset( $field['resolve'] ) ) { return ''; } $declared = self::options( $key ); $value = $declared ? ( $field['resolve'] )( $order, FieldOptions::values( $declared, $options ) ) : ( $field['resolve'] )( $order ); return is_scalar( $value ) ? (string) $value : ''; } /** * Resolve a per-line field for one product line. Empty for order fields. * * @param string $key Field key. * @param \WC_Order_Item_Product $item Line item. * @param \WC_Order $order Order the line belongs to. * @param array $options Chosen options for this column; defaults fill the rest. */ public static function resolve_item( string $key, \WC_Order_Item_Product $item, \WC_Order $order, array $options = [] ): string { $field = self::get( $key ); if ( ! $field || ! isset( $field['resolve_item'] ) ) { return ''; } $declared = self::options( $key ); $value = $declared ? ( $field['resolve_item'] )( $item, $order, FieldOptions::values( $declared, $options ) ) : ( $field['resolve_item'] )( $item, $order ); return is_scalar( $value ) ? (string) $value : ''; } /** * "2× Blue T-shirt (M), 1× Mug". * * @param \WC_Order $order Order. */ private static function items_summary( \WC_Order $order ): string { $parts = []; foreach ( $order->get_items() as $item ) { $parts[] = $item->get_quantity() . '× ' . $item->get_name(); } return implode( ', ', $parts ); } /** * Comma-separated SKUs. * * @param \WC_Order $order Order. */ private static function skus( \WC_Order $order ): string { $skus = []; foreach ( $order->get_items() as $item ) { $product = $item instanceof \WC_Order_Item_Product ? $item->get_product() : null; if ( $product && $product->get_sku() ) { $skus[] = $product->get_sku(); } } return implode( ', ', array_unique( $skus ) ); } /** * Formatted address → single line. * * @param string $html Address with
. */ private static function one_line( string $html ): string { return trim( wp_strip_all_tags( str_replace( [ '
', '
', '
' ], ', ', $html ) ) ); } }