Flysystem CHANGELOG 深度解读:从 3.0 到 3.35 的核心能力演进与源码印证

原创2026-10-13 13:22:181,899 阅读
文章标签:后端

Flysystem CHANGELOG 深度解读:从 3.0 到 3.35 的核心能力演进与源码印证

Flysystem 是 PHP 生态中广泛使用的文件存储抽象层(项目描述为 "Abstraction for local and remote filesystems"),通过统一的 FilesystemOperator 接口屏蔽本地磁盘、FTP/SFTP、AWS S3、Google Cloud Storage、MongoDB GridFS、WebDAV、ZipArchive 等底层存储差异。本文以 CHANGELOG.md 为骨架,梳理 Flysystem 从 3.0 重构到 3.35.2 的版本演进脉络,并对照 src/ 目录下的真实源码与测试,讲清每个重要版本条目背后的实现原理、涉及的新配置项及其默认值,帮助你在升级或选型时准确判断"哪个版本引入了哪项能力、该能力如何落地"。

一、为什么要读这份 CHANGELOG:版本史即能力史

Flysystem 采用 subsplit 多包发布模式:核心 API 位于 src/(League\Flysystem 命名空间),而 Local、FTP、SFTP、S3、GCS、WebDAV、ZipArchive、GridFS 等适配器各自独立成包(见 config.subsplit-publish.json)。因此 CHANGELOG 中大量条目以 [AwsS3V3]、[SFTP V3]、[Local]、[FTP] 等前缀标明改动所属模块,这既是各子包的发布记录,也是理解整个生态能力边界的索引。

主包 composer.json 要求 PHP ^8.0.2,核心仅依赖 league/flysystem-local 与 league/mime-type-detection,其余适配器均为可选依赖;这也解释了为什么 CHANGELOG 中适配器层的新特性总是以独立小版本推进。从 3.0 的接口大重构,到 3.35.2 的 ACL 优先级修正,每个条目都能在源码中找到对应实现——这正是把 CHANGELOG 读"厚"的价值所在。

二、2026 年最新特性:3.31.0 ~ 3.35.2

