Storage

Two stores, one path setting

The two stores are separate modules that a site can include independently. Both are configured through the Storage config group, whose one required setting is where bytes are written on disk:

Config::Provide('Storage', [
    'STORAGE_PATH' => '/var/www/storage',
]);

StorageBlob: files by id

StorageBlob is binary file storage. It writes the file bytes to disk under STORAGE_PATH and keeps a row per file (the storage_file table) holding its metadata: module, bucket, mime type, extension and size. A stored file is addressed by its file id, a database primary key. Use StorageBlob for uploaded files and anything where you have raw bytes plus metadata to track: an image, a document, a thumbnail.

Blob storage supports pluggable vendors. A local filesystem handler is always present; other vendors can be registered to write the bytes elsewhere.

StorageObject: content by hash

StorageObject is a content-addressed, immutable object store. An object is saved as a tree of hash-addressed nodes: structs, arrays and value leaves. Each node is addressed by the hash of its content, so identical content is stored once and shared across objects and across saves. A per-save header row records the object's module, type and root hash; the object itself is fetched by that hash.

The store is integrity-only: it guarantees the hash tree is intact and knows nothing about application schemas. Schema and type knowledge live in a per-type codec at the edge. Use StorageObject for structured, typed content that changes little between saves and benefits from deduplication, such as a versioned document or scene.

Choosing between them

• Uploaded file bytes plus metadata, addressed by a file id: StorageBlob.
• Structured typed content, deduplicated and addressed by content hash: StorageObject.

A single feature can use both. A saved scene can be a StorageObject referenced by its hash, while its thumbnail is a StorageBlob file referenced by its file id.

Next: Background work: queues and cron.