Method resolveFolderPath

src/FileRise/Domain/FolderModel.php:1109–1153

* Resolve a (possibly nested) relative folder like "invoices/2025" to a real path * under UPLOAD_DIR. Validates each path segment against REGEX_FOLDER_NAME, enforces * containment, and (optionally) creates the folder. * * @param string $folder Relative folder or "root" * @param bool $create Create the folder if missing * @return array [string|null $realPath, strin

(string $folder, bool $create = false)

     * @return array [string|null $realPath, string   $relative, string|null $error]
     */
    private static function resolveFolderPath(string $folder, bool $create = false): array
    {
        $folder   = trim($folder) ?: 'root';
        $relative = 'root';

        $storage = self::storage();
        $isLocal = $storage->isLocal();
        $base = $isLocal ? realpath(self::uploadRoot()) : rtrim(self::uploadRoot(), '/\\');
        if ($base === false || $base === '') {
            return [null, 'root', "Uploads directory not configured correctly."];
        }

        if (strtolower($folder) === 'root') {
            $dir = $base;
        } else {
            $parts = self::splitFolderSegments($folder);
            if ($parts === null || $parts === []) {
                return [null, 'root', "Invalid folder name."];
            }
            $relative = implode('/', $parts);
            $dir      = $base . DIRECTORY_SEPARATOR . implode(DIRECTORY_SEPARATOR, $parts);
        }

        $dirStat = $isLocal ? null : $storage->stat($dir);
        $dirExists = $isLocal ? is_dir($dir) : ($dirStat !== null && ($dirStat['type'] ?? '') === 'dir');
        if (!$dirExists) {
            if ($create) {
                if (!$storage->mkdir($dir, 0775, true)) {
                    return [null, $relative, "Failed to create folder."];
                }
            } else {
                return [null, $relative, "Folder does not exist."];
            }
        }

        if ($isLocal) {
            $real = realpath($dir);
            if ($real === false || !self::isPathInsideOrSame($base, $real)) {
                return [null, $relative, "Invalid folder path."];
            }
            return [$real, $relative, null];
        }

        return [$dir, $relative, null];
    }

    private static function resolveFolderPathForAdapter(StorageAdapterInterface $storage, string $root, string $folder, bool $create = false): array
    {