<?php
/**
 * Orphaned upload cleanup.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Uploads;

use FormPilot\Contracts\Hookable;
use FormPilot\Database\Repositories\SubmissionRepository;
use FormPilot\Settings\Settings;
use FilesystemIterator;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
use SplFileInfo;

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

/**
 * Removes uploads that no submission points at any more.
 *
 * Files are orphaned when a submission is deleted while the plugin cannot reach
 * its files, when a field is removed from a form, or when a submission fails
 * after its upload was already written. The cleaner is the backstop for all of
 * those.
 *
 * @since 1.0.0
 */
final class OrphanCleaner implements Hookable {

	/**
	 * Cron hook running the cleanup.
	 */
	public const HOOK = 'formpilot_cleanup_uploads';

	/**
	 * Files deleted per run.
	 */
	private const BATCH = 500;

	/**
	 * Files the cleaner never touches.
	 *
	 * Public because they are not only the cleaner's concern: these are the guard
	 * files `DirectoryGuard` writes into the upload directory, so their paths are
	 * entirely predictable, and anything deciding whether a stored path describes
	 * a real upload has to exclude them.
	 */
	public const PROTECTED_FILES = array( 'index.php', '.htaccess', 'web.config' );

	/**
	 * Constructor.
	 *
	 * @param SubmissionRepository $submissions Submission repository.
	 * @param UploadManager        $uploads     Upload manager.
	 */
	public function __construct( private SubmissionRepository $submissions, private UploadManager $uploads ) {}

	/**
	 * Registers the module hooks.
	 */
	public function register_hooks(): void {
		add_action( 'init', array( $this, 'schedule' ) );
		add_action( self::HOOK, array( $this, 'run' ) );
	}

	/**
	 * Keeps the daily cleanup scheduled while the setting is on.
	 */
	public function schedule(): void {
		$enabled   = Settings::flag( 'upload_cleanup' );
		$scheduled = wp_next_scheduled( self::HOOK );

		if ( $enabled && false === $scheduled ) {
			wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', self::HOOK );

			return;
		}

		if ( ! $enabled && false !== $scheduled ) {
			wp_clear_scheduled_hook( self::HOOK );
		}
	}

	/**
	 * Deletes the orphaned files found in the upload directory.
	 */
	public function run(): int {
		$base = UploadManager::base_dir();

		if ( '' === $base || ! is_dir( $base ) ) {
			return 0;
		}

		$referenced = $this->referenced_paths();

		/*
		 * An unreadable reference set is not an empty one. `referenced_files()`
		 * answers null for a failed query — a lost connection, a renamed table, a
		 * half-applied migration — and continuing from that would read as "nothing
		 * on this site is in use" and delete up to BATCH live attachments per run.
		 */
		if ( null === $referenced ) {
			return 0;
		}

		$cutoff  = time() - $this->retention();
		$deleted = 0;

		foreach ( $this->files( $base ) as $file ) {
			if ( $deleted >= self::BATCH ) {
				break;
			}

			// Young files may belong to a submission that is still being written.
			if ( $file->getMTime() > $cutoff ) {
				continue;
			}

			if ( ! $this->is_orphan( $file, $referenced ) ) {
				continue;
			}

			$path = wp_normalize_path( $file->getPathname() );

			/*
			 * Containment rests on the iterator's root, which is one bug away from
			 * being wrong. Asking the manager whether it owns the resolved path
			 * makes that explicit and survives a symlink inside the tree.
			 */
			if ( ! UploadManager::owns( $path ) ) {
				continue;
			}

			wp_delete_file( $path );

			++$deleted;
		}

		/**
		 * Fires after a cleanup run.
		 *
		 * @since 1.0.0
		 *
		 * @param int $deleted Number of deleted files.
		 */
		do_action( 'formpilot_uploads_cleaned', $deleted );

		return $deleted;
	}

	/**
	 * Counts the orphaned files without deleting anything.
	 */
	public function count_orphans(): int {
		$base = UploadManager::base_dir();

		if ( '' === $base || ! is_dir( $base ) ) {
			return 0;
		}

		$referenced = $this->referenced_paths();

		if ( null === $referenced ) {
			return 0;
		}

		$cutoff  = time() - $this->retention();
		$orphans = 0;

		foreach ( $this->files( $base ) as $file ) {
			/*
			 * Capped like the deletion run. This is reached from an admin page, and
			 * an uncapped walk of a directory holding a million files is a request
			 * that never returns.
			 */
			if ( $orphans >= self::BATCH ) {
				break;
			}

			if ( $file->getMTime() > $cutoff || ! $this->is_orphan( $file, $referenced ) ) {
				continue;
			}

			++$orphans;
		}

		return $orphans;
	}

