SoFinder S3 adapter

这个可选 Bundle 通过 AWS SDK for PHP v3，为 SoFinder 加入 s3 存储 adapter。

bash

composer require sohophp/sofinder-s3:^0.1@beta

在 config/bundles.php 将 SoFinderS3Bundle 注册于 SoFinderBundle 之后：

php

return [
    SohoPHP\SoFinder\SoFinderBundle::class => ['all' => true],
    SohoPHP\SoFinderS3\SoFinderS3Bundle::class => ['all' => true],
];

接着配置资源：

yaml

so_finder:
  resources:
    RemoteAssets:
      adapter: s3
      root: media
      delivery_mode: proxy
      public_url: ''
      options:
        bucket: '%env(SOFINDER_S3_BUCKET)%'
        region: '%env(SOFINDER_S3_REGION)%'
        endpoint: '%env(SOFINDER_S3_ENDPOINT)%'
        use_path_style_endpoint: false
        health_timeout_seconds: 5

AWS S3 请省略 endpoint。Cloudflare R2 使用 region: auto 与帐户 endpoint。MinIO 通常需要 use_path_style_endpoint: true；除非在受信任的开发网络明确配置 allow_insecure_endpoint: true，否则 HTTP 会遭拒绝。配置 root: / 可公开 bucket 根目录。health_timeout_seconds 将 /health 的 Bucket 探测及 S3 连接／请求超时限制在 0.1–30 秒，默认 5 秒。

除非通过环境变数支持的配置同时提供 access_key_id 与 secret_access_key，否则会使用 AWS 默认凭证 provider chain。切勿提交凭证。私有资源应使用代理传递。公开资源可将 public_url 设置为与配置 root 相对应的 CDN 或 bucket URL；配置 delivery_mode: public 后，浏览器项目、复制链接及编辑器选取结果会使用该 URL。Adapter 会接上逻辑对象路径，因此 root 为 component-images 的资源应使用 https://cdn.example.com/component-images 之类的基底 URL。必须由 SoFinder 验证内容 endpoint 保护的私有对象，请维持 delivery_mode: proxy 与 public_url: ''。

从 SoFinder 的角度来看，S3 删除是永久的。需要恢复能力时，请启用 bucket versioning 或供应商的 lifecycle 保护。

供应商状态

供应商	状态	说明
AWS S3	支持	省略自订 endpoint。
Cloudflare R2	支持	使用帐户 endpoint 与 `region: auto`。
MinIO	经 CI 验证	使用 path-style URL；只有受信任的开发网络才允许 HTTP。
Backblaze B2	经契约验证	使用区域 HTTPS endpoint；会自动停用有条件的 Put Object。
DigitalOcean Spaces、Wasabi	兼容候选	使用其 S3 endpoint；在您的环境通过契约测试前，视为尚未验证。

Backblaze B2 smoke test

可直接从此 repository 测试 Backblaze B2，不需要 Winstar。请使用既有的非正式环境 bucket 与手动建立的 B2 application key；key ID 是 access key ID，application key 是 secret access key。切勿使用 master application key，也不要将任何值提交到 repository。

安全模板只需复制一次，填写 .env.local，再执行单一外部测试。Symfony Dotenv 会自动为测试程序加载此文件；Git 会忽略 .env.local，绝不可提交：

bash

cd packages/sofinder-s3
cp .env.example .env.local
# 在 .env.local 填入 B2 endpoint、region、测试 bucket 与 application key。
vendor/bin/phpunit --filter S3ProviderSmokeTest

测试不会建立 bucket。它只会在随机的 <SOFINDER_PROVIDER_PREFIX>/provider-smoke/<random> 前缀下写入，检查 Unicode stream CRUD、列表、复制、移动、用量、永久删除与 adapter 审计，最后尽力清理。请将 SOFINDER_PROVIDER_PREFIX 设置为受限前缀 application key 所允许的同一前缀；只有 bucket-wide key 才能留空。B2 不要配置 SOFINDER_PROVIDER_USE_PATH_STYLE_ENDPOINT。若 application key 限制于单一 bucket，请启用 B2 的 list-all-bucket-names 权限以兼容 SDK。B2 bucket 一律启用 versioning，因此最终清理只会列出随机前缀中的版本，再依 version ID 删除。Application key 必须拥有 list／read／write／delete 权限；请配置适当的 lifecycle 规则，作为保留版本的备用清理方式。

Backblaze B2 未实现 Put Object 的 If-None-Match。Adapter 会辨识 *.backblazeb2.com endpoint，在执行一般存在性检查后省略该条件 header。AWS S3 与 MinIO 仍保留原子化的条件建立。其他有相同 API 限制的兼容供应商，可以明确配置 options.conditional_writes: false；停用后会引入一个很小的并行建立竞争时间窗。

SoFinder S3 adapter ​

供应商状态 ​

Backblaze B2 smoke test ​

SoFinder S3 adapter

供应商状态

Backblaze B2 smoke test