<?php
namespace Relay\Files;

use Relay\Support\RelayError;

/**
 * Small filesystem helpers that never follow symlinks out of the tree they work on, and the one place Relay calls
 * PHP's own file functions. Backups and migrations stream files of any size in chunks and swap folders atomically;
 * WP_Filesystem has no streaming API, and its FTP methods can ask for credentials in the middle of a job.
 */
final class Fs
{
    /**
     * Move a file or directory to a path that must not exist yet (never merges). Falls back to copy + delete
     * only when the two paths are on different filesystems; any other failure leaves both untouched.
     */
    public static function move(string $from, string $to): void
    {
        if (file_exists($to) || is_link($to) || (!file_exists($from) && !is_link($from))) {
            throw self::failed(esc_html($from), esc_html($to));
        }
        self::ensure_dir(dirname($to));
        if (self::rename($from, $to)) {
            return;
        }
        $source = file_exists($from) || is_link($from) ? lstat($from) : false;
        $target = is_dir(dirname($to)) ? stat(dirname($to)) : false;
        if ($source === false || $target === false || $source['dev'] === $target['dev']) {
            throw self::failed(esc_html($from), esc_html($to));
        }
        self::copy_tree($from, $to);
        self::remove_tree($from);
    }

    /** Copy a file, symlink or directory tree. A symlink is copied as a symlink: what it points to is never copied. */
    public static function copy_tree(string $from, string $to): void
    {
        if (is_link($from)) {
            self::ensure_dir(dirname($to));
            $target = readlink($from);
            if ($target === false || !function_exists('symlink') || !wp_is_writable(dirname($to)) || file_exists($to) || is_link($to) || !symlink($target, $to)) {
                throw self::failed(esc_html($from), esc_html($to));
            }
            return;
        }
        if (is_file($from)) {
            self::ensure_dir(dirname($to));
            if (!is_readable($from) || !wp_is_writable(dirname($to)) || !copy($from, $to)) {
                throw self::failed(esc_html($from), esc_html($to));
            }
            return;
        }
        self::ensure_dir($to);
        foreach (scandir($from) ?: [] as $name) {
            if ($name !== '.' && $name !== '..') {
                self::copy_tree($from . '/' . $name, $to . '/' . $name);
            }
        }
    }

    /** Delete a file, symlink (not its target) or directory tree. */
    public static function remove_tree(string $path): void
    {
        if (is_link($path) || is_file($path)) {
            wp_delete_file($path);
            return;
        }
        if (!is_dir($path)) {
            return;
        }
        foreach (scandir($path) ?: [] as $name) {
            if ($name !== '.' && $name !== '..') {
                self::remove_tree($path . '/' . $name);
            }
        }
        if (self::is_empty_dir($path)) {
            rmdir($path); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir -- removes the folder once emptied above; WP_Filesystem would need credentials
        }
    }

    private static function is_empty_dir(string $dir): bool
    {
        $names = is_readable($dir) ? scandir($dir) : false;
        return is_array($names) && count($names) <= 2;
    }

    /** Remove $dir and the folders under it that hold no files; anything with a file in it stays. */
    public static function remove_empty_dirs(string $dir): void
    {
        if (is_link($dir) || !is_dir($dir)) {
            return;
        }
        foreach (scandir($dir) ?: [] as $name) {
            if ($name !== '.' && $name !== '..') {
                self::remove_empty_dirs($dir . '/' . $name);
            }
        }
        if (self::is_empty_dir($dir)) {
            rmdir($dir); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir -- only once nothing is left inside
        }
    }

    public static function ensure_dir(string $dir): void
    {
        if (!is_dir($dir) && !wp_mkdir_p($dir) && !is_dir($dir)) {
            /* translators: %s: folder path */
            throw new RelayError('files.mkdir_failed', esc_html(sprintf(__('Could not create the folder %s.', 'siterelay'), $dir)), esc_html__('Check the file permissions of wp-content.', 'siterelay'));
        }
    }

    /**
     * Create $rel under $base one folder at a time, refusing to go through a symlink or a file (so nothing is
     * ever created outside $base). $base itself may be a symlink, e.g. an uploads folder on shared storage.
     */
    public static function ensure_dir_within(string $base, string $rel): string
    {
        $dir = rtrim($base, '/');
        self::ensure_dir($dir);
        foreach ($rel === '' || $rel === '.' ? [] : explode('/', $rel) as $segment) {
            $dir .= '/' . $segment;
            if ($segment === '' || $segment === '.' || $segment === '..' || is_link($dir) || (file_exists($dir) && !is_dir($dir)) || (!is_dir($dir) && (!wp_is_writable(dirname($dir)) || !mkdir($dir, 0755)) && !is_dir($dir))) { // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir -- one level at a time, so a symlink can't redirect the path
                /* translators: %s: folder path */
                throw new RelayError('files.mkdir_failed', esc_html(sprintf(__('Could not create the folder %s.', 'siterelay'), $dir)), esc_html__('A file, symlink or permission problem is in the way. Check that folder on the server.', 'siterelay'));
            }
        }
        return $dir;
    }

