<?php
/**
 * Stable @id URI generator for all schema.org entities.
 *
 * Every entity in the @graph must have a predictable, permanent @id so
 * cross-page references resolve correctly. All methods are static so any
 * builder or renderer can call them without instantiation.
 *
 * Convention (matches Yoast/Google expectations):
 *   Organization  → {site_url}/#organization
 *   LocalBusiness → {site_url}/#localbusiness  (or {location_url}/#localbusiness)
 *   WebSite       → {site_url}/#website
 *   WebPage       → {page_url}#webpage
 *   Article       → {page_url}#article
 *   Service       → {page_url}#service
 *   Product       → {page_url}#product
 *   Person        → {site_url}/author/{slug}/#person
 *   BreadcrumbList→ {page_url}#breadcrumb
 *   Place         → {page_url}#place
 *   FAQPage       → {page_url}#faq
 *
 * @package Schema_AI
 * @since   1.1.4
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class Schema_AI_ID_Builder {

	/**
	 * @id for the site-wide Organization entity (defined once on the homepage).
	 *
	 * @return string
	 */
	public static function organization() {
		return trailingslashit( home_url( '/' ) ) . '#organization';
	}

	/**
	 * @id for a LocalBusiness entity.
	 *
	 * Pass a location page URL for multi-location sites; omit for single-location
	 * (defaults to the homepage URL).
	 *
	 * @param string|null $location_url Absolute URL of the location page, or null.
	 * @return string
	 */
	public static function local_business( $location_url = null ) {
		$base = $location_url ? trailingslashit( $location_url ) : trailingslashit( home_url( '/' ) );
		return $base . '#localbusiness';
	}

	/**
	 * @id for the site-wide WebSite entity (defined once on the homepage).
	 *
	 * @return string
	 */
	public static function website() {
		return trailingslashit( home_url( '/' ) ) . '#website';
	}

	/**
	 * @id for a WebPage entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function webpage( $post_id ) {
		return get_permalink( $post_id ) . '#webpage';
	}

	/**
	 * @id for an Article / BlogPosting entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function article( $post_id ) {
		return get_permalink( $post_id ) . '#article';
	}

	/**
	 * @id for a Service entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function service( $post_id ) {
		return get_permalink( $post_id ) . '#service';
	}

	/**
	 * @id for a Product entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function product( $post_id ) {
		return get_permalink( $post_id ) . '#product';
	}

	/**
	 * @id for a Person (author) entity.
	 *
	 * Uses the author's nicename (URL slug) for stability — display names can change.
	 *
	 * @param int $user_id WordPress user ID.
	 * @return string
	 */
	public static function person( $user_id ) {
		$user = get_userdata( $user_id );

		if ( ! $user ) {
			return trailingslashit( home_url( '/' ) ) . 'author/unknown/#person';
		}

		return trailingslashit( home_url( '/' ) ) . 'author/' . $user->user_nicename . '/#person';
	}

	/**
	 * @id for a BreadcrumbList entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function breadcrumb( $post_id ) {
		return get_permalink( $post_id ) . '#breadcrumb';
	}

	/**
	 * @id for a Place entity on a location page.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function place( $post_id ) {
		return get_permalink( $post_id ) . '#place';
	}

	/**
	 * @id for a FAQPage entity, so another entity on the same page can
	 * reference it via subjectOf.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function faq_page( $post_id ) {
		return get_permalink( $post_id ) . '#faq';
	}

	/**
	 * @id for a PodcastEpisode entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function podcast_episode( $post_id ) {
		return get_permalink( $post_id ) . '#podcast-episode';
	}

	/**
	 * @id for a SoftwareApplication entity.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function software_app( $post_id ) {
		return get_permalink( $post_id ) . '#software-application';
	}

	/**
	 * @id for a CreativeWork entity (portfolio item).
	 *
	 * @param int $post_id WordPress post ID.
	 * @return string
	 */
	public static function creative_work( $post_id ) {
		return get_permalink( $post_id ) . '#creative-work';
	}

	/**
	 * @id for the primary site-wide entity.
	 *
	 * Returns the LocalBusiness @id for local business sites, or the Organization
	 * @id for all other site types. Use this anywhere you need to reference the
	 * homepage entity without knowing the site type.
	 *
	 * @return string
	 */
	public static function primary_entity() {
		if ( class_exists( 'Schema_AI_Site_Type' ) && Schema_AI_Site_Type::is_local_business() ) {
			return self::local_business();
		}
		return self::organization();
	}

	/**
	 * @id for a taxonomy term archive's CollectionPage entity.
	 *
	 * @param string $taxonomy Taxonomy slug (e.g. 'category', 'post_tag').
	 * @param int    $term_id  Term ID.
	 * @return string
	 */
	public static function archive( $taxonomy, $term_id ) {
		$link = get_term_link( $term_id, $taxonomy );
		$base = is_wp_error( $link ) ? trailingslashit( home_url( '/' ) ) : $link;
		return $base . '#collectionpage';
	}

	/**
	 * Build a minimal cross-reference stub: {"@id": "..."}.
	 *
	 * Use this when one entity needs to reference another without redefining it.
	 *
	 * @param string $id The @id value.
	 * @return array
	 */
	public static function ref( $id ) {
		return array( '@id' => $id );
	}
}