	/**
	 * Determines whether a file on disk is no longer referenced.
	 *
	 * The name test is the safety net for a moved site. Stored paths are absolute,
	 * so changing `basedir` — a migration, a new `UPLOADS` constant, a different
	 * drive letter's casing — makes every live file's path stop matching while the
	 * files themselves are untouched. Storage names are 24 random characters, so a
	 * basename match is strong evidence the file is the one being referenced, and
	 * treating it as in use costs a stale file where the alternative costs the
	 * whole directory.
	 *
	 * @param SplFileInfo                                                                          $file       File being judged.
	 * @param array{paths: array<string, true>, names: array<string, true>, stems: array<string, true>} $referenced Reference maps.
	 */
	private function is_orphan( SplFileInfo $file, array $referenced ): bool {
		if ( in_array( $file->getFilename(), self::PROTECTED_FILES, true ) ) {
			return false;
		}

		if ( isset( $referenced['paths'][ wp_normalize_path( $file->getPathname() ) ] ) ) {
			return false;
		}

		/*
		 * The sizes WordPress generates for a media library upload -
		 * `formpilot-…-150x150.jpg`, `formpilot-…-scaled.jpg`, an edited `formpilot-…-e1712345678.jpg` -
		 * are recorded nowhere this can read, and were deleted as orphans once the
		 * retention period passed, breaking every thumbnail of the attachment.
		 */
		$stem = (string) preg_replace( '/(?:-(?:\d+x\d+|scaled|rotated|e\d{10,}))+$/', '', pathinfo( $file->getFilename(), PATHINFO_FILENAME ) );

		if ( isset( $referenced['stems'][ $stem ] ) ) {
			return false;
		}

		return ! isset( $referenced['names'][ $file->getFilename() ] );
	}

	/**
	 * Walks every file in the upload directory.
	 *
	 * @param string $base Absolute directory path.
	 *
	 * @return iterable<SplFileInfo> The files.
	 */
	private function files( string $base ): iterable {
		$iterator = new RecursiveIteratorIterator(
			new RecursiveDirectoryIterator( $base, FilesystemIterator::SKIP_DOTS )
		);

		foreach ( $iterator as $file ) {
			if ( $file instanceof SplFileInfo && $file->isFile() ) {
				yield $file;
			}
		}
	}

	/**
	 * Returns every path that is still referenced, as a lookup map.
	 *
	 * Both sources matter: a file is in use when a submission stores it, and
	 * also when it lives in the media library, where deleting it from disk would
	 * leave a broken attachment behind.
	 *
	 * @return array{paths: array<string, true>, names: array<string, true>, stems: array<string, true>}|null
	 *         Reference maps, or null when the set could not be established.
	 */
	private function referenced_paths(): ?array {
		$stored = $this->submissions->referenced_files();

		if ( null === $stored ) {
			return null;
		}

		$attached = $this->attached_files();

		if ( null === $attached ) {
			return null;
		}

		$paths = array();
		$names = array();
		$stems = array();

		foreach ( array_merge( $stored, $attached ) as $path ) {
			$normalised = wp_normalize_path( (string) $path );

			$paths[ $normalised ] = true;
			$names[ basename( $normalised ) ] = true;
		}

		foreach ( $attached as $path ) {
			$stems[ pathinfo( (string) $path, PATHINFO_FILENAME ) ] = true;
		}

		return array(
			'paths' => $paths,
			'names' => $names,
			'stems' => $stems,
		);
	}

	/**
	 * Returns the plugin uploads that belong to a media library entry.
	 *
	 * @return array<int, string>|null Absolute paths, or null when the query failed.
	 */
	private function attached_files(): ?array {
		global $wpdb;

		$uploads = wp_get_upload_dir();
		$basedir = trailingslashit( (string) ( $uploads['basedir'] ?? '' ) );

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Maintenance scan over core meta, not cacheable.
		$rows = $wpdb->get_col(
			$wpdb->prepare(
				"SELECT meta_value FROM {$wpdb->postmeta} WHERE meta_key = '_wp_attached_file' AND meta_value LIKE %s",
				$wpdb->esc_like( UploadManager::SUBDIR . '/' ) . '%'
			)
		);

		/*
		 * Same reasoning as `referenced_files()`, and the same test: `get_col()`
		 * always returns an array, so the failure has to be read from `last_error`
		 * or it cannot be read at all.
		 */
		if ( '' !== trim( (string) $wpdb->last_error ) || ! is_array( $rows ) ) {
			return null;
		}

		return array_map(
			static fn( $relative ): string => $basedir . (string) $relative,
			$rows
		);
	}

	/**
	 * Returns how long a file is kept before it counts as orphaned.
	 */
	private function retention(): int {
		$hours = max( 1, Settings::number( 'upload_retention' ) );

		return $hours * HOUR_IN_SECONDS;
	}
}