    /** A folder with index.php and a deny-all .htaccess, for Relay's private working data. */
    public static function ensure_private_dir(string $dir): string
    {
        self::ensure_dir($dir);
        if (!file_exists($dir . '/index.php')) {
            self::put($dir . '/index.php', "<?php\n// Silence is golden.\n");
        }
        if (!file_exists($dir . '/.htaccess')) {
            self::put($dir . '/.htaccess', "Require all denied\n<IfModule !mod_authz_core.c>\nDeny from all\n</IfModule>\n");
        }
        return $dir;
    }

    /** Write (or with $append, add to) a file; a failed or short write throws, so nothing goes on with half a file. */
    public static function put(string $path, string $data, bool $append = false): void
    {
        if (!self::writable($path) || file_put_contents($path, $data, $append ? FILE_APPEND : 0) !== strlen($data)) {
            throw new RelayError(
                'files.write_failed',
                /* translators: %s: file path */
                esc_html(sprintf(__('Could not write %s.', 'siterelay'), $path)),
                esc_html__('The disk may be full, or the web server may not be allowed to write there.', 'siterelay')
            );
        }
    }

    /**
     * A file handle, or false when the file can't be opened that way (checked first: fopen() would warn).
     *
     * @return resource|false
     */
    public static function open(string $path, string $mode)
    {
        if (strpos($path, '://') === false && !self::can_open($path, $mode)) {
            return false;
        }
        return fopen($path, $mode); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen -- streams files of any size in chunks (see the class note)
    }

    private static function can_open(string $path, string $mode): bool
    {
        if ($mode[0] === 'r') {
            return is_file($path) && is_readable($path) && (strpos($mode, '+') === false || wp_is_writable($path));
        }
        if (file_exists($path)) {
            return is_file($path) && wp_is_writable($path) && ($mode[0] !== 'x');
        }
        return is_dir(dirname($path)) && wp_is_writable(dirname($path));
    }

    /**
     * @param resource $handle
     * @return string|false
     */
    public static function read($handle, int $length)
    {
        return fread($handle, $length); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fread -- streams files of any size in chunks (see the class note)
    }

    /**
     * @param resource $handle
     * @return int|false
     */
    public static function write($handle, string $data)
    {
        return fwrite($handle, $data); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fwrite -- streams files of any size in chunks (see the class note)
    }

    /** @param resource $handle */
    public static function close($handle): bool
    {
        return fclose($handle); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- closes a stream opened by open()
    }

    /**
     * Atomic within one filesystem: what file swaps and staged files rely on. False, without trying, where rename()
     * would fail (and warn): nothing to move, a folder in the way, no write access, or another filesystem.
     */
    public static function rename(string $from, string $to): bool
    {
        $exists = file_exists($from) || is_link($from);
        if (!$exists || !is_dir(dirname($to)) || !wp_is_writable(dirname($to)) || !wp_is_writable(dirname($from))
            || (file_exists($to) && (is_dir($to) || is_dir($from))) || lstat($from)['dev'] !== stat(dirname($to))['dev']) {
            return false;
        }
        return rename($from, $to); // phpcs:ignore WordPress.WP.AlternativeFunctions.rename_rename -- atomic swap within one filesystem; WP_Filesystem::move() may copy
    }

    public static function touch(string $path, int $mtime): bool
    {
        return is_file($path) && wp_is_writable($path) && touch($path, $mtime); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_touch -- keeps a copied file's modification time, which "only new or changed" compares
    }

    /** What is at $path, without following a symlink: 'link', 'dir', 'file' (any other kind too), or null for nothing. */
    public static function kind(string $path): ?string
    {
        if (!is_link($path) && !file_exists($path)) {
            return null;
        }
        $stat = lstat($path);
        if ($stat === false) {
            return null;
        }
        $type = $stat['mode'] & 0170000;
        return $type === 0120000 ? 'link' : ($type === 0040000 ? 'dir' : 'file');
    }

    /** Whether $path can be written: an existing file that is writable, or a new one in a writable folder. */
    public static function writable(string $path): bool
    {
        return file_exists($path) ? is_file($path) && wp_is_writable($path) : is_dir(dirname($path)) && wp_is_writable(dirname($path));
    }

    /**
     * Free space on the disk that holds $dir in bytes, or false when the host doesn't say.
     *
     * @return float|false
     */
    public static function free_space(string $dir)
    {
        return function_exists('disk_free_space') && is_dir($dir) ? disk_free_space($dir) : false;
    }

    /** Send a file to the browser (downloads of exports and backups). */
    public static function send(string $path): void
    {
        readfile($path); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_readfile -- streams a download of any size without loading it into memory
    }

    /** Send $length bytes of a file from $start (a piece of a download). */
    public static function send_range(string $path, int $start, int $length): void
    {
        $in = self::open($path, 'rb');
        $out = self::open('php://output', 'wb');
        if ($in === false || $out === false) {
            return;
        }
        stream_copy_to_stream($in, $out, $length, $start);
        self::close($in);
        self::close($out);
    }

    private static function failed(string $from, string $to): RelayError
    {
        return new RelayError(
            'restore.file_swap_failed',
            /* translators: 1: source path, 2: destination path */
            esc_html(sprintf(__('Could not move %1$s to %2$s.', 'siterelay'), $from, $to)),
            esc_html__('Check the file permissions of wp-content.', 'siterelay')
        );
    }
}