# efun-cloud-uploader **Repository Path**: DPF1994/efun-cloud-uploader ## Basic Information - **Project Name**: efun-cloud-uploader - **Description**: PHP 基于webman框架云存储文件上传类库,提供统一接口对接阿里云 OSS、腾讯云 COS、七牛云 Kodo,以及本地文件系统。包含单文件多文件,base64,服务端,大文件分片上传 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-18 - **Last Updated**: 2026-07-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # efun/cloud-uploader PHP 通用云存储文件上传类库,提供统一接口对接**阿里云 OSS**、**腾讯云 COS**、**七牛云 Kodo**,以及**本地文件系统**。 ## 特性 - **统一接口** — 通过适配器模式封装不同云服务商的 SDK,调用方无需关心底层差异 - **多种上传方式** — 表单上传、本地文件上传、Base64 上传、分片上传、批量上传 - **灵活验证规则** — 可配置单文件大小限制、总大小限制、文件数量、扩展名白名单/黑名单 - **统一返回结构** — 每次上传均返回 `UploadResult`,包含完整的上传信息 - **易于扩展** — 接入新的云存储只需新增一个适配器类,无需修改核心代码 - **本地适配器** — 内置 `LocalStorageAdapter`,可将文件直接保存到服务器本地目录,方便开发调试 - **配置驱动** — 提供 `Storage::disk()` 门面,一行代码切换存储引擎,验证规则和适配器配置统一管理 ## 环境要求 - PHP >= 7.4 - Composer ## 安装 ```bash composer require efun/cloud-uploader ``` 如需使用具体的云存储服务,请同时安装对应的 SDK: ```bash # 阿里云 OSS composer require aliyuncs/oss-sdk-php # 腾讯云 COS composer require qcloud/cos-sdk-v5 # 七牛云 Kodo composer require qiniu/php-sdk ``` ## 快速开始 ```php 'your-access-key-id', 'accessKeySecret' => 'your-access-key-secret', 'endpoint' => 'oss-cn-hangzhou.aliyuncs.com', 'bucket' => 'your-bucket-name', 'dirname' => 'crmAdmin', // 必填:存储目录前缀 'domain' => 'https://cdn.example.com', // 必填:自定义访问域名 ]); // 3. 创建上传器(规则通过链式调用或按次传参设置,详见下方「规则的三种传递方式」) $uploader = new FileUploader($adapter); // 链式设置验证规则 $uploader->setDefaultRule($rule); // 4. 上传本地文件 $result = $uploader->uploadLocalFile('/path/to/report.pdf'); if ($result->isSuccess()) { echo "上传成功!\n"; echo "访问 URL: " . $result->getUrl() . "\n"; } else { echo "上传失败: " . $result->getError() . "\n"; } ``` ## Storage 门面(配置驱动,推荐) 除了手动创建适配器和验证规则外,本库还提供 `Storage` 门面类,通过配置数组统一管理所有存储引擎和验证规则,一行代码即可切换磁盘。 ### 磁盘名称常量 `Storage` 类内置了磁盘名称常量,避免字符串硬编码,提高代码可维护性: | 常量 | 值 | 说明 | |------|------|------| | `Storage::LOCAL` | `'local'` | 本地文件系统 | | `Storage::OSS` | `'oss'` | 阿里云 OSS | | `Storage::COS` | `'cos'` | 腾讯云 COS | | `Storage::QINIU` | `'qiniu'` | 七牛云 Kodo | ### 配置文件 默认配置文件位于 `config/app.php`,通过 `require` 加载后传入 `Storage::loadConfig()` 即可: ```php // config/app.php 核心结构 return [ 'enable' => true, // 全局开关 'storage' => [ 'default' => 'local', // 默认磁盘:local / oss / cos / qiniu 'single_limit' => 1024 * 1024 * 200, // 单文件 200MB 'total_limit' => 1024 * 1024 * 200, // 总大小 200MB 'nums' => 10, // 最大文件数 'include' => [], // 白名单扩展名 'exclude' => [], // 黑名单扩展名 'local' => [ 'adapter' => \CloudUploader\Adapters\LocalStorageAdapter::class, 'root' => '/path/to/storage', 'dirname' => function () { return date('Ymd'); }, 'domain' => 'http://127.0.0.1:8787', 'uri' => '/runtime', ], 'oss' => [ 'adapter' => \CloudUploader\Adapters\AliyunOssAdapter::class, 'accessKeyId' => getenv('OSS_KEY_ID'), 'accessKeySecret' => getenv('OSS_KEY_SECRET'), 'bucket' => getenv('OSS_BUCKET'), 'dirname' => function () { return 'crmSaas'; }, 'domain' => getenv('OSS_DOMAIN'), 'endpoint' => 'oss-cn-beijing.aliyuncs.com', 'isCName' => false, ], 'cos' => [ 'adapter' => \CloudUploader\Adapters\TencentCosAdapter::class, 'secretId' => getenv('COS_SECRET_ID'), 'secretKey' => getenv('COS_SECRET_KEY'), 'bucket' => getenv('COS_BUCKET'), 'dirname' => 'storage', 'domain' => getenv('COS_DOMAIN'), 'region' => 'ap-shanghai', ], 'qiniu' => [ 'adapter' => \CloudUploader\Adapters\QiniuKodoAdapter::class, 'accessKey' => getenv('QINIU_ACCESS_KEY'), 'secretKey' => getenv('QINIU_SECRET_KEY'), 'bucket' => getenv('QINIU_BUCKET'), 'dirname' => 'storage', 'domain' => getenv('QINIU_DOMAIN'), ], ], ]; ``` 配置文件可放置在项目中的任意位置,通过 `require` 加载为数组后传入 `Storage::loadConfig()`。配合 `getenv()` 读取环境变量,敏感信息(AccessKey 等)无需硬编码。 ### 基本用法 ```php use CloudUploader\Storage; // 加载配置数组(先 require 得到数组,再传入 loadConfig) $config = require __DIR__ . '/config/app.php'; Storage::loadConfig($config); // 使用默认磁盘(由配置文件 storage.default 决定) $uploader = Storage::disk(); $result = $uploader->uploadLocalFile('/path/to/file.pdf'); // 切换到阿里云 OSS(使用常量) $oss = Storage::disk(Storage::OSS); $result = $oss->multipartUpload('/path/to/large.mp4', 10 * 1024 * 1024); // 切换配置后再使用七牛云 Kodo Storage::loadConfig($qiniuConfig); $qiniu = Storage::disk(Storage::QINIU); $result = $qiniu->uploadBase64('data:image/png;base64,...'); ``` ### 完整示例 ```php use CloudUploader\Storage; // 从自定义位置加载配置 $config = require __DIR__ . '/config/upload.php'; Storage::loadConfig($config); // 使用默认磁盘上传 $uploader = Storage::disk(); $result = $uploader->uploadLocalFile('/path/to/report.pdf'); if ($result->isSuccess()) { echo "上传成功:" . $result->getUrl(); } // 运行时动态切换磁盘(使用常量) $result = Storage::disk(Storage::OSS)->uploadLocalFile('/path/to/backup.zip'); $result = Storage::disk(Storage::COS)->uploadLocalFile('/path/to/archive.tar.gz'); // 按次覆盖验证规则(规则优先级不变) $result = Storage::disk()->uploadLocalFile( '/path/to/bigfile.mp4', new ValidationRule(['single_limit' => 2 * 1024 * 1024 * 1024]) ); // 手动三步分片上传(通过适配器) $adapter = Storage::disk(Storage::OSS)->getAdapter(); $init = $adapter->initiateMultipartUpload('large.mp4'); // ... uploadPart 循环 ... // ... completeMultipartUpload ... ``` ### 自定义磁盘扩展 ```php use CloudUploader\Storage; // 注册自定义适配器(如 MinIO、S3 等) Storage::registerDisk('minio', MyMinioAdapter::class); // 在配置数组中添加对应磁盘配置后即可使用 $minio = Storage::disk('minio'); ``` ### Storage 与手动创建对比 | 方式 | 适用场景 | |------|----------| | **`Storage::disk()`** | 生产项目,多磁盘切换,配置集中管理 | | **手动 `new FileUploader($adapter, $rule)`** | 快速原型,临时脚本,需要动态构造适配器参数 | 两种方式底层完全兼容,`Storage::disk()` 返回的也是 `FileUploader` 实例,所有上传方法和验证规则传递方式完全一致。 ## 验证规则配置 ```php $rule = new ValidationRule([ 'single_limit' => 10 * 1024 * 1024, // 单个文件最大 10MB(默认 200MB) 'total_limit' => 50 * 1024 * 1024, // 总大小最大 50MB(默认 200MB) 'nums' => 5, // 最多允许 5 个文件(默认 10) 'include' => ['xlsx', 'pdf', 'docx'], // 白名单:仅允许这些扩展名 'exclude' => ['exe', 'bat'], // 黑名单:禁止这些扩展名 ]); ``` **优先级规则**:当 `include` 不为空时,只检查白名单,`exclude` 被忽略。`include` 为空时 `exclude` 才生效。 也可通过链式调用动态修改: ```php $rule = (new ValidationRule()) ->setSingleLimit(5 * 1024 * 1024) ->setNums(3) ->setInclude(['pdf', 'doc']); ``` ### 规则的三种传递方式 验证规则可通过以下三种方式传递给上传方法,按优先级从高到低: | 方式 | 优先级 | 说明 | |------|--------|------| | **按次传参** | 最高 | 调用上传方法时直接传入 `$rule`,覆盖所有其他规则 | | **链式调用** | 中等 | `setDefaultRule()` 返回 `$this`,调用后立即生效 | | **系统默认** | 最低(兜底) | 未设置任何规则时,自动使用内置默认值(200MB/10个文件) | ```php // 方式 A:按次传参(最高优先级,仅本次上传生效) $result = $uploader->uploadLocalFile('/path/to/file.pdf', new ValidationRule(['single_limit' => 2 * 1024 * 1024]) ); // 方式 B:链式调用 setDefaultRule 后立即上传 $result = $uploader->setDefaultRule(new ValidationRule([ 'single_limit' => 5 * 1024 * 1024, 'include' => ['pdf', 'docx'], ]))->uploadLocalFile('/path/to/doc.pdf'); // 方式 C:不设置任何规则,使用系统内置默认值(200MB/10个文件) $uploader = new FileUploader($adapter); $result = $uploader->uploadLocalFile('/path/to/file.pdf'); // 使用系统默认 200MB 限制 $result = $uploader->uploadLocalFile('/path/to/large.pdf', // 按次覆盖为 100MB new ValidationRule(['single_limit' => 100 * 1024 * 1024]) ); ``` ## 上传方法 ### 1. 表单文件上传 接收框架的 `UploadFile` 对象(webman / Laravel),通过鸭子类型自动识别,无需硬依赖: ```php // 单文件:$request->file('file') 返回 UploadFile 对象,直接传入 $result = $uploader->formUpload($request->file('file')); // 多文件: // webman / Laravel 返回 UploadFile[] 数组,直接传入 $results = $uploader->formUpload($request->file('files')); // 单次上传时覆盖默认验证规则 $result = $uploader->formUpload($request->file('file'), $oneTimeRule); ``` ### 2. 本地文件上传 ```php $result = $uploader->uploadLocalFile('/var/www/data.xlsx'); // 按次覆盖验证规则 $result = $uploader->uploadLocalFile('/var/www/data.xlsx', new ValidationRule(['single_limit' => 5 * 1024 * 1024]) ); ``` ### 3. Base64 文件上传 ```php // 纯 Base64(需同时指定文件名) $result = $uploader->uploadBase64($base64Str, 'avatar.jpg'); // Data URI 格式(自动提取 MIME 类型和扩展名) $result = $uploader->uploadBase64('data:image/png;base64,iVBORw0KG...'); // 按次覆盖验证规则 $result = $uploader->uploadBase64($base64Str, 'file.pdf', new ValidationRule(['single_limit' => 10 * 1024 * 1024]) ); ``` ### 4. 大文件分片上传 **便捷方法(一步完成)**:对于大多数场景,可直接使用 `multipartUpload()` 便捷方法,内部自动完成初始化→逐片上传→合并的完整流程: ```php // 便捷方法(服务端自动分片,无需手动控制每个分片) $result = $uploader->multipartUpload( '/path/to/large-video.mp4', 10 * 1024 * 1024 // 分片大小 10MB(默认 5MB) ); // 按次覆盖验证规则 $result = $uploader->multipartUpload( '/path/to/large-video.mp4', 10 * 1024 * 1024, new ValidationRule(['single_limit' => 2 * 1024 * 1024 * 1024]) ); ``` **手动分片(三步流程)**:如需精确控制每个分片的上传进度(例如前端进度条),可通过适配器直接调用分步接口: ```php $adapter = $uploader->getAdapter(); $filePath = '/path/to/large-video.mp4'; $fileName = basename($filePath); $partSize = 5 * 1024 * 1024; // 每个分片 5MB $fileSize = filesize($filePath); // 第一步:初始化分片上传,获取 uploadId 和云端对象路径 $init = $adapter->initiateMultipartUpload($fileName); $uploadId = $init['uploadId']; $object = $init['object']; $parts = []; $partNumber = 1; $offset = 0; try { // 第二步:循环上传每个分片 while ($offset < $fileSize) { $length = min($partSize, $fileSize - $offset); $part = $adapter->uploadPart( $uploadId, $object, $partNumber, $filePath, $offset, $length ); // uploadPart 返回包含 partNumber + etag(OSS/COS)或 ctx(七牛)的数组 $parts[] = $part; $partNumber++; $offset += $length; } // 第三步:提交所有分片标识,完成云端合并 $result = $adapter->completeMultipartUpload($uploadId, $object, $parts); echo "上传成功,URL: " . $result->getUrl(); } catch (\Throwable $e) { // 发生异常时中止上传,清理已上传的分片碎片 $adapter->abortMultipartUpload($uploadId, $object); throw $e; } ``` ### 5. 批量上传(混合来源) ```php $results = $uploader->batchUpload([ // 字符串:本地文件路径 '/var/www/uploads/doc1.pdf', // 带自定义名称的路径 ['path' => '/var/www/uploads/doc2.docx', 'name' => '报告文档.docx'], // Base64 内容 ['base64' => base64_encode('Hello'), 'name' => 'hello.txt'], // Data URI 格式的 Base64 ['base64' => 'data:image/png;base64,...', 'name' => 'screenshot.png'], // webman / Laravel UploadFile 对象(鸭子类型自动识别) $request->file('file'), ]); // 按次覆盖验证规则 $results = $uploader->batchUpload($files, new ValidationRule(['nums' => 3])); ``` ### 6. 前端 + 后端协作分片上传 适用于前端进度条、大文件断点续传等场景。前端使用 `File.slice()` 切片,逐片发送给后端;后端接收后通过适配器逐片上传至云端,最后合并。 **接口约定(4 个端点)**: | 端点 | 方法 | 说明 | |------|------|------| | `/api/upload/initiate` | POST | 初始化,返回 `{uploadId, object}` | | `/api/upload/part` | POST | 上传一个分片,返回 `{partNumber, etag/ctx}` | | `/api/upload/complete` | POST | 合并所有分片,返回 `UploadResult` | | `/api/upload/abort` | POST | 取消上传,清理碎片 | **前端(JavaScript)**: ```javascript async function upload() { const file = document.getElementById('fileInput').files[0]; const CHUNK_SIZE = 10 * 1024 * 1024; // 每片 10MB,最小值取决于云厂商 const totalChunks = Math.ceil(file.size / CHUNK_SIZE); // ① 初始化(后端返回 uploadId + object) const initRes = await fetch('/api/upload/initiate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ filename: file.name }), }); const { uploadId, object } = await initRes.json(); // ② 逐片上传 const parts = []; for (let i = 0; i < totalChunks; i++) { const start = i * CHUNK_SIZE; const end = Math.min(start + CHUNK_SIZE, file.size); const chunk = file.slice(start, end); const formData = new FormData(); formData.append('uploadId', uploadId); formData.append('object', object); formData.append('partNumber', i + 1); formData.append('file', chunk, file.name); const partRes = await fetch('/api/upload/part', { method: 'POST', body: formData, }); const part = await partRes.json(); parts.push(part); const percent = Math.round((end / file.size) * 100); console.log(`上传进度: ${percent}%`); } // ③ 合并(元数据由适配器从文件缓存自动恢复,无需前端回传) const completeRes = await fetch('/api/upload/complete', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ uploadId, object, parts }), }); const result = await completeRes.json(); console.log('上传完成', result); } ``` **后端(webman 控制器)**: ```php use CloudUploader\Storage; class MultipartController { /** * ① 初始化分片上传 * POST /api/upload/initiate Body: { "filename": "video.mp4" } */ public function initiate(Request $request) { $filename = $request->input('filename'); $adapter = Storage::disk(Storage::OSS)->getAdapter(); $init = $adapter->initiateMultipartUpload($filename); return json([ 'uploadId' => $init['uploadId'], 'object' => $init['object'], ]); } /** * ② 上传单个分片 * POST /api/upload/part FormData: uploadId, object, partNumber, file */ public function uploadPart(Request $request) { $uploadId = $request->post('uploadId'); $object = $request->post('object'); $partNumber = (int)$request->post('partNumber'); $file = $request->file('file'); if (!$file || !$file->isValid()) { return json(['code' => 1, 'msg' => '文件无效']); } // 写入临时文件(webman 的 move() 接受完整目标路径) $tempFile = tempnam(sys_get_temp_dir(), 'chunk_'); if ($tempFile === false) { return json(['code' => 1, 'msg' => '创建临时文件失败']); } $file->move($tempFile); // 校验文件是否成功写入 if (!file_exists($tempFile)) { return json(['code' => 1, 'msg' => '临时文件写入失败']); } $chunkSize = filesize($tempFile); try { $adapter = Storage::disk(Storage::OSS)->getAdapter(); $part = $adapter->uploadPart( $uploadId, $object, $partNumber, $tempFile, 0, // offset = 0(临时文件只有这一片) $chunkSize ); return json($part); } finally { @unlink($tempFile); } } /** * ③ 合并分片 * POST /api/upload/complete Body: { uploadId, object, parts: [...] } */ public function complete(Request $request) { $uploadId = $request->input('uploadId'); $object = $request->input('object'); $parts = $request->input('parts'); $adapter = Storage::disk(Storage::OSS)->getAdapter(); $result = $adapter->completeMultipartUpload($uploadId, $object, $parts); return json($result); } /** * ④ 取消上传(前端主动取消或上传失败时调用) * POST /api/upload/abort Body: { uploadId, object } */ public function abort(Request $request) { $uploadId = $request->input('uploadId'); $object = $request->input('object'); $adapter = Storage::disk(Storage::OSS)->getAdapter(); $adapter->abortMultipartUpload($uploadId, $object); return json(['success' => true]); } } ``` ## 返回结果结构 每次上传返回 `UploadResult` 对象,实现了 `ArrayAccess`、`JsonSerializable` 和 `__toString()`,支持多种访问方式: ### 返回字段 | 字段 | 类型 | 说明 | 示例 | |------|------|------|------| | `success` | bool | 是否成功 | `true` | | `origin_name` | string | 原始文件名 | `'常用编程软件和工具.xlsx'` | | `save_name` | string | 保存文件名 | `'03414c9b...xlsx'` | | `save_path` | string | 保存路径 | `'crmAdmin/20260717/03414c9b...xlsx'` | | `url` | string | 访问 URL | `'https://...'` | | `unique_id` | string | 唯一标识 | `'03414c9bdaf7a...'` | | `size` | int | 文件大小(字节) | `15050` | | `mime_type` | string | MIME 类型 | `'application/...'` | | `extension` | string | 扩展名 | `'xlsx'` | | `error` | string | 错误信息(成功为空) | `''` | ### 多种访问方式 ```php $result = $uploader->uploadLocalFile('/path/to/file.pdf'); // 方式 1:Getter 方法 $url = $result->getUrl(); $isOk = $result->isSuccess(); // 方式 2:数组方式访问(ArrayAccess) $url = $result['url']; $originName = $result['origin_name']; // 方式 3:动态字段写入/覆盖 $result['db_id'] = 12345; // 写入自定义字段 $result['url'] = 'https://custom...'; // 覆盖内置字段 // 方式 4:转为数组 $data = $result->toArray(); // 方式 5:JSON 序列化(json_encode 自动调用 JsonSerializable) $json = json_encode($result, JSON_UNESCAPED_UNICODE); // 方式 6:直接作为 webman / Laravel 控制器返回值(自动调用 __toString()) return $result; // 自动输出 JSON 字符串 ``` ### 失败结果 ```php // 失败上传返回的 UploadResult,success 为 false,error 包含错误信息 $result = UploadResult::failure('文件大小超过限制', ['origin_name' => 'bigfile.mp4']); echo $result['success']; // false echo $result['error']; // '文件大小超过限制' ``` ### 多文件上传返回 ```php // formUpload 多文件、batchUpload 均返回 UploadResult[] 数组 $results = $uploader->formUpload($request->file('files')); foreach ($results as $result) { if ($result['success']) { echo "上传成功: " . $result['url'] . "\n"; } else { echo "上传失败: " . $result['error'] . "\n"; } } // 失败的文件不会跳过,而是在对应位置返回 failure 结果 // 保证返回值数组与输入文件数组一一对应,顺序不变 // 直接返回给 webman 前端: return json($results); // [{...}, {...}, {...}] ``` ## 适配器配置 ### 阿里云 OSS ```php // 阿里云 OSS $adapter = new AliyunOssAdapter([ 'accessKeyId' => 'LTAI...', 'accessKeySecret' => '...', 'endpoint' => 'oss-cn-hangzhou.aliyuncs.com', 'bucket' => 'my-bucket', 'dirname' => 'crmAdmin', // 必填:存储目录前缀,支持字符串或闭包 'domain' => 'https://cdn.example.com', // 必填:自定义访问域名 ]); ``` > **isCName 参数**:使用标准 OSS endpoint(如 `oss-cn-hangzhou.aliyuncs.com`)时设为 `false`(默认);使用自定义域名/CNAME 时设为 `true`。 ### 腾讯云 COS ```php $adapter = new TencentCosAdapter([ 'secretId' => 'AKID...', 'secretKey' => '...', 'region' => 'ap-guangzhou', 'bucket' => 'my-bucket-1234567890', // 格式:BucketName-APPID 'dirname' => 'storage', // 必填:存储目录前缀,支持字符串或闭包 'domain' => 'https://cdn.example.com', // 必填:自定义访问域名 ]); ``` ### 七牛云 Kodo ```php $adapter = new QiniuKodoAdapter([ 'accessKey' => '...', 'secretKey' => '...', 'bucket' => 'my-bucket', 'dirname' => 'crmAdmin', // 必填:存储目录前缀,支持字符串或闭包 'domain' => 'https://cdn.example.com', // 必填:自定义访问域名 ]); ``` ### dirname 用法说明 `dirname` 表示文件在 Bucket 下的存储路径前缀。支持两种方式: ```php // 方式 1:固定字符串前缀 $adapter = new AliyunOssAdapter([ // ...其他配置... 'dirname' => 'crmAdmin', ]); // 文件保存路径:crmAdmin/20260717/xxxxx.xlsx // 方式 2:闭包动态生成目录(如按日期分目录) $adapter = new AliyunOssAdapter([ // ...其他配置... 'dirname' => function () { return 'uploads/' . date('Y/m/d'); }, ]); // 文件保存路径:uploads/2024/01/15/20240115/xxxxx.xlsx // dirname 为必填参数,传入空字符串将导致异常 ``` ### 本地文件系统(LocalStorageAdapter) 将文件直接保存到服务器本地目录,适用于开发调试或内部文件落地场景。 ```php $adapter = new LocalStorageAdapter([ 'root_path' => '/var/www/uploads', // 必填:本地存储根目录 'dirname' => 'local_files', // 必填:子目录前缀 'domain' => 'https://cdn.example.com', // 必填:访问域名 ]); ``` **限制说明**: - 不支持分片上传步骤方法(`initiateMultipartUpload` / `uploadPart` / `completeMultipartUpload`),调用会抛出 `UnsupportedOperationException`。 - `multipartUpload()` 便捷方法已降级为一次性写入。 ### 域名优先级 文件访问 URL 按以下优先级构建: 1. 如果配置了 `domain`,直接使用 `{domain}/{save_path}` 2. 否则使用各云服务的默认域名 ## 异常处理 ```php try { $result = $uploader->uploadLocalFile('/path/to/file.pdf'); } catch (ValidationException $e) { // 验证失败:文件大小、扩展名、数量不满足规则 echo "验证失败: " . $e->getMessage(); } catch (UploadException $e) { // 上传失败:SDK 调用失败、网络错误等 echo "上传失败: " . $e->getMessage(); // 可获取部分已收集的数据 $partialData = $e->getPartialData(); } catch (\Throwable $e) { echo "系统错误: " . $e->getMessage(); } ``` ## 扩展自定义存储适配器 实现 `StorageAdapterInterface` 并继承 `BaseStorageAdapter` 即可接入新的云存储: ```php use CloudUploader\BaseStorageAdapter; use CloudUploader\UploadResult; class MyCustomAdapter extends BaseStorageAdapter { public function upload(string $localPath, string $filename): UploadResult { // 调用你的云存储 SDK... return UploadResult::success([...]); } public function multipartUpload(string $localPath, string $filename, int $partSize = 5242880): UploadResult { // 分片上传... return UploadResult::success([...]); } public function initiateMultipartUpload(string $filename): array { // 初始化分片上传... return [...]; } public function uploadPart(string $uploadId, string $object, int $partNumber, string $localPath, int $offset, int $length): array { // 上传单个分片... return [...]; } public function completeMultipartUpload(string $uploadId, string $object, array $parts): UploadResult { // 完成分片合并... return UploadResult::success([...]); } public function abortMultipartUpload(string $uploadId, string $object): void { // 取消分片上传... } public function uploadContent(string $content, string $filename): UploadResult { // 内容上传... return UploadResult::success([...]); } } ``` ## 运行测试 ```bash # 安装开发依赖 composer install # 运行测试 vendor/bin/phpunit # 带覆盖率报告 vendor/bin/phpunit --coverage-text ``` ## 目录结构 ``` ├── src/ │ ├── UploadResult.php # 统一返回结果 DTO │ ├── ValidationRule.php # 验证规则配置 │ ├── StorageAdapterInterface.php # 适配器接口 │ ├── BaseStorageAdapter.php # 适配器基类 │ ├── FileUploader.php # 核心上传器 │ ├── Storage.php # Storage 门面(配置驱动入口) │ ├── Adapters/ │ │ ├── AliyunOssAdapter.php # 阿里云 OSS │ │ ├── TencentCosAdapter.php # 腾讯云 COS │ │ ├── QiniuKodoAdapter.php # 七牛云 Kodo │ │ └── LocalStorageAdapter.php # 本地文件系统 │ └── Exception/ │ ├── UploadException.php # 上传异常 │ ├── ValidationException.php # 验证异常 │ └── UnsupportedOperationException.php # 不支持的操作异常 ├── config/ │ └── app.php # 默认配置文件 ├── tests/ # 单元测试 ├── examples/ │ └── example.php # 完整使用示例 ├── composer.json ├── phpunit.xml └── README.md ``` ## License MIT