1. copy 时 ACL 配置优先于 visibility(3.35.2,#1905)

3.35.2 修正了 AwsS3V3 适配器在 copy 场景下 ACL 与 visibility 的优先级问题。对照 src/AwsS3V3/AwsS3V3Adapter.php 的 copy() 实现:它先尝试从 $config 读取显式 visibility,若未设置且 retain_visibility 默认开启,则读取源对象可见性;最终传给 S3 的 ACL 取值逻辑是 $options['params']['ACL'] ?? $this->visibility->visibilityToAcl($visibility ?: 'private')——即显式配置的 ACL 参数拥有最高优先级,只有未显式指定 ACL 时才回退到 visibility 推导。这延续了 2.1.0 时代"Allow the ACL config option to take precedence over the visibility key"的设计(见下方 2.x 部分),使 copy 行为与 write 一致。

2. Filesystem 层防御空 mime-type(3.35.0,#1901)

该版本在 Filesystem 门面层对 mime-type 返回 null 的场景做了防御。看 src/Filesystem.php 的 mimeType():适配器返回的 FileAttributes 中若 mimeType() === null,直接抛出 UnableToRetrieveMetadata::mimeType($path),避免上层拿到 null 引发类型错误。这也与 3.22.0 引入的"Resolve to 'inconclusive' mimetype instead of causing a type error"形成闭环——适配器层尽量返回可推断的 mime-type,Filesystem 层则兜底拦截空值。

3. 可关闭相对路径解析(3.34.0)

3.34.0 为核心 Filesystem 增加"在配置的根路径内禁用相对路径解析"的能力。实现位于 src/WhitespacePathNormalizer.php:构造器接受 bool $allowRelativePathTraversal = true,当传入 false 时,路径中任何 .. 段都会直接抛出 PathTraversalDetected,而不是被折叠;同时保留对 \p{C}+ 控制字符的 CorruptedPathDetected 检查。Filesystem 通过配置键 allow_relative_path_traversal 透传该开关(见 src/Filesystem.php),适合对用户输入路径做严格白名单校验的场景。

4. SFTP V3 多指纹支持(3.33.0,#1893)

SftpConnectionProvider 的 hostFingerprint 参数从"单个指纹字符串"扩展为"字符串或字符串数组"。对照 src/PhpseclibV3/SftpConnectionProvider.php:checkFingerprint() 先通过 getServerPublicHostKey() 取回服务端公钥并计算指纹,再与期望指纹列表逐一 strcasecmp 比对,全部不匹配才抛 UnableToEstablishAuthenticityOfHost。多指纹支持意味着同一主机轮换密钥期间可同时配置新旧两个指纹,降低运维切换时的连接失败率。

5. S3 SSE-C 元数据读取与 AsyncAwsS3 V3(3.32.0、3.31.0)

3.32.0 让 AwsS3V3 在获取文件元数据(HeadObject)时允许携带 SSE-C 相关选项;对照 fetchFileMetadata() 中的 $this->client->getCommand('HeadObject', $options + $this->options),适配器构造器传入的全局 $options 会被合并进 HeadObject 请求。SSE-C 选项(SSECustomerAlgorithm、SSECustomerKey、SSECustomerKeyMD5 等)早已列入 AVAILABLE_OPTIONS。3.31.0 则是让 AsyncAwsS3 适配器支持 async-aws 的 V3 依赖版本,属于依赖生态跟进。

三、2024–2025:稳定性修复与连接生命周期管理(3.25 ~ 3.30)

1. Local 适配器清除 last error(3.30.2,#1883)

<a href="https://link.gitcode.com/i/1f5c189abe1b0f51eac0c5be2fbb0a6e" target="_blank">Local] Clear last error for rename and copy operations 修复了 @rename / @copy 失败后 error_get_last() 仍携带旧错误信息导致异常描述失真的问题。对照 [src/Local/LocalFilesystemAdapter.php 的 move() / copy(),两者在执行 @rename / @copy 前都会先调用 error_clear_last(),失败时再从 error_get_last() 取真实原因写入 UnableToMoveFile / UnableToCopyFile。

2. 目录名为 "0" 的列表修复(3.30.1)

该修复确保"名为 0 的目录"不会被错误地当成空路径而跳过过滤。这类问题在文件系统抽象层很常见——空字符串与 "0" 的 falsy 差异,正是适配器与核心层路径规范化时容易踩的坑,本次统一修正了列表目录时的过滤逻辑。

3. 3.30.0 多模块增强

  • <a href="https://link.gitcode.com/i/f778eb428c36cf212dac67114f2dbb3f" target="_blank">MongoDB] Allow v2:GridFS 适配器(见 [src/GridFS/GridFSAdapter.php)支持 mongodb 驱动 v2;
  • [AsyncAWS] Encode/decode object identifiers:对象标识的编解码处理;
  • <a href="https://link.gitcode.com/i/7f1c906ef8970327f5e585fa4f899c35" target="_blank">GoogleCloudStorage] Add option to stream responses:GCS 适配器构造器新增 streamReads 选项(默认 false),按需流式读取响应(见 [src/GoogleCloudStorage/GoogleCloudStorageAdapter.php);
  • <a href="https://link.gitcode.com/i/a1721424ebff6438a172414cdbd9335e" target="_blank">Local] Clear stat cache consistently:在 fileExists / directoryExists / fileSize 等元数据读取前统一 clearstatcache()(见 [LocalFilesystemAdapter),避免 PHP 进程内 stat 缓存造成的结果陈旧;
  • [SFTP] Add option to disconnect connections on destruction:SFTP 连接在对象析构时主动断开;
  • [WebDAV] Deal with 405 case:创建已存在的目录时,对 WebDAV 返回 405 的情况做兼容处理。

4. SFTP 连通性 ping 改为 opt-in(3.26.0)

早期 SFTP 适配器每次复用连接都会执行连通性检测(ping),3.26.0 将其改为可选特性以降低往返开销。对照 src/PhpseclibV3/SimpleConnectivityChecker.php 与 FixatedConnectivityChecker,连通性检查器可注入 SftpConnectionProvider(构造参数 ?ConnectivityChecker $connectivityChecker = null),默认仅在不满足条件时重连。同版本还新增了 AWS S3 的 add_content_md5 选项(#1774,已被列入 MUP_AVAILABLE_OPTIONS)与 SSE-C 选项(#1773),以及 3.27.0 对 MetadataDirective 的优雅处理(copy 时默认 'COPY',见 copy())。

5. 主动断开连接与动态挂载(3.25.0)

  • FTP 与 SFTP V3 适配器新增 disconnect() 方法,允许在长任务中主动释放连接。FTP 侧实现在 src/Ftp/FtpAdapter.php(@ftp_close 后置空连接句柄,且在 __destruct 中自动调用);SFTP 侧实现在 SftpConnectionProvider::disconnect()(断开并置空 $connection)。
  • MountManager 新增 dangerouslyMountFilesystems(string $key, FilesystemOperator $filesystem),作为"创建后追加挂载"的逃生舱口——注释明确提示常规用法应避免动态挂载(见 src/MountManager.php)。

6. GridFS 适配器正式加入(3.28.0)

3.28.0 由 @GromNaN 贡献了 MongoDB GridFS 适配器(src/GridFS/GridFSAdapter.php)。实现要点:文件内容存储于 MongoDB GridFS 的 chunk,目录以"以斜杠结尾的空文件"作为标记(flysystem_directory 元数据);listContents 使用聚合管道按 filename + uploadDate 排序取每个文件的最新修订(见 listContents());同版本还修复了 FTP 适配器在 PHP 8.3 下的目录列表问题(by @lanz1)。

四、2023:copy/move 语义的精细化与装饰器抽象(3.18 ~ 3.23)

1. inconclusive mime-type 可配置(3.23.0)

3.23.0 修复了"上游回归"(由不可判定的 mime-type 解析引起),并让 Local 适配器把该行为做成配置项。对照 LocalFilesystemAdapter 构造器:新增 bool $useInconclusiveMimeTypeFallback = false,透传给 FallbackMimeTypeDetector,决定 mime-type 推断不确定时是否回退到扩展名查找。

2. lazy root creation 防重复建目录(3.22.0)

<a href="https://link.gitcode.com/i/a42bf70d157af40cb74ab78590c225d3" target="_blank">Local] Prevent double directory creation with lazy root creation:开启懒创建后,根目录不再于构造时立即创建,而是在首次写/复制/移动等变更操作时才创建。源码中用 $rootLocationIsSetup 布尔位保证幂等(见 [ensureRootDirectoryExists()),lazyRootCreation 构造参数默认 false(行为与旧版一致,见 composer.json 依赖 对应的 Local 包)。

3. MountManager::extend 与 DecoratedAdapter(3.22.0)

  • MountManager::extend(array $filesystems, array $config = <a href="https://link.gitcode.com/i/13815d77e24791de28f0f5590195b0a0" target="_blank">]):以不可变方式扩展挂载点——基于 clone $this 生成新实例并追加挂载,原实例不受影响(见 [src/MountManager.php);
  • 新增抽象基类 src/DecoratedAdapter.php:代理 FilesystemAdapter 的全部方法,让开发者只需覆盖关心的行为即可"装饰"任意适配器(by @jnoordsij)。后续的 ReadOnly、PathPrefixing 等装饰器家族均基于此思路。

4. 同路径 copy/move 的策略化处理(3.18.0,#1715)

3.18.0 引入配置项 copy_destination_same_as_source / move_destination_same_as_source(见 src/Config.php),取值由 ResolveIdenticalPathConflict 定义三种策略:

策略 值 行为
TRY(默认) 'try' 交由底层适配器自行处理
IGNORE 'ignore' 静默跳过,视为成功(no-op)
FAIL 'fail' 抛出 UnableToCopyFile / UnableToMoveFile 的 same-path 异常

实现见 Filesystem::copy() / move():规范化后若 $from === $to,按策略分支处理。

5. 可见性保留(retain_visibility)(3.19.0)

3.19.0 是 copy/move 语义的里程碑:新增配置键 retain_visibility(默认 true,见 src/Config.php),并让各适配器在 copy/move 时遵循"保留源可见性"约定。核心逻辑在 Filesystem::resolveConfigForMoveAndCopy():默认保留可见性时,若调用方未显式传 visibility,则从默认配置中剔除 visibility 设置,避免"默认可见性"污染目标对象;显式传入的 visibility 依然生效。同版本还让 InMemory 与 Local 适配器支持了 move/copy 时的可见性变更(Local 侧见 copy() 的 retain_visibility 读取与 setVisibility 调用)。3.21.0(#1730)进一步修正 Local 在 copy 时与其它适配器保持一致地保留可见性。

五、2022:3.0 大重构与 URL 生成 / checksum 能力矩阵(3.0 ~ 3.17)

1. 3.0.0:读取接口细分化

3.0.0 把笼统的 has() 拆分为三兄弟:FilesystemReader::fileExists、directoryExists、has(has 等于两者之或,见 src/FilesystemReader.php 与 Filesystem::has()),适配器层同步新增 FilesystemAdapter::fileExists / directoryExists。这也是从 2.x 升级到 3.x 时适配器接口最显著的破坏性变化之一。

2. 列表 API 的迭代器化

3.0 的 listContents 返回 iterable 并由 DirectoryListing 包装(src/DirectoryListing.php),支持 filter()、map()、sortByPath()、toArray() 等链式操作;2.2.0 引入的 sortByPath 让列表可按路径排序(见 sortByPath())。

3. 公开 URL / 临时 URL / checksum 能力矩阵(3.6.0 ~ 3.10.0)

这一系列版本为 Filesystem 与各适配器补齐了三大高级能力:

  • publicUrl(3.6.0):Filesystem::publicUrl() 优先使用注入的 PublicUrlGenerator,否则回退到适配器自身实现(见 Filesystem::resolvePublicUrlGenerator());AWS S3 侧直接调用 SDK 的 getObjectUrl(AwsS3V3Adapter::publicUrl);
  • checksum(3.7.0):基于 src/ChecksumProvider.php 接口;适配器不实现时,Filesystem 回退到流式计算(src/CalculateChecksumFromStream.php 的 hash_update_stream 方案,默认算法 md5);AWS S3 的 checksum_algo 支持 etag(取 ETag 并去引号,见 AwsS3V3Adapter::checksum),且 3.8.0 引入 ChecksumAlgoIsNotSupported 异常,Filesystem::checksum() 捕获后自动降级为流式计算(Filesystem.php);
  • temporaryUrl(3.10.0):基于 src/UrlGeneration/TemporaryUrlGenerator.php;AWS S3 使用 createPresignedRequest 生成预签名 URL,支持 get_object_options 与 presigned_request_options 两个配置项(见 AwsS3V3Adapter::temporaryUrl)。3.10.1 补齐了 Filesystem 构造器中临时 URL 生成器的注入参数,3.10.2 修复了"temporary URL 必须由适配器暴露"的问题,3.10.3 处理了无 message 的 checksum 错误(#1590)。

4. URL 生成策略家族(3.9.0、3.12.0)

  • ChainedPublicUrlGenerator(3.12.0):src/UrlGeneration/ChainedPublicUrlGenerator.php 按顺序尝试多个生成器,捕获 UnableToGeneratePublicUrl 后继续下一个,全部失败才抛出异常——适合多 CDN 兜底场景;
  • ShardedPrefixPublicUrlGenerator(3.9.0):src/UrlGeneration/ShardedPrefixPublicUrlGenerator.php 用 crc32($path) % count 把路径稳定散列到一组前缀上,实现 URL 分片分发;要求至少一个前缀,否则抛 InvalidArgumentException。Filesystem 的 public_url 配置传数组时自动选用分片策略、传字符串时选用 PrefixPublicUrlGenerator(见 resolvePublicUrlGenerator())。

5. GCS 的 uniform bucket-level access(3.11.0)

<a href="https://link.gitcode.com/i/9b44c87b78b1776d4d035427dff296d1" target="_blank">GoogleCloudStorage] UniformBucketLevelAccessVisibility([src/GoogleCloudStorage/UniformBucketLevelAccessVisibility.php)让 GCS 适配器支持启用了 uniform bucket-level access 的存储桶——此类桶禁用对象级 ACL,可见性交由桶策略统一管理。

6. 装饰器与内存注册表三件套(3.3.0)

3.3.0 一次性引入三个实用组件(均为社区贡献):

  • StaticInMemoryAdapterRegistry(by @kbond):src/InMemory/StaticInMemoryAdapterRegistry.php 提供静态注册表,get($name) 惰性创建并复用 InMemory 适配器,deleteAllFilesystems() 用于测试隔离;
  • ReadOnlyFilesystemAdapter(by @kbond):src/ReadOnly/ReadOnlyFilesystemAdapter.php 继承 DecoratedAdapter,所有写操作直接抛对应 UnableTo* 异常(如 UnableToWriteFile),读、checksum、publicUrl、temporaryUrl 正常透传;
  • PathPrefixedAdapter(by @shyim):src/PathPrefixing/PathPrefixedAdapter.php 为任意适配器加上路径前缀,所有方法调用前 prefixPath()、列表结果 stripPrefix(),要求前缀非空。

7. FTP 列表选项与异常统一(3.4.0)

3.4.0 新增 FTP 配置项 useRawListOptions(null|false|true,见 src/Ftp/FtpConnectionOptions.php)。对照 FtpAdapter::isServerSupportingListOptions():null(默认)时自动探测——通过 SYST 判断,FileZilla 与 L8 服务器禁用 raw list 选项(对应 #1553 的修复),其余服务器启用。同版本还引入 UnableToListContents 异常(src/UnableToListContents.php),Filesystem::listContents 的 pipeListing() 会捕获底层异常并包装为它(见 src/Filesystem.php),统一内容列表失败的表征。

8. AwsS3V3 的三大可配置面(3.2.0)

3.2.0 让 AwsS3V3 适配器更加可定制,对应构造器参数(见 src/AwsS3V3/AwsS3V3Adapter.php):

构造参数 默认值 说明
$options [] 全局选项,合并进所有 S3 请求(含 HeadObject / ListObjectsV2)
$forwardedOptions AVAILABLE_OPTIONS(24 项,含 ACL、CacheControl、ContentType、StorageClass、Tagging、SSECustomer*、ChecksumAlgorithm 等) 写操作时从 Config 透传给 SDK 的参数白名单
$multipartUploadOptions MUP_AVAILABLE_OPTIONS(add_content_md5、before_upload、concurrency、mup_threshold、params、part_size) 分片上传参数
$metadataFields Metadata、StorageClass、ETag、VersionId 从 HeadObject 结果提取的 extraMetadata 字段

同版本的修复还包括:目录删除时删顶层目录(ZipArchive)、ChecksumAlgorithm / ContentMD5 加入转发选项、SFTP V3 最低依赖版本修正。

9. Local 懒建根目录(3.1.0)

3.1.0 为 Local 适配器增加"仅在首次变更操作时创建根目录"的选项(即上文 3.22.0 深化前的雏形,构造参数 lazyRootCreation,见 LocalFilesystemAdapter)。

10. 3.0.x 系列的关键修复沉淀

  • ListObjectsV2(3.0.21 / 3.0.22):AWS S3 从 ListObjects 全面切换到 ListObjectsV2,并获得分页器支持(retrievePaginatedListing());3.0.22 同时为异常补充了原因信息;
  • 异常原因完备化(3.0.23):所有适配器补齐缺失的上一级异常 message;
  • 目录存在性检测去重(3.0.10):检测 S3 目录存在性时 MaxKeys => 1 限制结果集以提升性能,且不返回顶层目录自身(3.0.13);
  • ACL 直接选项(3.0.9):支持将 ACL 作为直接选项而非依赖 visibility;
  • ContentType 回写(3.0.8):配置了 mime-type 时写入时设置 ContentType(同 2.4.3);
  • GCS 元数据(3.0.15):允许设置上传 metadata 与 contentType;
  • InMemory last-updated(3.0.14,#1438):允许设置最后更新时间;
  • SFTP 相关(3.0.14、3.0.16、3.0.17、3.0.18、3.0.19):SFTP V3 可配置 preferred algorithms(#1440);Local 在 mime-type 不确定时回退扩展名查找;SFTP v2/v3 避免公钥未取到时类型错误(#1446);SFTP V3 修复重试(#1451);FTP 连接根解析错误转异常(#1460);
  • 路径规范化(3.0.1、3.0.20、3.0.6):Windows 分隔符转 unix 风格(#1398、2.0.7);${var} 插值弃用修复(#1470);核心统一使用 directory_visibility 作为目录可见性键,属性类统一裁剪斜杠。

11. 2.x 时代的两处重要伏笔

CHANGELOG 尾部保留的 2.x 记录对理解 3.x 行为很有价值:

  • SFTP V3 适配器官方发布(2.4.0):基于 phpseclib v3 的 SFTP 适配器正式发布,即 src/PhpseclibV3;
  • ACL 优先于 visibility(2.1.0):AwsS3V3 允许 ACL 配置优先于 visibility 键——这正是 3.35.2(#1905)在 copy 场景下重申的语义;
  • 其它如 2.0.0 的全可见性参数 string 化、DirectoryAttributes 的 extraMetadata(2.1.0)、DirectoryListing 迭代排序(2.2.2)等,均为 3.x 的当前行为奠定了基调。

六、给升级者与使用者的实践建议

结合 CHANGELOG 与源码,整理几条可落地的选型与升级建议:

  1. 从 2.x 升 3.x 的重点:接口层面重点核对 fileExists / directoryExists / has 的三分法、listContents 的 iterable 返回、FilesystemAdapter 的 Config 传参签名(move / copy / createDirectory / 各元数据方法均收 Config),以及 directory_visibility 与 visibility 的分工(核心统一约定,见 3.0.6);
  2. S3 场景:若需细粒度控制上传参数,直接使用 3.2.0+ 的 forwardedOptions / multipartUploadOptions / metadataFields;SSE-C 与 add_content_md5 需 3.26.0+;copy 的 ACL 优先级语义以 3.35.2 为准;
  3. SFTP 场景:多指纹(hostFingerprint 数组)需 3.33.0+;PuTTY 风格私钥、禁用 stat cache、preferred algorithms 需 3.13.0 / 3.14.0 / 3.0.14;主动 disconnect() 需 3.25.0;
  4. Local 场景:生产环境建议显式设置 lazyRootCreation、useInconclusiveMimeTypeFallback,并利用 retain_visibility / 同路径策略(3.18.0 / 3.19.0)统一 copy/move 语义;
  5. 统一异常体验:所有列表失败最终包装为 UnableToListContents(3.4.0+),checksum 不可用时会自动降级为流式计算(3.8.0+),这让上层代码可以用统一的 catch 模式处理跨适配器错误。

本仓库为只读镜像,如需查看上述任一能力的完整实现,可直接在 src/ 目录下按适配器阅读对应源码与测试(如 FilesystemTest.php、MountManagerTest.php、各 *AdapterTest.php),并结合本 CHANGELOG 定位每个条目对应的发布版本与配置默认值。

登录后查看全文
flysystem