Method saveFile

src/FileRise/Domain/FileModel.php:1213–1322

* Save a file’s contents *and* record its metadata, including who uploaded it. * * @param string $folder Folder key (e.g. "root" or "invoices/2025") * @param string $fileName Basename of the file * @param resource|string $content File contents (stream or string) * @param string|null $uploader Username of uploader (if nul

(string $folder, string $fileName, $content, ?string $uploader = null)

     * @return array                          ["success"=>"…"] or ["error"=>"…"]
     */
    public static function saveFile(string $folder, string $fileName, $content, ?string $uploader = null): array
    {
        $folder   = trim($folder) ?: 'root';
        $fileName = basename(trim($fileName));

        if (strtolower($folder) !== 'root' && !preg_match(REGEX_FOLDER_NAME, $folder)) {
            return ["error" => "Invalid folder name"];
        }
        if (!UploadNamePolicy::isAllowedForWrite($fileName)) {
            return ["error" => "Invalid file name"];
        }

        $storage = self::storage();
        $isLocal = $storage->isLocal();
        $root = self::uploadRoot();
        $baseDirReal = $isLocal ? realpath($root) : rtrim($root, '/\\');
        if ($baseDirReal === false || $baseDirReal === '') {
            return ["error" => "Server misconfiguration"];
        }

        $root = self::uploadRoot();

        if (!$isLocal) {
            try {
                if (FolderCrypto::isEncryptedOrAncestor($folder)) {
                    return ["error" => "Encrypted folders are not supported for remote storage."];
                }
            } catch (\Throwable $e) {
/* ignore */
            }
        }

        $targetDir = (strtolower($folder) === 'root')
            ? rtrim($root, '/\\') . DIRECTORY_SEPARATOR
            : rtrim($root, '/\\') . DIRECTORY_SEPARATOR . trim($folder, "/\\ ") . DIRECTORY_SEPARATOR;

        // Ensure directory exists *before* realpath + containment check
        $dirStat = $storage->stat($targetDir);
        if ($dirStat === null || $dirStat['type'] !== 'dir') {
            if (!$storage->mkdir($targetDir, 0775, true)) {
                return ["error" => "Failed to create destination folder"];
            }
        }

        if ($isLocal) {
            $targetDirReal = realpath($targetDir);
            if ($targetDirReal === false || strpos($targetDirReal, $baseDirReal) !== 0) {
                return ["error" => "Invalid folder path"];
            }
            $filePath = $targetDirReal . DIRECTORY_SEPARATOR . $fileName;
        } else {
            $filePath = rtrim($targetDir, '/\\') . DIRECTORY_SEPARATOR . $fileName;
        }

        if (is_resource($content)) {
            if ($isLocal) {
                $out = fopen($filePath, 'wb');
                if ($out === false) {