<?php
// +----------------------------------------------------------------------
// | onezan-admin 快速开发的管理平台
// +----------------------------------------------------------------------
// | 官方网址：https://www.onezan.cn
// +----------------------------------------------------------------------
// | onezan团队 版权所有 开源版本可自由商用
// +----------------------------------------------------------------------
// | Author: 543885307@qq.com
// +----------------------------------------------------------------------
namespace app\service\domain\storage\gateway;


/**
 * Storage Gateway Interface
 * @package app\service\domain\storage\gateway
 */
interface StorageGatewayInterface
{
    /**
     * 上传文件到存储
     * @param string $localPath 本地文件路径
     * @param string $remotePath 远程文件路径
     * @param array $options 上传选项
     * @return array 上传结果
     */
    public function upload(string $localPath, string $remotePath, array $options = []): array;


    /**
     * 删除存储中的文件
     * @param string $remotePath 远程文件路径
     * @return bool 是否删除成功
     */
    public function delete(string $remotePath): bool;

    /**
     * 获取七牛 Kodo 存储中的文件 URL
     * @param string $remotePath 远程文件路径
     * @param int $expireSeconds 过期时间（秒）
     * @return string 文件 URL
     */
    public function url(string $remotePath, int $expireSeconds = 0): string;

    /**
     * 获取存储提供程序名称
     * @return string 存储提供程序名称
     */
    public function provider(): string;

    /**
     * 获取存储名称
     * @return string 存储名称
     */
    public function name(): string;

    /**
     * 检查存储配置是否已配置
     * @return bool 是否已配置
     */
    public function isConfigured(): bool;
}