*/ private const LOCATION_FIELDS = array( 'name', 'business_type', 'street', 'street2', 'postal_code', 'city', 'region', 'country', 'phone', 'email', 'latitude', 'longitude', 'map_url', 'booking_url', 'price_range', 'image_url', ); /** * A representative subset of schema.org LocalBusiness subtypes, grouped so * a dentist does not have to read past 40 shop types to find "Dentist". * * @return array> */ public static function type_groups(): array { return array( 'General' => array( 'LocalBusiness', 'ProfessionalService', 'Organization', 'Corporation' ), 'Health & medical' => array( 'Dentist', 'Physician', 'MedicalClinic', 'MedicalBusiness', 'Hospital', 'Pharmacy', 'Optician', 'Physiotherapy', 'PsychologicalTreatment', 'VeterinaryCare', 'DiagnosticLab', ), 'Legal & finance' => array( 'Attorney', 'LegalService', 'Notary', 'AccountingService', 'FinancialService', 'InsuranceAgency', 'BankOrCreditUnion', 'RealEstateAgent', ), 'Food & hospitality' => array( 'Restaurant', 'CafeOrCoffeeShop', 'Bakery', 'BarOrPub', 'FastFoodRestaurant', 'IceCreamShop', 'Winery', 'Brewery', 'Distillery', 'Hotel', 'BedAndBreakfast', 'Resort', 'Campground', ), 'Beauty & wellness' => array( 'HealthAndBeautyBusiness', 'BeautySalon', 'HairSalon', 'DaySpa', 'NailSalon', 'TattooParlor', 'ExerciseGym', 'SportsActivityLocation', 'YogaStudio', ), 'Home & trade' => array( 'HomeAndConstructionBusiness', 'Electrician', 'Plumber', 'RoofingContractor', 'GeneralContractor', 'HousePainter', 'Locksmith', 'MovingCompany', 'HVACBusiness', 'CleaningService', 'Carpenter', ), 'Automotive' => array( 'AutomotiveBusiness', 'AutoRepair', 'AutoDealer', 'AutoBodyShop', 'AutoPartsStore', 'AutoRental', 'AutoWash', 'GasStation', 'MotorcycleDealer', ), 'Retail' => array( 'Store', 'ClothingStore', 'ShoeStore', 'JewelryStore', 'Bookstore', 'ComputerStore', 'ElectronicsStore', 'FurnitureStore', 'GardenStore', 'GroceryStore', 'HardwareStore', 'PetStore', 'SportingGoodsStore', 'ToyStore', 'Florist', 'MobilePhoneStore', 'OutletStore', ), 'Services & other' => array( 'TravelAgency', 'Photographer', 'EntertainmentBusiness', 'EmploymentAgency', 'AdvertisingAgency', 'WebDesignCompany', 'ITService', 'EducationalOrganization', 'School', 'Library', 'ChildCare', 'DryCleaningOrLaundry', 'SelfStorage', 'RecyclingCenter', 'TouristInformationCenter', ), ); } /** @return array */ public static function business_types(): array { $flat = array(); foreach ( self::type_groups() as $types ) { foreach ( $types as $type ) { $flat[] = $type; } } return array_values( array_unique( $flat ) ); } /** * Payment methods Google recognises on a business profile. * * @return array */ public static function payment_methods(): array { return array( 'cash' => __( 'Cash', 'ai-rank-suite' ), 'credit_card' => __( 'Credit card', 'ai-rank-suite' ), 'debit_card' => __( 'Debit card', 'ai-rank-suite' ), 'visa' => 'Visa', 'mastercard' => 'Mastercard', 'amex' => 'American Express', 'paypal' => 'PayPal', 'apple_pay' => 'Apple Pay', 'google_pay' => 'Google Pay', 'invoice' => __( 'Invoice', 'ai-rank-suite' ), 'bank_transfer' => __( 'Bank transfer', 'ai-rank-suite' ), 'crypto' => __( 'Cryptocurrency', 'ai-rank-suite' ), ); } /** * Amenities emitted as LocationFeatureSpecification. These are the ones an * assistant is actually asked about — "is it wheelchair accessible", "do * they have parking" — rather than the full schema.org vocabulary. * * @return array */ public static function amenities(): array { return array( 'wheelchair' => __( 'Wheelchair accessible', 'ai-rank-suite' ), 'parking' => __( 'Free parking', 'ai-rank-suite' ), 'street_parking' => __( 'Street parking', 'ai-rank-suite' ), 'wifi' => __( 'Free Wi-Fi', 'ai-rank-suite' ), 'restroom' => __( 'Public restroom', 'ai-rank-suite' ), 'air_con' => __( 'Air conditioning', 'ai-rank-suite' ), 'outdoor' => __( 'Outdoor seating', 'ai-rank-suite' ), 'pets' => __( 'Pet friendly', 'ai-rank-suite' ), 'family' => __( 'Family friendly', 'ai-rank-suite' ), 'delivery' => __( 'Delivery', 'ai-rank-suite' ), 'takeaway' => __( 'Takeaway', 'ai-rank-suite' ), 'appointment' => __( 'By appointment only', 'ai-rank-suite' ), 'walk_ins' => __( 'Walk-ins welcome', 'ai-rank-suite' ), 'ev_charging' => __( 'EV charging', 'ai-rank-suite' ), ); } /** * @return array */ public static function defaults(): array { $hours = array(); foreach ( self::DAYS as $day ) { $hours[ $day ] = array( 'closed' => in_array( $day, array( 'saturday', 'sunday' ), true ), 'open' => '09:00', 'close' => '17:00', 'break_start' => '', 'break_end' => '', ); } return array( 'enabled' => false, 'business_type' => 'LocalBusiness', 'name' => '', 'legal_name' => '', 'description' => '', 'slogan' => '', 'founding_date' => '', 'phone' => '', 'phone_secondary' => '', 'whatsapp' => '', 'fax' => '', 'email' => '', 'price_range' => '', 'currencies' => '', 'payments' => array(), 'amenities' => array(), 'vat_id' => '', 'tax_id' => '', 'registration_id' => '', 'logo_url' => '', 'image_url' => '', 'street' => '', 'street2' => '', 'postal_code' => '', 'city' => '', 'region' => '', 'country' => '', 'latitude' => '', 'longitude' => '', 'map_url' => '', 'booking_url' => '', 'menu_url' => '', 'order_url' => '', // The directories: Google by Place ID (checked live through the // Places API), Bing and Apple by listing URL. All three become sameAs. 'google_place_id' => '', 'bing_url' => '', 'apple_url' => '', 'profiles' => array(), 'languages' => array(), 'areas' => array(), 'services' => array(), 'departments' => array(), 'hours' => $hours, 'special_hours' => array(), 'locations' => array(), 'show_open_now' => true, ); } /** * Sanitise a submitted partial payload. * * Only keys present in the request are returned, so a screen that edits one * section can PUT that section without blanking the rest — the same rule the * keyword editor had to learn the hard way. * * @param array $input Raw values keyed like defaults(). * @param array $current Settings as currently stored. * @return array */ public static function sanitize( array $input, array $current = array() ): array { $defaults = self::defaults(); $values = array(); foreach ( array_keys( $defaults ) as $key ) { if ( ! array_key_exists( $key, $input ) ) { continue; } $raw = $input[ $key ]; $values[ $key ] = match ( $key ) { 'enabled', 'show_open_now' => (bool) $raw, 'email' => sanitize_email( (string) $raw ), 'description' => sanitize_textarea_field( (string) $raw ), 'business_type' => self::type( (string) $raw ), 'logo_url', 'image_url', 'map_url', 'booking_url', 'menu_url', 'order_url', 'bing_url', 'apple_url' => esc_url_raw( (string) $raw ), 'google_place_id' => preg_replace( '/[^A-Za-z0-9_\-]/', '', (string) $raw ) ?? '', 'payments' => self::keys_from( (array) $raw, self::payment_methods() ), 'amenities' => self::keys_from( (array) $raw, self::amenities() ), 'profiles' => self::urls( (array) $raw ), 'languages', 'areas' => self::strings( (array) $raw, 40 ), 'services' => self::services( (array) $raw ), 'departments' => self::departments( (array) $raw ), 'hours' => self::hours( (array) $raw, (array) ( $current['hours'] ?? $defaults['hours'] ) ), 'special_hours' => self::special_hours( (array) $raw ), 'locations' => self::locations( (array) $raw ), default => sanitize_text_field( (string) $raw ), }; } return $values; } private static function type( string $value ): string { return in_array( $value, self::business_types(), true ) ? $value : 'LocalBusiness'; } private static function time( string $value ): string { return preg_match( '/^([01][0-9]|2[0-3]):[0-5][0-9]$/', $value ) ? $value : ''; } /** * @param array $raw Submitted keys. * @param array $catalog Allowed key => label. * @return array */ private static function keys_from( array $raw, array $catalog ): array { $clean = array(); foreach ( $raw as $key ) { $key = sanitize_key( (string) $key ); if ( isset( $catalog[ $key ] ) && ! in_array( $key, $clean, true ) ) { $clean[] = $key; } } return $clean; } /** * @param array $raw Submitted URLs. * @return array */ private static function urls( array $raw ): array { $clean = array(); foreach ( array_slice( $raw, 0, 30 ) as $url ) { // esc_url_raw() happily turns "my facebook page" into a relative URL // rather than rejecting it, and a sameAs pointing at nothing is worse // than no sameAs at all. Require a real scheme and host. $url = esc_url_raw( trim( (string) $url ), array( 'http', 'https' ) ); if ( ! preg_match( '#^https?://[^\s/]+\.[^\s/]#i', $url ) ) { continue; } if ( '' !== $url && ! in_array( $url, $clean, true ) ) { $clean[] = $url; } } return $clean; } /** * @param array $raw Submitted strings. * @param int $limit Maximum entries kept. * @return array */ private static function strings( array $raw, int $limit ): array { $clean = array(); foreach ( array_slice( $raw, 0, $limit ) as $value ) { $value = sanitize_text_field( trim( (string) $value ) ); if ( '' !== $value && ! in_array( $value, $clean, true ) ) { $clean[] = $value; } } return $clean; } /** * @param array $raw Submitted services. * @return array> */ private static function services( array $raw ): array { $clean = array(); foreach ( array_slice( $raw, 0, 60 ) as $service ) { if ( ! is_array( $service ) ) { continue; } $name = sanitize_text_field( trim( (string) ( $service['name'] ?? '' ) ) ); if ( '' === $name ) { continue; } $clean[] = array( 'name' => $name, 'description' => sanitize_textarea_field( (string) ( $service['description'] ?? '' ) ), 'price' => sanitize_text_field( (string) ( $service['price'] ?? '' ) ), 'currency' => sanitize_text_field( (string) ( $service['currency'] ?? '' ) ), 'url' => esc_url_raw( (string) ( $service['url'] ?? '' ) ), ); } return $clean; } /** * @param array $raw Submitted departments. * @return array> */ private static function departments( array $raw ): array { $clean = array(); foreach ( array_slice( $raw, 0, 40 ) as $dept ) { if ( ! is_array( $dept ) ) { continue; } $name = sanitize_text_field( trim( (string) ( $dept['name'] ?? '' ) ) ); if ( '' === $name ) { continue; } $clean[] = array( 'name' => $name, 'business_type' => self::type( (string) ( $dept['business_type'] ?? 'LocalBusiness' ) ), 'phone' => sanitize_text_field( (string) ( $dept['phone'] ?? '' ) ), 'email' => sanitize_email( (string) ( $dept['email'] ?? '' ) ), 'url' => esc_url_raw( (string) ( $dept['url'] ?? '' ) ), ); } return $clean; } /** * @param array $raw Submitted week. * @param array $current Week as currently stored. * @return array> */ private static function hours( array $raw, array $current = array() ): array { $fallback = array() === $current ? self::defaults()['hours'] : $current; $clean = array(); foreach ( self::DAYS as $day ) { // A payload that omits a day is not saying "this day is now open // with no times" — it is saying nothing about that day. Without this // guard, a partial save turns a closed Sunday into an open Sunday // with empty hours, which is exactly the class of silent data loss // the keyword editor already taught us to design against. if ( ! array_key_exists( $day, $raw ) || ! is_array( $raw[ $day ] ) ) { $clean[ $day ] = (array) ( $fallback[ $day ] ?? array() ); continue; } $slot = (array) $raw[ $day ]; $clean[ $day ] = array( 'closed' => ! empty( $slot['closed'] ), 'open' => self::time( (string) ( $slot['open'] ?? '' ) ), 'close' => self::time( (string) ( $slot['close'] ?? '' ) ), 'break_start' => self::time( (string) ( $slot['break_start'] ?? '' ) ), 'break_end' => self::time( (string) ( $slot['break_end'] ?? '' ) ), ); } return $clean; } /** * Holidays and one-off changes. Sorted by date so the list a customer sees * is in the order they will happen, and past entries can be pruned by eye. * * @param array $raw Submitted exceptions. * @return array> */ private static function special_hours( array $raw ): array { $clean = array(); foreach ( array_slice( $raw, 0, 80 ) as $entry ) { if ( ! is_array( $entry ) ) { continue; } $date = trim( (string) ( $entry['date'] ?? '' ) ); if ( ! preg_match( '/^\d{4}-\d{2}-\d{2}$/', $date ) ) { continue; } $until = trim( (string) ( $entry['until'] ?? '' ) ); $clean[] = array( 'date' => $date, 'until' => preg_match( '/^\d{4}-\d{2}-\d{2}$/', $until ) && $until >= $date ? $until : '', 'label' => sanitize_text_field( (string) ( $entry['label'] ?? '' ) ), 'closed' => ! empty( $entry['closed'] ), 'open' => self::time( (string) ( $entry['open'] ?? '' ) ), 'close' => self::time( (string) ( $entry['close'] ?? '' ) ), ); } usort( $clean, static fn( $a, $b ) => strcmp( (string) $a['date'], (string) $b['date'] ) ); return $clean; } /** * @param array $raw Submitted branches. * @return array> */ private static function locations( array $raw ): array { $clean = array(); foreach ( array_slice( $raw, 0, 200 ) as $location ) { if ( ! is_array( $location ) ) { continue; } $entry = array(); foreach ( self::LOCATION_FIELDS as $field ) { $value = (string) ( $location[ $field ] ?? '' ); $entry[ $field ] = match ( $field ) { 'business_type' => '' === $value ? '' : self::type( $value ), 'email' => sanitize_email( $value ), 'map_url', 'booking_url', 'image_url' => esc_url_raw( $value ), default => sanitize_text_field( $value ), }; } // A branch that has not overridden its hours inherits head office's. // Storing the empty array rather than a copy means changing the main // week keeps every branch in step, which is what people expect. $entry['own_hours'] = ! empty( $location['own_hours'] ); $entry['hours'] = $entry['own_hours'] ? self::hours( (array) ( $location['hours'] ?? array() ) ) : array(); if ( '' !== $entry['name'] || '' !== $entry['street'] || '' !== $entry['city'] ) { $clean[] = $entry; } } return $clean; } /** * Build the JSON-LD graph nodes for the whole business. * * @param array $s Settings. * @param string $base Home URL used for @id. * @return array> */ public static function graph( array $s, string $base ): array { $nodes = array( self::node( $s, $base . '#localbusiness', $base ) ); foreach ( (array) ( $s['locations'] ?? array() ) as $index => $location ) { $location = (array) $location; $merged = $s; foreach ( $location as $key => $value ) { // An empty override means "same as head office", so it must not // wipe the inherited value. if ( '' === $value || array() === $value ) { continue; } $merged[ $key ] = $value; } $merged['locations'] = array(); $merged['departments'] = array(); if ( empty( $location['own_hours'] ) ) { $merged['hours'] = $s['hours'] ?? array(); } $node = self::node( $merged, $base . '#location-' . ( (int) $index + 1 ), $base ); $node['parentOrganization'] = array( '@id' => $base . '#localbusiness' ); $nodes[] = $node; } foreach ( (array) ( $s['departments'] ?? array() ) as $index => $dept ) { $dept = (array) $dept; $node = array( '@type' => $dept['business_type'] ?: 'LocalBusiness', '@id' => $base . '#department-' . ( (int) $index + 1 ), 'name' => (string) $dept['name'], 'telephone' => (string) ( $dept['phone'] ?? '' ), 'email' => (string) ( $dept['email'] ?? '' ), 'url' => (string) ( $dept['url'] ?? '' ), 'parentOrganization' => array( '@id' => $base . '#localbusiness' ), ); $nodes[] = array_filter( $node, static fn( $v ) => '' !== $v && array() !== $v ); } return $nodes; } /** * Build one LocalBusiness node. * * @param array $data Business data. * @param string $id Node @id. * @param string $base Home URL. * @return array */ public static function node( array $data, string $id, string $base ): array { $node = array( '@type' => self::type( (string) ( $data['business_type'] ?? '' ) ), '@id' => $id, 'name' => '' !== trim( (string) ( $data['name'] ?? '' ) ) ? (string) $data['name'] : get_bloginfo( 'name' ), 'legalName' => (string) ( $data['legal_name'] ?? '' ), 'description' => (string) ( $data['description'] ?? '' ), 'slogan' => (string) ( $data['slogan'] ?? '' ), 'url' => $base, 'telephone' => (string) ( $data['phone'] ?? '' ), 'faxNumber' => (string) ( $data['fax'] ?? '' ), 'email' => (string) ( $data['email'] ?? '' ), 'priceRange' => (string) ( $data['price_range'] ?? '' ), 'currenciesAccepted' => (string) ( $data['currencies'] ?? '' ), 'vatID' => (string) ( $data['vat_id'] ?? '' ), 'taxID' => (string) ( $data['tax_id'] ?? '' ), 'foundingDate' => (string) ( $data['founding_date'] ?? '' ), 'hasMap' => (string) ( $data['map_url'] ?? '' ), ); foreach ( array( 'logo_url' => 'logo', 'image_url' => 'image' ) as $field => $prop ) { $url = (string) ( $data[ $field ] ?? '' ); if ( '' !== $url ) { $node[ $prop ] = $url; } } // Google wants an image on a LocalBusiness; falling back to the logo is // better than emitting nothing at all. if ( empty( $node['image'] ) && ! empty( $node['logo'] ) ) { $node['image'] = $node['logo']; } $address = array_filter( array( '@type' => 'PostalAddress', 'streetAddress' => trim( (string) ( $data['street'] ?? '' ) . ' ' . (string) ( $data['street2'] ?? '' ) ), 'postalCode' => (string) ( $data['postal_code'] ?? '' ), 'addressLocality' => (string) ( $data['city'] ?? '' ), 'addressRegion' => (string) ( $data['region'] ?? '' ), 'addressCountry' => (string) ( $data['country'] ?? '' ), ) ); if ( count( $address ) > 1 ) { $node['address'] = $address; } if ( '' !== trim( (string) ( $data['latitude'] ?? '' ) ) && '' !== trim( (string) ( $data['longitude'] ?? '' ) ) ) { $node['geo'] = array( '@type' => 'GeoCoordinates', 'latitude' => (string) $data['latitude'], 'longitude' => (string) $data['longitude'], ); } $specs = self::hour_specs( (array) ( $data['hours'] ?? array() ), (array) ( $data['special_hours'] ?? array() ) ); if ( ! empty( $specs ) ) { $node['openingHoursSpecification'] = $specs; } $profiles = (array) ( $data['profiles'] ?? array() ); // The directory listings belong in sameAs too — a Google Maps URL, a // Bing Places page and an Apple Business Connect page are the three // strongest "this is the same entity" signals a local business has. foreach ( array( 'map_url', 'bing_url', 'apple_url' ) as $k ) { $u = (string) ( $data[ $k ] ?? '' ); if ( '' !== $u && ! in_array( $u, $profiles, true ) ) { $profiles[] = $u; } } if ( ! empty( $profiles ) ) { $node['sameAs'] = array_values( $profiles ); } $languages = (array) ( $data['languages'] ?? array() ); if ( ! empty( $languages ) ) { $node['knowsLanguage'] = array_values( $languages ); } $areas = (array) ( $data['areas'] ?? array() ); if ( ! empty( $areas ) ) { $node['areaServed'] = array_map( static fn( $area ) => array( '@type' => 'AdministrativeArea', 'name' => (string) $area ), array_values( $areas ) ); } $payments = (array) ( $data['payments'] ?? array() ); if ( ! empty( $payments ) ) { $catalog = self::payment_methods(); $node['paymentAccepted'] = implode( ', ', array_map( static fn( $key ) => (string) ( $catalog[ $key ] ?? $key ), $payments ) ); } $amenities = (array) ( $data['amenities'] ?? array() ); if ( ! empty( $amenities ) ) { $catalog = self::amenities(); $node['amenityFeature'] = array_map( static fn( $key ) => array( '@type' => 'LocationFeatureSpecification', 'name' => (string) ( $catalog[ $key ] ?? $key ), 'value' => true, ), array_values( $amenities ) ); } $services = (array) ( $data['services'] ?? array() ); if ( ! empty( $services ) ) { $items = array(); foreach ( $services as $service ) { $service = (array) $service; $offer = array( '@type' => 'Offer', 'itemOffered' => array_filter( array( '@type' => 'Service', 'name' => (string) ( $service['name'] ?? '' ), 'description' => (string) ( $service['description'] ?? '' ), 'url' => (string) ( $service['url'] ?? '' ), ) ), ); if ( '' !== (string) ( $service['price'] ?? '' ) ) { $offer['price'] = (string) $service['price']; $offer['priceCurrency'] = (string) ( $service['currency'] ?? ( $data['currencies'] ?? '' ) ); } $items[] = array_filter( $offer ); } $node['hasOfferCatalog'] = array( '@type' => 'OfferCatalog', 'name' => __( 'Services', 'ai-rank-suite' ), 'itemListElement' => $items, ); } $urls = array_filter( array( 'menu' => (string) ( $data['menu_url'] ?? '' ), 'potentialAction' => (string) ( $data['booking_url'] ?? '' ), ) ); if ( isset( $urls['menu'] ) ) { $node['menu'] = $urls['menu']; } if ( isset( $urls['potentialAction'] ) ) { $node['potentialAction'] = array( '@type' => 'ReserveAction', 'target' => array( '@type' => 'EntryPoint', 'urlTemplate' => $urls['potentialAction'], ), ); } return array_filter( $node, static fn( $value ) => '' !== $value && array() !== $value && null !== $value ); } /** * Weekly hours plus dated exceptions, in the shape Google reads. * * @param array $hours Weekly grid. * @param array $special Dated exceptions. * @return array> */ public static function hour_specs( array $hours, array $special = array() ): array { $specs = array(); foreach ( self::DAYS as $day ) { $slot = (array) ( $hours[ $day ] ?? array() ); if ( ! empty( $slot['closed'] ) || '' === (string) ( $slot['open'] ?? '' ) ) { continue; } $day_url = 'https://schema.org/' . ucfirst( $day ); // A lunch break is two windows, not one long one. Emitting a single // 09:00–17:00 span when the practice shuts at noon is how an // assistant ends up telling someone to come at 13:00. $break_start = (string) ( $slot['break_start'] ?? '' ); $break_end = (string) ( $slot['break_end'] ?? '' ); if ( '' !== $break_start && '' !== $break_end && $break_start > (string) $slot['open'] ) { $specs[] = array( '@type' => 'OpeningHoursSpecification', 'dayOfWeek' => $day_url, 'opens' => (string) $slot['open'], 'closes' => $break_start, ); $specs[] = array( '@type' => 'OpeningHoursSpecification', 'dayOfWeek' => $day_url, 'opens' => $break_end, 'closes' => (string) $slot['close'], ); continue; } $specs[] = array( '@type' => 'OpeningHoursSpecification', 'dayOfWeek' => $day_url, 'opens' => (string) $slot['open'], 'closes' => (string) $slot['close'], ); } $today = current_time( 'Y-m-d' ); foreach ( $special as $entry ) { $entry = (array) $entry; $date = (string) ( $entry['date'] ?? '' ); $until = (string) ( $entry['until'] ?? '' ); // Last year's Christmas closure is noise in the markup; drop anything // whose window has already ended. if ( '' === $date || ( '' !== $until ? $until : $date ) < $today ) { continue; } $spec = array( '@type' => 'OpeningHoursSpecification', 'validFrom' => $date, 'validThrough' => '' !== $until ? $until : $date, ); if ( ! empty( $entry['closed'] ) ) { $spec['opens'] = '00:00'; $spec['closes'] = '00:00'; } else { if ( '' === (string) ( $entry['open'] ?? '' ) ) { continue; } $spec['opens'] = (string) $entry['open']; $spec['closes'] = (string) ( $entry['close'] ?? '' ); } $specs[] = $spec; } return $specs; } /** * Is the business open right now, according to the site's own timezone? * * @param array $s Settings. * @return array{open: bool, label: string, until: string, reason: string} */ public static function open_now( array $s ): array { $date = current_time( 'Y-m-d' ); $time = current_time( 'H:i' ); $day = strtolower( current_time( 'l' ) ); foreach ( (array) ( $s['special_hours'] ?? array() ) as $entry ) { $entry = (array) $entry; $from = (string) ( $entry['date'] ?? '' ); $to = (string) ( $entry['until'] ?? '' ); $to = '' !== $to ? $to : $from; if ( '' === $from || $date < $from || $date > $to ) { continue; } $label = (string) ( $entry['label'] ?? '' ); if ( ! empty( $entry['closed'] ) ) { return array( 'open' => false, 'label' => __( 'Closed', 'ai-rank-suite' ), 'until' => '', 'reason' => '' !== $label ? $label : __( 'Special closing', 'ai-rank-suite' ), ); } $open = (string) ( $entry['open'] ?? '' ); $close = (string) ( $entry['close'] ?? '' ); $is = '' !== $open && $time >= $open && ( '' === $close || $time < $close ); return array( 'open' => $is, 'label' => $is ? __( 'Open now', 'ai-rank-suite' ) : __( 'Closed', 'ai-rank-suite' ), 'until' => $is ? $close : $open, 'reason' => '' !== $label ? $label : __( 'Special hours', 'ai-rank-suite' ), ); } $slot = (array) ( ( $s['hours'] ?? array() )[ $day ] ?? array() ); if ( ! empty( $slot['closed'] ) || '' === (string) ( $slot['open'] ?? '' ) ) { return array( 'open' => false, 'label' => __( 'Closed today', 'ai-rank-suite' ), 'until' => '', 'reason' => '' ); } $break_start = (string) ( $slot['break_start'] ?? '' ); $break_end = (string) ( $slot['break_end'] ?? '' ); if ( '' !== $break_start && '' !== $break_end && $time >= $break_start && $time < $break_end ) { return array( 'open' => false, 'label' => __( 'On break', 'ai-rank-suite' ), 'until' => $break_end, 'reason' => '', ); } $open = $time >= (string) $slot['open'] && $time < (string) $slot['close']; return array( 'open' => $open, 'label' => $open ? __( 'Open now', 'ai-rank-suite' ) : __( 'Closed', 'ai-rank-suite' ), 'until' => $open ? (string) $slot['close'] : (string) $slot['open'], 'reason' => '', ); } /** * What is still missing before this profile earns a rich result. * * Grouped as required / recommended / optional because "78%" on its own * tells nobody what to type next. * * @param array $s Settings. * @return array{score: int, required: int, checks: array>} */ public static function completeness( array $s ): array { $has = static fn( string $key ) => '' !== trim( (string) ( $s[ $key ] ?? '' ) ); $any = static fn( string $key ) => ! empty( $s[ $key ] ) && is_array( $s[ $key ] ); $open_days = 0; foreach ( self::DAYS as $day ) { $slot = (array) ( ( $s['hours'] ?? array() )[ $day ] ?? array() ); if ( empty( $slot['closed'] ) && '' !== (string) ( $slot['open'] ?? '' ) ) { ++$open_days; } } $checks = array( array( 'id' => 'name', 'tier' => 'required', 'label' => __( 'Business name', 'ai-rank-suite' ), 'ok' => $has( 'name' ), 'hint' => __( 'Use the name on the shopfront, not the legal entity.', 'ai-rank-suite' ) ), array( 'id' => 'type', 'tier' => 'required', 'label' => __( 'Specific business type', 'ai-rank-suite' ), 'ok' => 'LocalBusiness' !== (string) ( $s['business_type'] ?? '' ), 'hint' => __( 'A precise subtype such as Dentist or Plumber earns richer results than the generic LocalBusiness.', 'ai-rank-suite' ) ), array( 'id' => 'street', 'tier' => 'required', 'label' => __( 'Street address', 'ai-rank-suite' ), 'ok' => $has( 'street' ), 'hint' => '' ), array( 'id' => 'city', 'tier' => 'required', 'label' => __( 'City', 'ai-rank-suite' ), 'ok' => $has( 'city' ), 'hint' => '' ), array( 'id' => 'postal', 'tier' => 'required', 'label' => __( 'Postal code', 'ai-rank-suite' ), 'ok' => $has( 'postal_code' ), 'hint' => '' ), array( 'id' => 'country', 'tier' => 'required', 'label' => __( 'Country code', 'ai-rank-suite' ), 'ok' => $has( 'country' ), 'hint' => __( 'Two letters, e.g. DE, AE, US.', 'ai-rank-suite' ) ), array( 'id' => 'phone', 'tier' => 'required', 'label' => __( 'Phone number', 'ai-rank-suite' ), 'ok' => $has( 'phone' ), 'hint' => __( 'In international format, so a click-to-call works from abroad.', 'ai-rank-suite' ) ), array( 'id' => 'hours', 'tier' => 'required', 'label' => __( 'Opening hours', 'ai-rank-suite' ), 'ok' => $open_days > 0, 'hint' => __( 'At least one open day, or assistants will say the hours are unknown.', 'ai-rank-suite' ) ), array( 'id' => 'image', 'tier' => 'recommended', 'label' => __( 'Photo of the business', 'ai-rank-suite' ), 'ok' => $has( 'image_url' ), 'hint' => __( 'Google shows an image beside a local result; without one the listing is text only.', 'ai-rank-suite' ) ), array( 'id' => 'logo', 'tier' => 'recommended', 'label' => __( 'Logo', 'ai-rank-suite' ), 'ok' => $has( 'logo_url' ), 'hint' => __( 'Square, at least 112×112, on a plain background.', 'ai-rank-suite' ) ), array( 'id' => 'geo', 'tier' => 'recommended', 'label' => __( 'Map coordinates', 'ai-rank-suite' ), 'ok' => $has( 'latitude' ) && $has( 'longitude' ), 'hint' => __( 'Coordinates settle "near me" queries when the street name is ambiguous.', 'ai-rank-suite' ) ), array( 'id' => 'description', 'tier' => 'recommended', 'label' => __( 'Description', 'ai-rank-suite' ), 'ok' => $has( 'description' ), 'hint' => __( 'Two or three sentences an assistant can quote when asked what you do.', 'ai-rank-suite' ) ), array( 'id' => 'profiles', 'tier' => 'recommended', 'label' => __( 'Linked profiles', 'ai-rank-suite' ), 'ok' => $any( 'profiles' ), 'hint' => __( 'Your Google Business Profile and social accounts, as sameAs — this is how an engine confirms you are one entity.', 'ai-rank-suite' ) ), array( 'id' => 'areas', 'tier' => 'recommended', 'label' => __( 'Service areas', 'ai-rank-suite' ), 'ok' => $any( 'areas' ), 'hint' => __( 'The towns you travel to. Required if you have no walk-in address.', 'ai-rank-suite' ) ), array( 'id' => 'email', 'tier' => 'recommended', 'label' => __( 'Email address', 'ai-rank-suite' ), 'ok' => $has( 'email' ), 'hint' => '' ), array( 'id' => 'services', 'tier' => 'optional', 'label' => __( 'Service catalogue', 'ai-rank-suite' ), 'ok' => $any( 'services' ), 'hint' => __( 'Named services with prices give an assistant something concrete to answer with.', 'ai-rank-suite' ) ), array( 'id' => 'payments', 'tier' => 'optional', 'label' => __( 'Payment methods', 'ai-rank-suite' ), 'ok' => $any( 'payments' ), 'hint' => '' ), array( 'id' => 'amenities', 'tier' => 'optional', 'label' => __( 'Amenities', 'ai-rank-suite' ), 'ok' => $any( 'amenities' ), 'hint' => __( '"Is it wheelchair accessible?" is a question with a schema answer.', 'ai-rank-suite' ) ), array( 'id' => 'special', 'tier' => 'optional', 'label' => __( 'Holiday hours', 'ai-rank-suite' ), 'ok' => $any( 'special_hours' ), 'hint' => __( 'Publish closures before the holiday, not after someone drove over.', 'ai-rank-suite' ) ), array( 'id' => 'price', 'tier' => 'optional', 'label' => __( 'Price range', 'ai-rank-suite' ), 'ok' => $has( 'price_range' ), 'hint' => '' ), array( 'id' => 'vat', 'tier' => 'optional', 'label' => __( 'VAT or tax ID', 'ai-rank-suite' ), 'ok' => $has( 'vat_id' ) || $has( 'tax_id' ), 'hint' => '' ), array( 'id' => 'booking', 'tier' => 'optional', 'label' => __( 'Booking link', 'ai-rank-suite' ), 'ok' => $has( 'booking_url' ), 'hint' => __( 'Emitted as a ReserveAction, which is what a "book an appointment" answer links to.', 'ai-rank-suite' ) ), array( 'id' => 'languages', 'tier' => 'optional', 'label' => __( 'Languages spoken', 'ai-rank-suite' ), 'ok' => $any( 'languages' ), 'hint' => '' ), ); $weights = array( 'required' => 3, 'recommended' => 2, 'optional' => 1 ); $total = 0; $earned = 0; $missing_required = 0; foreach ( $checks as $check ) { $weight = $weights[ $check['tier'] ]; $total += $weight; if ( $check['ok'] ) { $earned += $weight; } elseif ( 'required' === $check['tier'] ) { ++$missing_required; } } return array( 'score' => $total > 0 ? (int) round( $earned / $total * 100 ) : 0, 'required' => $missing_required, 'checks' => $checks, ); } }