<?php

declare( strict_types=1 );

namespace AcezSeo\Support;

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

/**
 * Shared "one-click takeover" mechanics for a physical file in the site root
 * (robots.txt, llms.txt) that shadows the plugin's own generator — the web
 * server serves the physical file directly, so no plugin filter can touch it.
 * The takeover reads the content, then renames the file to a reversible
 * backup so the plugin's own output takes over. Content is read BEFORE the
 * rename so nothing is lost if the rename then fails.
 *
 * Extracted from the original robots.txt-only implementation (M19) when
 * llms.txt (M57/M58) needed the identical mechanic — a straight DRY move,
 * behavior unchanged.
 */
final class PhysicalFileTakeover
{
	/**
	 * WP_Filesystem accessor — direct PHP filesystem calls (is_writable/
	 * rename) are flagged by Plugin Check because some hosts restrict them;
	 * WP_Filesystem() falls back to the site's configured method (direct/
	 * FTP) instead. Returns null when even that isn't available, which
	 * callers treat the same as "not writable".
	 */
	public static function wp_filesystem(): ?\WP_Filesystem_Base
	{
		global $wp_filesystem;

		if ( ! function_exists( 'WP_Filesystem' ) )
		{
			require_once ABSPATH . 'wp-admin/includes/file.php';
		}

		if ( ! $wp_filesystem instanceof \WP_Filesystem_Base && ! WP_Filesystem() )
		{
			return null;
		}

		return $wp_filesystem;
	}

	public static function can_take_over( string $path ): bool
	{
		$fs = self::wp_filesystem();

		return null !== $fs && file_exists( $path ) && is_readable( $path ) && $fs->is_writable( $path ) && $fs->is_writable( dirname( $path ) );
	}

	/**
	 * Reads the file's trimmed content. Callers MUST check `can_take_over()`
	 * first — kept as a separate step (rather than folded into a combined
	 * take-over method) so a caller can apply the migrated content to its
	 * own settings BEFORE attempting `rename_to_backup()`, matching the
	 * original robots.txt behavior: nothing migrated is lost even on the
	 * rare case the rename itself then fails.
	 */
	public static function read_content( string $path ): string
	{
		return trim( (string) file_get_contents( $path ) );
	}

	/**
	 * Renames the file to a backup (`{path}.acez-backup`, or a timestamped
	 * variant if that name is already taken). Returns whether the rename
	 * succeeded.
	 */
	public static function rename_to_backup( string $path ): bool
	{
		$fs = self::wp_filesystem();

		if ( null === $fs )
		{
			return false;
		}

		$backup = $path . '.acez-backup';

		if ( file_exists( $backup ) )
		{
			$backup = $path . '.acez-backup-' . gmdate( 'Ymd-His' );
		}

		return $fs->move( $path, $backup );
	}
}