<?php
/**
 * File Path: includes/data/class-mbs-quote-library.php
 *
 * My Book Showroom — Daily Quote Library
 *
 * Static data class. Holds all 365 inspirational quotes and provides
 * day-of-year rotation. No database queries, no transients.
 *
 * @package MyBookShowroom
 * @since   1.1.0
 */

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

class MBS_Quote_Library { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Return all quotes as an indexed array of associative arrays.
	 *
	 * Each item: array{ text: string, author: string }
	 * Author is an empty string for anonymous quotes.
	 *
	 * @return array<int, array{text: string, author: string}>
	 */
	public static function get_all(): array {
		return MBS_Quote_Data::get();
	}

	/**
	 * Return the quote for today based on day-of-year rotation.
	 *
	 * Uses date('z') (0-indexed day of year, 0-365) modulo quote count,
	 * making the rotation naturally leap-year safe.
	 *
	 * @return array{text: string, author: string}
	 */
	public static function get_today(): array {
		$all   = self::get_all();
		$index = (int) gmdate( 'z' ) % count( $all );
		return $all[ $index ];
	}

	/**
	 * Return the quote at a specific 0-based index.
	 *
	 * Wraps with modulo so out-of-range values are safe.
	 *
	 * @param int $n Zero-based index.
	 * @return array{text: string, author: string}
	 */
	public static function get_by_index( int $n ): array {
		$all = self::get_all();
		$n   = abs( $n ) % count( $all );
		return $all[ $n ];
	}
}
