block in an HTML * document. Malformed blocks are skipped, not fatal. * * @param string $html Rendered page HTML. * @return array Decoded JSON-LD nodes. */ public static function extract_jsonld_blocks( string $html ): array { if ( ! preg_match_all( '#]*type\s*=\s*["\']application/ld\+json["\'][^>]*>(.*?)#is', $html, $matches ) ) { return array(); } $blocks = array(); foreach ( $matches[1] as $raw ) { $decoded = json_decode( trim( $raw ), true ); if ( is_array( $decoded ) ) { $blocks[] = $decoded; } } return $blocks; } /** * Finds the first LocalBusiness(-subtype) node among decoded JSON-LD * blocks, looking through top-level nodes, plain arrays of nodes, * and "@graph" containers. * * @param array $blocks Decoded blocks from extract_jsonld_blocks(). * @return array|null The LocalBusiness node, or null when none exists. */ public static function find_local_business( array $blocks ): ?array { foreach ( $blocks as $block ) { foreach ( self::candidate_nodes( $block ) as $node ) { if ( self::is_local_business( $node ) ) { return $node; } } } return null; } /** * Validates a LocalBusiness node against the required-field set: * name, address (PostalAddress with streetAddress + addressLocality), * and telephone (required for NAP purposes). Missing postalCode and * url are warnings — recommended, not required. * * @param array $node LocalBusiness node from find_local_business(). * @return array{valid:bool, errors:string[], warnings:string[]} */ public static function validate( array $node ): array { $errors = array(); $warnings = array(); if ( '' === trim( (string) ( $node['name'] ?? '' ) ) ) { $errors[] = 'missing_name'; } if ( '' === trim( (string) ( $node['telephone'] ?? '' ) ) ) { $errors[] = 'missing_telephone'; } $address = $node['address'] ?? null; if ( ! is_array( $address ) ) { // A bare-string address technically parses but loses all // structure Google's local results rely on. $errors[] = is_string( $address ) && '' !== trim( $address ) ? 'address_not_structured' : 'missing_address'; } else { if ( '' === trim( (string) ( $address['streetAddress'] ?? '' ) ) ) { $errors[] = 'missing_street_address'; } if ( '' === trim( (string) ( $address['addressLocality'] ?? '' ) ) ) { $errors[] = 'missing_address_locality'; } if ( '' === trim( (string) ( $address['postalCode'] ?? '' ) ) ) { $warnings[] = 'missing_postal_code'; } } if ( '' === trim( (string) ( $node['url'] ?? '' ) ) ) { $warnings[] = 'missing_url'; } return array( 'valid' => array() === $errors, 'errors' => $errors, 'warnings' => $warnings, ); } /** * Expands one decoded JSON-LD block into candidate nodes: the block * itself, its @graph members, or — when the block is a plain list — * each list item. * * @param array $block Decoded JSON-LD block. * @return array Candidate nodes. */ protected static function candidate_nodes( array $block ): array { if ( isset( $block['@graph'] ) && is_array( $block['@graph'] ) ) { return array_filter( $block['@graph'], 'is_array' ); } // A JSON-LD file may be a plain array of nodes (list keys 0..n). if ( array_keys( $block ) === range( 0, count( $block ) - 1 ) ) { return array_filter( $block, 'is_array' ); } return array( $block ); } /** * Whether a node's "@type" is LocalBusiness or an accepted subtype. * The "@type" value may be a string or an array of strings. * * @param array $node Candidate node. * @return bool */ protected static function is_local_business( array $node ): bool { $types = (array) ( $node['@type'] ?? array() ); return array() !== array_intersect( array_map( 'strval', $types ), self::LOCAL_BUSINESS_TYPES ); } }