<?php
/**
 * Plugin settings accessor.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Settings;

/**
 * Plugin settings accessor.
 *
 * Reads the single `postlinkly_settings` option once per request,
 * hydrates the three settings DTOs, and caches them for the lifetime
 * of the request. Callers never touch `get_option` directly.
 *
 * All settings live in one autoloaded option row. Each section is
 * hydrated into a typed DTO on first access and cached for the
 * remainder of the request.
 *
 * The row can also hold sections this class does not know, such as the
 * Pro add-on's `auto_link` section. `save_section()` rewrites only the
 * section it is given, so those survive every save made here.
 *
 * @since 1.0.0
 * @since 1.18.0 The auto-link section moved to the Pro add-on.
 */
final class Settings {

	/**
	 * The WordPress option key for all plugin settings.
	 */
	public const OPTION_KEY = 'postlinkly_settings';

	/**
	 * Cached raw settings array.
	 *
	 * @var array<string, mixed>|null
	 */
	private ?array $raw = null;

	/**
	 * Cached DTO instances.
	 *
	 * @var GeneralSettings|null
	 */
	private ?GeneralSettings $general = null;

	/**
	 * @var SuggestionSettings|null
	 */
	private ?SuggestionSettings $suggestion = null;

	/**
	 * @var AdvancedSettings|null
	 */
	private ?AdvancedSettings $advanced = null;

	/**
	 * Returns the General settings DTO.
	 *
	 * @since 1.0.0
	 *
	 * @return GeneralSettings
	 */
	public function general(): GeneralSettings {
		if ( null === $this->general ) {
			$this->general = GeneralSettings::from_array( $this->section( 'general' ) );
		}
		return $this->general;
	}

	/**
	 * Returns the Suggestion settings DTO.
	 *
	 * @since 1.0.0
	 *
	 * @return SuggestionSettings
	 */
	public function suggestion(): SuggestionSettings {
		if ( null === $this->suggestion ) {
			$this->suggestion = SuggestionSettings::from_array( $this->section( 'suggestion' ) );
		}
		return $this->suggestion;
	}

	/**
	 * Returns the Advanced settings DTO.
	 *
	 * @since 1.0.0
	 *
	 * @return AdvancedSettings
	 */
	public function advanced(): AdvancedSettings {
		if ( null === $this->advanced ) {
			$this->advanced = AdvancedSettings::from_array( $this->section( 'advanced' ) );
		}
		return $this->advanced;
	}

	/**
	 * Saves a settings section back to the database.
	 *
	 * Merges the new section data into the existing option and writes it
	 * back. Clears the in-memory cache so the next read reflects the
	 * saved values.
	 *
	 * @since 1.0.0
	 *
	 * @param string               $section Section key (`general`, `suggestion`, `advanced`, or
	 *                                      an add-on's own section).
	 * @param array<string, mixed> $data    New values for the section.
	 *
	 * @return bool True when the option was updated.
	 */
	public function save_section( string $section, array $data ): bool {
		$raw             = $this->load();
		$raw[ $section ] = $data;

		$result = update_option( self::OPTION_KEY, $raw, true );

		// Clear cache so the next read picks up the new values.
		$this->raw        = null;
		$this->general    = null;
		$this->suggestion = null;
		$this->advanced   = null;

		return $result;
	}

	/**
	 * Returns the raw settings array for a section.
	 *
	 * @since 1.0.0
	 *
	 * @param string $section Section key.
	 *
	 * @return array<string, mixed>
	 */
	private function section( string $section ): array {
		$raw = $this->load();
		return isset( $raw[ $section ] ) && is_array( $raw[ $section ] )
			? $raw[ $section ]
			: array();
	}

	/**
	 * Loads the raw option, caching the result.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, mixed>
	 */
	private function load(): array {
		if ( null !== $this->raw ) {
			return $this->raw;
		}

		$value     = get_option( self::OPTION_KEY, array() );
		$this->raw = is_array( $value ) ? $value : array();
		return $this->raw;
	}
}