<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Secrets;

/**
 * Filesystem questions about key folders that never emit a PHP warning (Phase 87, D6).
 *
 * Strict hosts confine PHP with open_basedir; asking about a path outside it (the parent of WordPress, for example) raises a warning
 * that names an absolute path, and with display_errors on that text would be printed into administrator pages. An answer about a
 * path PHP may not look at is simply "no" ("not there / not usable"), which is also the fail-closed answer. Nothing here writes.
 */
final class Fs
{
    public static function isFile(string $path): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @is_file($path);
    }

    public static function isDir(string $path): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @is_dir($path);
    }

    public static function isLink(string $path): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @is_link($path);
    }

    public static function exists(string $path): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @file_exists($path);
    }

    public static function isWritable(string $path): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_is_writable -- checks whether the key folder can be written before anything is created
        return @is_writable($path);
    }

    public static function realpath(string $path): string|false
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @realpath($path);
    }

    /** Sets a file's mode; false (and no warning) when the account may not. Used only to tighten a key file to 0600. */
    public static function chmod(string $path, int $mode): bool
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged, WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- private key file mode 0600; a refusal reads as "false", not as a warning
        return @chmod($path, $mode);
    }

    /** @return array<string, int|float>|false stat() (follows links) */
    public static function stat(string $path): array|false
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @stat($path);
    }

    /** @return array<string, int|float>|false lstat() (does not follow a final link) */
    public static function lstat(string $path): array|false
    {
        // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an open_basedir restriction must read as "no" and not print a path
        return @lstat($path);
    }
}