<?php
/**
 * Local filesystem operations through the WordPress filesystem API.
 *
 * Cache files must be on the local filesystem used by PHP. The direct transport
 * avoids prompting visitors or cron workers for remote filesystem credentials.
 * Streaming, flock and atomic rename operations are kept at their call sites.
 *
 * @package NBHPerformance
 */

namespace NBH\Performance\Modules\Core;

/**
 * Local filesystem operations through the WordPress filesystem API.
 */
final class Filesystem {
	/** @var \WP_Filesystem_Direct|null */
	private static $driver;

	/** @return \WP_Filesystem_Direct */
	private static function driver() {
		if ( null === self::$driver ) {
			if ( ! class_exists( 'WP_Filesystem_Direct', false ) ) {
				require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-base.php';
				require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-direct.php';
			}
			self::$driver = new \WP_Filesystem_Direct( null );
		}
		return self::$driver;
	}

	/** Read a local file through WordPress. @return string|false */
	public static function get_contents( $path ) {
		return self::driver()->get_contents( $path );
	}

	/** Write a complete buffer and verify its length through WordPress. @return bool */
	public static function put_contents( $path, $contents, $mode = 0644 ) {
		return self::driver()->put_contents( $path, (string) $contents, $mode );
	}

	/** Copy only where the caller has already checked destination ownership. @return bool */
	public static function copy( $source, $destination ) {
		return self::driver()->copy( $source, $destination, true, 0644 );
	}

	/**
	 * Atomically replace a verified local page-cache drop-in.
	 *
	 * The temporary file and target are within the same wp-content directory.
	 * WordPress_Filesystem_Direct::move() deletes the old target before calling
	 * rename(), creating a time gap; this operation must be atomic instead.
	 * All ownership and symlink protections are enforced by DropInInstaller.
	 *
	 * @param string $source      Verified temporary file.
	 * @param string $destination Existing owned drop-in or empty destination.
	 * @return bool Whether the atomic filesystem replacement succeeded.
	 */
	public static function atomic_replace( $source, $destination ) {
		if (
			! is_string( $source ) ||
			! is_string( $destination ) ||
			! is_file( $source ) ||
			! is_readable( $source ) ||
			is_link( $source ) ||
			basename( $destination ) !== 'advanced-cache.php' ||
			dirname( $source ) !== dirname( $destination ) ||
			is_link( $destination )
		) {
			return false;
		}

		// Check ownership again immediately before replacing a drop-in.
		if ( file_exists( $destination ) ) {
			if ( ! is_file( $destination ) || ! is_readable( $destination ) ) {
				return false;
			}

			$existing = self::get_contents( $destination );
			if ( ! is_string( $existing ) || false === strpos( substr( $existing, 0, 1024 ), 'NBH_PERFORMANCE_DROPIN' ) ) {
				return false;
			}
		}

		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged, WordPress.WP.AlternativeFunctions.rename_rename -- Same-directory atomic replacement is required, and permission failures are handled by the caller.
		$replaced = @rename( $source, $destination );
		if ( $replaced && function_exists( 'opcache_invalidate' ) ) {
			opcache_invalidate( $destination, true );
		}

		return $replaced;
	}

	/** @return bool */
	public static function is_writable( $path ) {
		return self::driver()->is_writable( $path );
	}

	/** @return bool */
	public static function chmod( $path, $mode ) {
		return self::driver()->chmod( $path, $mode );
	}

	/** Delete one file or symlink, without following directories. @return bool */
	public static function unlink( $path ) {
		return self::driver()->delete( $path, false, 'f' );
	}

	/** Remove an empty directory only; recursive deletion is deliberately absent. @return bool */
	public static function rmdir( $path ) {
		return self::driver()->rmdir( $path, false );
	}
}