> */ public static function identifier_keys(): array { return array( // WooCommerce 9.2+ core, then the three most-installed GTIN plugins. 'gtin' => array( '_global_unique_id', '_wpm_gtin_code', '_gtin', 'hwp_var_gtin', '_woo_uec_gtin', '_alg_ean' ), 'gtin8' => array( '_gtin8', '_woo_uec_gtin8' ), 'gtin12' => array( '_gtin12', '_upc', '_woo_uec_upc' ), 'gtin13' => array( '_gtin13', '_ean', '_woo_uec_ean' ), 'gtin14' => array( '_gtin14' ), 'mpn' => array( '_mpn', '_wpm_mpn_code', '_woo_uec_mpn' ), 'isbn' => array( '_isbn', '_woo_uec_isbn' ), ); } /** * Attribute-based fields Google understands for apparel and variants. * * @return array> */ public static function attribute_keys(): array { return array( 'color' => array( 'color', 'colour', 'farbe' ), 'size' => array( 'size', 'groesse', 'größe' ), 'material' => array( 'material', 'materials' ), 'pattern' => array( 'pattern', 'muster' ), ); } /** * Every identifier we can find for a product. * * @param \WC_Product $product The product. * @return array */ public static function identifiers( $product ): array { $out = array(); foreach ( self::identifier_keys() as $field => $keys ) { foreach ( $keys as $key ) { $value = trim( (string) $product->get_meta( $key, true ) ); if ( '' !== $value ) { $out[ $field ] = $value; break; } } } // A bare GTIN of a known length is also the specific typed identifier, // which is what Google's validator actually looks for. if ( isset( $out['gtin'] ) ) { $digits = preg_replace( '/\D/', '', $out['gtin'] ); $length = strlen( (string) $digits ); $map = array( 8 => 'gtin8', 12 => 'gtin12', 13 => 'gtin13', 14 => 'gtin14' ); if ( isset( $map[ $length ] ) && ! isset( $out[ $map[ $length ] ] ) ) { $out[ $map[ $length ] ] = (string) $digits; } } return $out; } /** * Colour, size, material and pattern from product attributes or meta. * * @param \WC_Product $product The product. * @return array */ public static function attributes( $product ): array { $out = array(); foreach ( self::attribute_keys() as $field => $names ) { foreach ( $names as $name ) { $value = $product->get_attribute( $name ); if ( '' === $value ) { $value = $product->get_attribute( 'pa_' . $name ); } if ( '' !== $value ) { // Attributes come back comma-separated; schema wants one value. $out[ $field ] = trim( (string) explode( ',', $value )[0] ); break; } } } return $out; } /** * Physical dimensions and weight, in the units Schema.org expects. * * @param \WC_Product $product The product. * @return array> */ public static function measurements( $product ): array { $out = array(); $unit = get_option( 'woocommerce_dimension_unit', 'cm' ); foreach ( array( 'width' => 'width', 'height' => 'height', 'depth' => 'length' ) as $field => $getter ) { $value = $product->{'get_' . $getter}(); if ( '' !== (string) $value && (float) $value > 0 ) { $out[ $field ] = array( '@type' => 'QuantitativeValue', 'value' => (string) $value, 'unitCode' => self::unit_code( (string) $unit ), ); } } $weight = $product->get_weight(); if ( '' !== (string) $weight && (float) $weight > 0 ) { $out['weight'] = array( '@type' => 'QuantitativeValue', 'value' => (string) $weight, 'unitCode' => self::unit_code( (string) get_option( 'woocommerce_weight_unit', 'kg' ) ), ); } return $out; } /** * WooCommerce unit slug → UN/CEFACT code, which is what Schema.org wants. */ private static function unit_code( string $unit ): string { $map = array( 'cm' => 'CMT', 'm' => 'MTR', 'mm' => 'MMT', 'in' => 'INH', 'yd' => 'YRD', 'kg' => 'KGM', 'g' => 'GRM', 'lbs' => 'LBR', 'oz' => 'ONZ', ); return $map[ $unit ] ?? strtoupper( $unit ); } /** * Shipping details for the first matching zone — Merchant Center flags * offers without them. * * @param \WC_Product $product The product. * @return array|null */ public static function shipping( $product, array $settings ): ?array { if ( empty( $settings['shipping_details'] ) || ! $product->needs_shipping() ) { return null; } $country = (string) ( WC()->countries ? WC()->countries->get_base_country() : '' ); if ( '' === $country ) { return null; } $min = max( 0, (int) $settings['handling_days_min'] ); $max = max( $min, (int) $settings['handling_days_max'] ); $tmin = max( 0, (int) $settings['transit_days_min'] ); $tmax = max( $tmin, (int) $settings['transit_days_max'] ); return array( '@type' => 'OfferShippingDetails', 'shippingDestination' => array( '@type' => 'DefinedRegion', 'addressCountry' => $country, ), 'deliveryTime' => array( '@type' => 'ShippingDeliveryTime', 'handlingTime' => array( '@type' => 'QuantitativeValue', 'minValue' => $min, 'maxValue' => $max, 'unitCode' => 'DAY', ), 'transitTime' => array( '@type' => 'QuantitativeValue', 'minValue' => $tmin, 'maxValue' => $tmax, 'unitCode' => 'DAY', ), 'businessDays' => array( '@type' => 'OpeningHoursSpecification', 'dayOfWeek' => array( 'https://schema.org/Monday', 'https://schema.org/Tuesday', 'https://schema.org/Wednesday', 'https://schema.org/Thursday', 'https://schema.org/Friday', ), ), ), ); } /** * Merchant return policy — the other field Merchant Center demands. * * @return array|null */ public static function return_policy( array $settings ): ?array { if ( empty( $settings['return_policy'] ) ) { return null; } $days = max( 0, (int) $settings['return_days'] ); $country = (string) ( function_exists( 'WC' ) && WC()->countries ? WC()->countries->get_base_country() : '' ); return array_filter( array( '@type' => 'MerchantReturnPolicy', 'applicableCountry' => $country ?: null, 'returnPolicyCategory' => $days > 0 ? 'https://schema.org/MerchantReturnFiniteReturnWindow' : 'https://schema.org/MerchantReturnNotPermitted', 'merchantReturnDays' => $days > 0 ? $days : null, 'returnMethod' => $days > 0 ? 'https://schema.org/ReturnByMail' : null, 'returnFees' => $days > 0 ? ( ! empty( $settings['return_free'] ) ? 'https://schema.org/FreeReturn' : 'https://schema.org/ReturnShippingFees' ) : null, ) ); } /** * Up to five published reviews as Review nodes — Google recommends the * field, and a Product with reviews earns star treatment in results. * * @param \WC_Product $product The product. * @return array> */ public static function reviews( $product ): array { $comments = get_comments( array( 'post_id' => $product->get_id(), 'status' => 'approve', 'type' => 'review', 'number' => 5, 'meta_key' => 'rating', // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key ) ); $out = array(); foreach ( (array) $comments as $comment ) { $rating = (int) get_comment_meta( $comment->comment_ID, 'rating', true ); if ( $rating < 1 ) { continue; } $out[] = array( '@type' => 'Review', 'reviewRating' => array( '@type' => 'Rating', 'ratingValue' => (string) $rating, 'bestRating' => '5', 'worstRating' => '1', ), 'author' => array( '@type' => 'Person', 'name' => (string) $comment->comment_author, ), 'datePublished' => gmdate( 'Y-m-d', (int) strtotime( (string) $comment->comment_date_gmt ) ), 'reviewBody' => wp_strip_all_tags( (string) $comment->comment_content ), ); } return $out; } /** * Merchant fields stored as per-product meta → their feed key. * * These are the Google/Meta catalog attributes that have no WooCommerce * equivalent, so the shop stores them on the product and we pass them * straight through. * * @return array */ public static function merchant_fields(): array { return array( '_airanksuite_age_group' => 'age_group', '_airanksuite_gender' => 'gender', '_airanksuite_adult' => 'adult', '_airanksuite_size_system' => 'size_system', '_airanksuite_size_type' => 'size_type', '_airanksuite_energy_rating' => 'energy_efficiency_class', '_airanksuite_unit_pricing' => 'unit_pricing_measure', '_airanksuite_multipack' => 'multipack', '_airanksuite_is_bundle' => 'is_bundle', '_airanksuite_map' => 'minimum_price', ); } /** * Allowed values for the merchant fields, for the settings UI. * * @return array> */ public static function merchant_options(): array { return array( 'age_group' => array( '', 'newborn', 'infant', 'toddler', 'kids', 'adult' ), 'gender' => array( '', 'male', 'female', 'unisex' ), 'adult' => array( '', 'yes', 'no' ), 'size_system' => array( '', 'US', 'UK', 'EU', 'DE', 'FR', 'IT', 'JP', 'CN', 'BR', 'MEX', 'AU' ), 'size_type' => array( '', 'regular', 'petite', 'plus', 'big and tall', 'maternity' ), 'condition' => array( 'new', 'refurbished', 'used' ), 'energy_efficiency_class' => array( '', 'A+++', 'A++', 'A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G' ), ); } /** * Merchant meta as Schema.org properties, so the on-page markup and the * feed never disagree about the same product. * * @param \WC_Product $product The product. * @return array */ public static function merchant_schema( $product ): array { $out = array(); $map = array( '_airanksuite_age_group' => 'audience', '_airanksuite_gender' => 'audience', '_airanksuite_size_system' => 'sizeSystem', '_airanksuite_size_type' => 'sizeGroup', '_airanksuite_energy_rating' => 'hasEnergyConsumptionDetails', ); $age = (string) $product->get_meta( '_airanksuite_age_group', true ); $gender = (string) $product->get_meta( '_airanksuite_gender', true ); if ( '' !== $age || '' !== $gender ) { $out['audience'] = array_filter( array( '@type' => 'PeopleAudience', 'suggestedGender' => '' !== $gender && 'unisex' !== $gender ? $gender : null, 'suggestedAge' => '' !== $age ? array( '@type' => 'QuantitativeValue', 'name' => $age, ) : null, ) ); } foreach ( array( '_airanksuite_size_system' => 'sizeSystem', '_airanksuite_size_type' => 'sizeGroup' ) as $meta => $property ) { $value = (string) $product->get_meta( $meta, true ); if ( '' !== $value ) { $out[ $property ] = $value; } } $energy = (string) $product->get_meta( '_airanksuite_energy_rating', true ); if ( '' !== $energy ) { $out['hasEnergyConsumptionDetails'] = array( '@type' => 'EnergyConsumptionDetails', 'energyEfficiencyScaleMin' => 'https://schema.org/EUEnergyEfficiencyCategoryG', 'energyEfficiencyScaleMax' => 'https://schema.org/EUEnergyEfficiencyCategoryA3Plus', 'hasEnergyEfficiencyCategory' => $energy, ); } unset( $map ); return $out; } /** * Condition slug → Schema.org URL. */ public static function condition( string $slug ): string { $map = array( 'new' => 'https://schema.org/NewCondition', 'used' => 'https://schema.org/UsedCondition', 'refurbished' => 'https://schema.org/RefurbishedCondition', 'damaged' => 'https://schema.org/DamagedCondition', ); return $map[ $slug ] ?? $map['new']; } /** * Variable products as a ProductGroup with hasVariant. * * A variable product emitted as one Product is a lie about the catalogue: * every size and colour has its own price, stock state and often its own * GTIN, and Google matches merchant listings on the variant, not on the * parent. Emitting the parent alone means the whole group competes on one * price — usually the lowest, which is the one you cannot fulfil. * * Capped at 60 variants: past that the JSON-LD outweighs the page, and a * catalogue with 200 variations on one product has a different problem. * * @param object $product WC product. * @return array Properties to merge, empty when not variable. */ public static function variants( $product ): array { if ( ! is_object( $product ) || ! method_exists( $product, 'get_type' ) || 'variable' !== $product->get_type() ) { return array(); } if ( ! method_exists( $product, 'get_children' ) ) { return array(); } $children = array_slice( (array) $product->get_children(), 0, 60 ); if ( empty( $children ) ) { return array(); } $variants = array(); $currency = function_exists( 'get_woocommerce_currency' ) ? get_woocommerce_currency() : 'USD'; foreach ( $children as $child_id ) { $variation = wc_get_product( (int) $child_id ); if ( ! $variation ) { continue; } $url = (string) $variation->get_permalink(); $node = array_filter( array( '@type' => 'Product', '@id' => $url . '#variant-' . (int) $child_id, 'name' => $variation->get_name(), 'sku' => $variation->get_sku(), 'image' => (string) wp_get_attachment_image_url( (int) $variation->get_image_id(), 'full' ), ) ); foreach ( self::identifiers( $variation ) as $field => $value ) { $node[ $field ] = $value; } // The attributes that distinguish this variant — colour, size, and // whatever else the shop defined. Without them a consumer cannot // tell two variants apart. foreach ( (array) $variation->get_attributes() as $key => $value ) { $value = trim( (string) $value ); if ( '' === $value ) { continue; } $label = strtolower( str_replace( array( 'attribute_', 'pa_' ), '', (string) $key ) ); if ( in_array( $label, array( 'color', 'colour' ), true ) ) { $node['color'] = $value; } elseif ( 'size' === $label ) { $node['size'] = $value; } elseif ( in_array( $label, array( 'material', 'pattern' ), true ) ) { $node[ $label ] = $value; } else { $node['additionalProperty'][] = array( '@type' => 'PropertyValue', 'name' => $label, 'value' => $value, ); } } $price = $variation->get_price(); if ( '' !== (string) $price ) { $node['offers'] = array( '@type' => 'Offer', 'price' => (string) wc_format_decimal( $price, wc_get_price_decimals() ), 'priceCurrency' => $currency, 'availability' => $variation->is_in_stock() ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock', 'url' => $url, ); } $variants[] = $node; } if ( empty( $variants ) ) { return array(); } // variesBy tells a consumer which axis actually differs, so it can // render a picker rather than a list of near-identical products. $varies = array(); foreach ( (array) $product->get_variation_attributes() as $key => $unused ) { $label = strtolower( str_replace( 'pa_', '', (string) $key ) ); if ( in_array( $label, array( 'color', 'colour' ), true ) ) { $varies[] = 'https://schema.org/color'; } elseif ( 'size' === $label ) { $varies[] = 'https://schema.org/size'; } elseif ( 'material' === $label ) { $varies[] = 'https://schema.org/material'; } else { $varies[] = $label; } } return array_filter( array( '@type' => 'ProductGroup', 'productGroupID' => (string) ( $product->get_sku() ?: $product->get_id() ), 'variesBy' => ! empty( $varies ) ? array_values( array_unique( $varies ) ) : null, 'hasVariant' => $variants, ) ); } }