Download the PHP package yeh110/php-s3-lite without Composer
On this page you can find all versions of the php package yeh110/php-s3-lite. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package php-s3-lite
php-s3-lite
零第三方依赖的 S3 兼容对象存储客户端,PHP 8.1+。
内置 AWS Signature V4 签名实现,不需要 aws/aws-sdk-php,甚至不需要 Composer。
已针对 https://s3.youdomain.com(RustFS)做过端到端实测:49 项检查通过,0 失败(1 条服务端不一致告警,见文末)。
特性
| 能力 | 方法 |
|---|---|
| 上传字符串 / 本地文件 / 流 / 大文件自动分片 | put() putFile() putStream() multipartUpload() upload() |
| 远程 URL 抓取转存 | putFromUrl() fetchToFile() |
| 下载到内存 / 落盘 / 流式 / 分段 | get() getToFile() download() |
| 预签名直传(前端直传,不经过业务服务器) | presignPut() |
| 预签名预览 / 预览链接 / 下载链接 | presignGet() previewUrl() downloadUrl() publicUrl() |
| 服务端代理预览 / 下载(私密桶不暴露地址) | preview() download() |
| 列举分页 / 目录模拟 / 自动翻页 | listObjects() iterateObjects() |
| 元信息 / 存在性 / 复制 / 删除 | head() exists() size() copy() delete() deleteMany() |
| 桶操作 | listBuckets() bucketExists() |
环境要求
- PHP >= 8.1,扩展:
curl、openssl、simplexml、mbstring、hash - 不依赖 Composer。命名空间为
yeh110\S3Lite
安装
目录结构
快速开始
推荐用 S3Config::fromArray() 从环境变量读密钥:
API 速查
上传
下载与预览
预签名
远程抓取
管理
异常处理
示例
示例与测试都不内置密钥,先设置环境变量:
跑冒烟测试(会打真实服务端并自动清理):
配置项
| 配置 | 默认 | 说明 |
|---|---|---|
endpoint |
必填 | 如 https://s3.youdomain.com |
accessKey / secretKey |
必填 | 密钥 |
region |
us-east-1 |
区域不符时自动纠偏重试 |
pathStyle |
true |
路径寻址 /bucket/key;虚拟主机寻址需通配 DNS 与证书 |
verifyTls |
true |
生产务必保持 true |
caBundle |
null |
null=自动探测;''=交给 curl 默认;也可写具体路径 |
timeout / connectTimeout |
60 / 10 | 秒 |
multipartThreshold |
16 MiB | 超过则自动分片 |
multipartPartSize |
8 MiB | 不得小于 5 MiB |
presignForRange |
true |
Range 走预签名,规避服务端验签缺陷(见下) |
remoteMaxBytes |
512 MiB | 远程抓取单文件上限 |
httpVersion |
1.1 |
可改 2 |
debug |
false |
请求过程打到 STDERR |
注意事项(实测踩过的坑)
1. CA 证书:Windows 下最常见的报错
PHP 在 Windows 上常常没有配置 curl.cainfo。本库会自动探测常见位置(curl.cainfo、openssl.cafile、
/etc/ssl/certs/ca-certificates.crt、Git 自带 ca-bundle.crt、PHP 目录下的 cacert.pem 等)。
探测不到时显式指定:
2. Range 分段下载
本服务端(RustFS)存在一个验签缺陷:带 Authorization 头且携带 Range 的请求会被判为
SignatureDoesNotMatch: missing signed header: range,即使 range 已正确纳入 SignedHeaders;
而预签名(查询串认证)不受影响,匿名 Range 也正常返回 206。
因此 presignForRange 默认为 true:库在检测到 range 参数时自动改用预签名 URL 发起请求。
服务端修复后可设为 false 走标准签名路径。
3. 不支持 chunked 上传
服务端要求 Content-Length,Transfer-Encoding: chunked 会返回 400。所以:
putStream()必须显式传长度putFromUrl()先落临时文件再上传(远端可能是 chunked/gzip,长度不可预知)
4. 分片上传规则
除最后一片外,每片不得小于 5MiB(S3Config::MIN_PART_SIZE 会强制校验);
CompleteMultipartUpload 失败时库会自动 Abort,避免留下垃圾分片。
5. HeadObject 可能返回陈旧的 200
实测发现:对象删除后,同一个 key 的 head() 偶尔仍返回 200 + 旧 size/etag,
而同一时刻的独立 GET 返回 404、列举返回 0(用全新连接、全新客户端实例、独立 Python 客户端交叉验证过)。
结论是服务端 HeadObject 的不一致,不是本库的问题(RustFS 上游有同族问题: #2933、#1763、 修复 PR #2936)。
业务上如需权威判断对象是否存在,建议用列举或 GET:
6. 私密桶的访问方式
私密桶不能匿名读取,二选一:
- 预签名:
previewUrl()/downloadUrl()/presignGet(),把链接交给前端,不占业务服务器带宽 - 服务端代理:
preview()/download(),URL 与密钥特征都不暴露,便于鉴权、审计、限流
实测结论(对 https://s3.youdomain.com)
覆盖并通过:签名认证、ListBuckets、HeadBucket、对象 PUT/GET/HEAD/DELETE、ETag 与 MD5 一致、 自定义元数据保留、中文与特殊字符 Key、列举分页与目录模拟、服务端复制、分片上传(含 5MiB 下限校验与 Abort)、预签名 GET/PUT、防篡改、防跨对象复用、预览与下载链接(中文文件名)、Range 分段、 远程抓取转存、错误码与异常。
唯一告警即上文第 5 条的 HeadObject 服务端不一致。
安全建议
- 不要用根密钥跑业务:给每个应用单独建最小权限账号
- 密钥放环境变量或
chmod 600的配置文件,不要进代码仓库 - 预签名有效期按需设置(本库限制在 1 秒 ~ 7 天)
- 直传场景建议在 key 里加随机串,并由后端二次校验(大小、类型、归属),不要直接信任前端
- 生产环境保持
verifyTls: true
All versions of php-s3-lite with dependencies
ext-curl Version *
ext-hash Version *
ext-simplexml Version *
ext-mbstring Version *