Download the PHP package vergil-lai/laravel-oss-filesystem without Composer

Laravel OSS Filesystem

基于 alibabacloud/oss-v2 的 Laravel 阿里云 OSS filesystem 驱动。

Laravel 集成基于独立的 vergil-lai/oss-flysystem 包；Laravel 用户只需安装当前包，Composer 会自动安装底层依赖。

要求

• PHP 8.2+
• Laravel 12/13

安装

配置

在应用的 config/filesystems.php 中，将以下配置加入 disks。本包会先加载内部默认值，再用这里的 disks.oss 配置覆盖默认值。

region 和 bucket 是通常需要配置的参数。凭证可以使用 access_key_id、access_key_secret 和可选的 security_token，也可以程序化注入 credentials_provider。其余参数按实际环境选填。

OSS_USE_CNAME=false 时，SDK 使用 OSS_ENDPOINT（留空则根据 OSS_REGION 生成），请求地址采用 Bucket.Endpoint 形式。OSS_USE_CNAME=true 且配置了 OSS_DOMAIN 时，SDK 改用 OSS_DOMAIN 进行读写和临时 URL 签名，并且不再把 Bucket 名添加到主机名前。为兼容原有配置，未设置 OSS_DOMAIN 时仍使用 OSS_ENDPOINT 作为 CNAME Endpoint。

OSS_DOMAIN 必须是在 OSS 中绑定到当前 Bucket 的自定义 CNAME 域名。若只是希望 Storage::url() 使用 CDN 或其他公开访问地址，而 SDK 读写和临时 URL 继续使用 OSS Endpoint，请保持 OSS_USE_CNAME=false，并使用 OSS_URL 配置公开 URL。

和旧版 aliyuncs/oss-sdk-php 的配置相比，这里有几个差异：

• prefix 在 Laravel/Flysystem 里对应 root
• request_proxy 对应 SDK v2 的 proxy_host
• timeout 对应 SDK v2 的 read_write_timeout
• use_ssl 改为 SDK v2 的反向语义 disable_ssl
• signatureVersion 对应 signature_version，支持 v4 和 v1，默认使用 v4
• 不提供旧包的 macros 和 options

自定义凭证提供器和重试器

credentials_provider 接受 SDK 的 CredentialsProvider 实现，设置后优先于 access_key_id、access_key_secret 和 security_token。retryer 接受 SDK 的 RetryerInterface 实现。

这两个参数是对象，不建议直接写进 config/filesystems.php，否则可能影响 Laravel 的 config:cache。可以在应用的 Service Provider 中、首次解析 OSS disk 前注入：

如果没有设置 retryer，SDK 会使用默认的 StandardRetryer。仅需调整最大重试次数时，直接配置 retry_max_attempts 即可。

自定义 HTTP 客户端

底层 SDK 的 AlibabaCloud\Oss\V2\Client 第二个参数支持传入 Guzzle 选项。你可以通过 client_options 透传这些配置：

本包不会自动替换底层 HTTP handler。如有需要，可以通过 client_options.handler 自行配置；该值会被原样传给 OSS SDK。

handler 通常是对象，不建议直接写入 config/filesystems.php。可以在应用的 Service Provider 中、首次解析 OSS disk 前注入：

注入原生 SDK Client

client 接受 AlibabaCloud\Oss\V2\Client 实例。设置后，本包不会再根据数组配置创建客户端：

自定义 Client 同样不建议直接写入配置文件，应在首次解析 OSS disk 前程序化注入。公开 URL 仍由 disk 的 url、endpoint、region 和 endpoint 模式配置生成。

支持的操作

• put、get、流式读写
• exists、文件大小、MIME 类型、最后修改时间、可见性
• 递归列出文件和删除目录
• 复制、移动、删除
• 通过 url 生成公开访问地址
• 通过 temporaryUrl 生成临时 GET 访问地址
• 通过 temporaryUploadUrl 生成临时 PUT 上传地址
• 上传时支持 visibility、mimetype、cache_control、content_disposition、content_encoding、metadata、forbid_overwrite、storage_class 等常见选项
• checksum 默认使用 OSS ETag，不会为了计算校验值下载完整对象

使用

详细请查看官方文档