Download the PHP package vortos/vortos-object-store without Composer

Vortos Object Store

S3-compatible object storage with Cloudflare R2 defaults, transactional outbox, direct-to-cloud uploads, and server-side multipart transfers.

Design

• User file uploads go directly to R2/S3 via presigned URLs. The backend issues a signed URL, stores the object key, and promotes from tmp/ to a permanent key after validation.
• Mutations (put, delete, copy, move) are queued through the outbox so file adoption is atomic with domain DB changes.
• tmp/ keys are cleaned up by a bucket lifecycle rule managed via vortos:object-store:lifecycle.
• Integration tests run against real R2/S3 credentials. LocalStack is not part of this package.

Configuration

Service Guarantees

The injected interface defines the delivery guarantee. There is no hidden config switch.

Direct Upload Flow

1. Call DirectUploadManagerInterface::createUploadIntent() for a tmp/... key.
2. The client uploads directly to R2/S3 using the returned signed URL.
3. Persist domain data with the temporary key.
4. After validation, call promote() — copies to a permanent key, optionally deletes the source.

Server-Side Multipart

ServerSideMultipartUploadManagerInterface handles backend-owned transfers: imports, exports, migrations, CLI jobs. It validates S3 part limits, keeps memory bounded by part size, retries transient part failures, and aborts failed uploads. Do not use it for browser uploads — use the direct-to-cloud flow above.

Lifecycle Provisioning

Lifecycle rules are never applied during HTTP requests, workers, or container boot.

apply brings the bucket to the declared rule set and is idempotent: when nothing drifted it writes nothing, so it is safe to run on every deploy. plan exits 2 when there are changes, 0 when up to date.

Declaring rules

• Ownership is by rule-ID namespace (managedRuleIdPrefix(), default vortos-). Every rule whose ID starts with it is managed: a managed rule removed from config is removed from the bucket on the next apply. Rules outside the namespace (console-made rules, the provider's default multipart-abort rule) are never touched. Declaring a rule outside the namespace fails the container build.
• The temporary-upload expiry rule (rule_id, default vortos-object-store-expire-temporary-uploads) is built from bucket.temporary_key_prefix and orphan_ttl_seconds while manageTemporaryUploads(true). With it off, that ID is treated as unowned and left in place.
• Every rule needs a non-empty prefix. A bucket-wide rule would also act on temporary uploads and public assets.
• Rules are compared as models, not raw arrays, so a provider's key order or legacy Prefix field does not read as drift. A managed rule the model cannot represent exactly (date expiry, tag filter, archive class) is rewritten to the declared shape.
• Declarations are validated when config loads (even with lifecycle disabled), and again at plan against provider capabilities.

Storage-class transitions

Only ObjectStorageClass::InfrequentAccess (STANDARD_IA) is supported. Archive tiers are deliberately excluded: their objects cannot be read through a presigned GET until restored.

Do not transition prefixes whose objects are deleted within 30 days or read constantly (public assets, support attachments): the minimum duration and retrieval fees cost more than Standard.

Managing lifecycle needs write access to the bucket configuration — on R2 an API token with bucket-level Workers R2 Storage Write. Check the token before making apply part of a deploy.

Commands