Site * Name"), which is what Yoast emits by default too. $title_template * empty (the R1 behavior, and every existing caller) leaves this * method's output byte-for-byte unchanged. * * @param string $seo_title Explicit _abds_seo_title (may be ''). * @param string $post_title The post/page title. * @param string $site_name Blog name. * @param string $separator Title separator (e.g. "-"). * @param string $title_template Optional {{title}}/{{sep}}/{{site_name}} template (may be ''). * @return string Resolved title, never empty when a post title exists. */ public static function resolve_title( string $seo_title, string $post_title, string $site_name, string $separator = '-', string $title_template = '' ): string { $seo_title = trim( $seo_title ); if ( '' !== $seo_title ) { return $seo_title; } if ( '' !== trim( $title_template ) ) { return trim( ABDS_SEO_Template_Resolver::resolve( $title_template, array( 'title' => trim( $post_title ), 'sep' => trim( $separator ), 'site_name' => trim( $site_name ), ) ) ); } $parts = array_filter( array( trim( $post_title ), trim( $site_name ) ), fn( $part ) => '' !== $part ); return implode( ' ' . trim( $separator ) . ' ', $parts ); } /** * Resolves the meta description: the explicit one when set, otherwise * (R2, F2.2) a configured Global description template when one is set, * otherwise a trimmed excerpt (or, failing that, the plain content) * capped at DESCRIPTION_FALLBACK_MAX characters on a word boundary. * $description_template empty leaves this method's output unchanged * from R1. * * @param string $seo_description Explicit _abds_seo_description (may be ''). * @param string $excerpt Post excerpt (may be ''). * @param string $plain_content Tag-stripped post content (may be ''). * @param string $description_template Optional {{title}}/{{sep}}/{{site_name}} template (may be ''). * @param string $post_title The post/page title, only used when $description_template is set. * @param string $site_name Blog name, only used when $description_template is set. * @param string $separator Title separator, only used when $description_template is set. * @return string Resolved description (may be '' when nothing to derive from). */ public static function resolve_description( string $seo_description, string $excerpt, string $plain_content, string $description_template = '', string $post_title = '', string $site_name = '', string $separator = '-' ): string { $seo_description = trim( $seo_description ); if ( '' !== $seo_description ) { return $seo_description; } if ( '' !== trim( $description_template ) ) { return trim( ABDS_SEO_Template_Resolver::resolve( $description_template, array( 'title' => trim( $post_title ), 'sep' => trim( $separator ), 'site_name' => trim( $site_name ), ) ) ); } $source = '' !== trim( $excerpt ) ? $excerpt : $plain_content; $source = trim( (string) preg_replace( '/\s+/u', ' ', $source ) ); if ( '' === $source ) { return ''; } return self::truncate_on_word_boundary( $source, self::DESCRIPTION_FALLBACK_MAX ); } /** * Builds the Open Graph tag map (property => content) from already * resolved values. Only non-empty tags are included, so an imageless * post simply omits og:image rather than emitting an empty one. * * @param array $context Resolved page values: title, description, url, * site_name, type, image (each '' if unset). * @return array Property => content, empties dropped. */ public static function build_open_graph( array $context ): array { $tags = array( 'og:title' => (string) ( $context['title'] ?? '' ), 'og:description' => (string) ( $context['description'] ?? '' ), 'og:url' => (string) ( $context['url'] ?? '' ), 'og:site_name' => (string) ( $context['site_name'] ?? '' ), 'og:type' => (string) ( $context['type'] ?? 'website' ), 'og:image' => (string) ( $context['image'] ?? '' ), ); return array_filter( $tags, fn( $value ) => '' !== $value ); } /** * Builds the Twitter Card tag map (name => content). Uses * summary_large_image when an image exists, plain summary otherwise. * * @param array $context Same shape as build_open_graph()'s $context. * @return array name => content, empties dropped. */ public static function build_twitter_card( array $context ): array { $image = (string) ( $context['image'] ?? '' ); $tags = array( 'twitter:card' => '' !== $image ? 'summary_large_image' : 'summary', 'twitter:title' => (string) ( $context['title'] ?? '' ), 'twitter:description' => (string) ( $context['description'] ?? '' ), 'twitter:image' => $image, ); return array_filter( $tags, fn( $value ) => '' !== $value ); } /** * The LocalBusiness node a request's should carry, or null. * Printed only on the front page (the first page of it: /page/2/ of a * posts-index home is not the business's home) and only while the site's * licence covers Local SEO -- a lapsed or missing licence prints nothing, * while the stored profile itself is left untouched, so the markup * returns the moment the licence does. * * @param array $nap Reference profile (see build_local_business_schema()). * @param string $url Site URL for the node. * @param bool $licensed Whether the licence covers Local SEO. * @param bool $is_front_page is_front_page() for this request. * @param bool $is_paged is_paged() for this request. * @return array|null */ public static function local_business_head_node( array $nap, string $url, bool $licensed, bool $is_front_page, bool $is_paged ): ?array { if ( ! $licensed || ! $is_front_page || $is_paged ) { return null; } return self::build_local_business_schema( $nap, $url ); } /** * Builds a LocalBusiness JSON-LD node from a reference-profile array * (the one ABDS_SEO_Local_SEO_Scanner stores in the Pro add-on). * Returns null when the profile has no name — a LocalBusiness node * without a name is invalid (see ABDS_SEO_LocalBusiness_Validator), so * there's nothing to emit. * * Beyond the original name / address / phone, every key below is * optional and emitted only when present AND well-formed — a value that * would make the node invalid (a latitude of 200, a day with closing * before opening, a non-URL in sameAs) is silently dropped rather than * shipped to search engines: * - locality, region, postal_code, country: parts of the PostalAddress * - business_type: a schema.org subtype from * ABDS_SEO_LocalBusiness_Validator::LOCAL_BUSINESS_TYPES (else the * generic LocalBusiness) * - price_range: free text such as "$$" * - latitude / longitude: both, in range, or neither * - hours: day key (mon..sun) => { open:bool, opens:"HH:MM", closes:"HH:MM" } * - area_served, same_as: string lists (same_as: http(s) URLs only) * - logo_url, image_url: absolute http(s) URLs * * @param array $nap Reference profile (see above); name/address/phone as before. * @param string $url Site URL for the node. * @return array|null LocalBusiness node, or null when not emittable. */ public static function build_local_business_schema( array $nap, string $url = '' ): ?array { $name = trim( (string) ( $nap['name'] ?? '' ) ); if ( '' === $name ) { return null; } $type = trim( (string) ( $nap['business_type'] ?? '' ) ); if ( ! in_array( $type, ABDS_SEO_LocalBusiness_Validator::LOCAL_BUSINESS_TYPES, true ) ) { $type = 'LocalBusiness'; } $node = array( '@context' => 'https://schema.org', '@type' => $type, 'name' => $name, ); $phone = trim( (string) ( $nap['phone'] ?? '' ) ); if ( '' !== $phone ) { $node['telephone'] = $phone; } $address = array(); foreach ( array( 'address' => 'streetAddress', 'locality' => 'addressLocality', 'region' => 'addressRegion', 'postal_code' => 'postalCode', 'country' => 'addressCountry', ) as $key => $property ) { $value = trim( (string) ( $nap[ $key ] ?? '' ) ); if ( '' !== $value ) { $address[ $property ] = $value; } } if ( array() !== $address ) { $node['address'] = array( '@type' => 'PostalAddress' ) + $address; } if ( '' !== trim( $url ) ) { $node['url'] = trim( $url ); } $price_range = trim( (string) ( $nap['price_range'] ?? '' ) ); if ( '' !== $price_range ) { $node['priceRange'] = $price_range; } $geo = self::geo_node( $nap['latitude'] ?? null, $nap['longitude'] ?? null ); if ( null !== $geo ) { $node['geo'] = $geo; } $hours = self::opening_hours_nodes( is_array( $nap['hours'] ?? null ) ? $nap['hours'] : array() ); if ( array() !== $hours ) { $node['openingHoursSpecification'] = $hours; } $areas = array_values( array_filter( array_map( static fn( $a ): string => trim( (string) $a ), (array) ( $nap['area_served'] ?? array() ) ), static fn( string $a ): bool => '' !== $a ) ); if ( array() !== $areas ) { $node['areaServed'] = $areas; } $same_as = array_values( array_filter( array_map( static fn( $u ): string => trim( (string) $u ), (array) ( $nap['same_as'] ?? array() ) ), array( __CLASS__, 'is_http_url' ) ) ); if ( array() !== $same_as ) { $node['sameAs'] = $same_as; } foreach ( array( 'logo_url' => 'logo', 'image_url' => 'image', ) as $key => $property ) { $asset = trim( (string) ( $nap[ $key ] ?? '' ) ); if ( self::is_http_url( $asset ) ) { $node[ $property ] = $asset; } } return $node; } /** * GeoCoordinates node, or null unless BOTH values are numeric and in * range (half a coordinate pair, or 200 degrees of latitude, is worse * than none). * * @param mixed $latitude Latitude. * @param mixed $longitude Longitude. * @return array|null */ public static function geo_node( $latitude, $longitude ): ?array { if ( ! is_numeric( $latitude ) || ! is_numeric( $longitude ) ) { return null; } $lat = (float) $latitude; $lng = (float) $longitude; if ( $lat < -90 || $lat > 90 || $lng < -180 || $lng > 180 ) { return null; } return array( '@type' => 'GeoCoordinates', 'latitude' => $lat, 'longitude' => $lng, ); } /** * OpeningHoursSpecification nodes from a per-day map. Open days that * share the same hours are grouped into one node (Monday-Friday * 09:00-18:00 is one specification, not five); a day is skipped when it * is closed, or its times are not HH:MM, or it closes before it opens. * Day order follows the week, so output is stable. * * @param array $hours Day key (mon..sun) => hours. * @return array */ public static function opening_hours_nodes( array $hours ): array { $names = array( 'mon' => 'Monday', 'tue' => 'Tuesday', 'wed' => 'Wednesday', 'thu' => 'Thursday', 'fri' => 'Friday', 'sat' => 'Saturday', 'sun' => 'Sunday', ); $groups = array(); foreach ( $names as $key => $day_name ) { $day = $hours[ $key ] ?? null; if ( ! is_array( $day ) || empty( $day['open'] ) ) { continue; } $opens = (string) ( $day['opens'] ?? '' ); $closes = (string) ( $day['closes'] ?? '' ); if ( ! preg_match( '/^([01]\d|2[0-3]):[0-5]\d$/', $opens ) || ! preg_match( '/^([01]\d|2[0-3]):[0-5]\d$/', $closes ) || $closes <= $opens ) { continue; } $groups[ $opens . '-' . $closes ]['days'][] = $day_name; $groups[ $opens . '-' . $closes ]['opens'] = $opens; $groups[ $opens . '-' . $closes ]['closes'] = $closes; } $nodes = array(); foreach ( $groups as $group ) { $nodes[] = array( '@type' => 'OpeningHoursSpecification', 'dayOfWeek' => $group['days'], 'opens' => $group['opens'], 'closes' => $group['closes'], ); } return $nodes; } /** * Whether a string is an absolute http(s) URL. * * @param string $value Candidate. * @return bool */ public static function is_http_url( string $value ): bool { return 1 === preg_match( '#^https?://[^\s/$.?\#].[^\s]*$#i', $value ); } /** * Truncates text to a character budget on a word boundary (when one * exists in the final stretch), with a trailing ellipsis. Multibyte-safe. * * @param string $text Text to truncate. * @param int $max Maximum characters including the ellipsis. * @return string */ protected static function truncate_on_word_boundary( string $text, int $max ): string { if ( mb_strlen( $text ) <= $max ) { return $text; } $cut = mb_substr( $text, 0, $max - 1 ); $space = mb_strrpos( $cut, ' ' ); if ( false !== $space && $space > (int) ( $max * 0.6 ) ) { $cut = mb_substr( $cut, 0, $space ); } return rtrim( $cut, ' ,.;:—-' ) . '…'; } }