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