StorageBlob

Reference for the StorageBlob module: store binary file blobs in named buckets, split large files into chunks, and read and write them through pluggable vendor handlers with a built-in local filesystem handler.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

StorageBucketDatabase - look up and create the bucket a file belongs to.
StorageConfig - registry of vendor-specific save, load and delete handlers.
StorageFileData - immutable file id, data and metadata.
StorageFileDatabase - save, append, load and delete file blobs.
StorageFileMetaData - immutable metadata for a stored file.
StorageFormValidate - form-field validators for uploaded files and images.

StorageBucketDatabase

Look up the numeric id of a storage bucket by module and name, create it when needed, and read the bucket row that holds its vendor and storage type.

Functions

Get GetOrAdd GetRow GetRowById

Get

StorageBucketDatabase::Get(string $moduleName, string $bucketName): int

The id of the bucket for a module and bucket name.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.

Returns int The bucket id.

GetOrAdd

StorageBucketDatabase::GetOrAdd(string $moduleName, string $bucketName, ?string $optionalVendor = null, ?string $optionalStorageType = null, ?string $optionalVendorParamsJson = null): int

The id of the bucket for a module and bucket name, inserting the bucket first when it does not yet exist. Results are cached for the running process.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$optionalVendor`	`?string`	Vendor such as 'local' or 'aws'. Defaults to 'local' when null.
`$optionalStorageType`	`?string`	Storage type such as 'filesystem' or 's3'. Defaults to 'filesystem' when null.
`$optionalVendorParamsJson`	`?string`	JSON for vendor-specific parameters, or null.

Returns int The bucket id.

GetRow

StorageBucketDatabase::GetRow(string $moduleName, string $bucketName): stdClass

The bucket row for a module and bucket name.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.

Returns stdClass The bucket row, with StorageBucketID, StorageBucketModuleName, StorageBucketName, StorageBucketVendor, StorageBucketStorageType and StorageBucketVendorParams.

GetRowById

StorageBucketDatabase::GetRowById(int $bucketId): stdClass

The bucket row for a bucket id.

Name	Type	Description
`$bucketId`	`int`	The bucket id.

Returns stdClass The bucket row, with StorageBucketID, StorageBucketModuleName, StorageBucketName, StorageBucketVendor, StorageBucketStorageType and StorageBucketVendorParams.

StorageConfig

Registry for vendor-specific storage handlers. Modules register a save, load and delete callback for a vendor and storage type, keyed by vendor and type; the file database reads them back to perform operations.

Functions

GetHandlers Register

GetHandlers

StorageConfig::GetHandlers(string $vendorName, string $storageType): object

The registered handlers for a vendor and storage type. Throws when no handlers are registered for the key.

Name	Type	Description
`$vendorName`	`string`	Vendor identifier such as 'local' or 'aws'.
`$storageType`	`string`	Storage type such as 'filesystem' or 's3'.

Returns object An object with save, load and delete callables.

Register

StorageConfig::Register(string $vendorName, string $storageType, callable $save, callable $load, callable $delete): void

Name	Type	Description
`$vendorName`	`string`	Vendor identifier such as 'local' or 'aws'.
`$storageType`	`string`	Storage type such as 'filesystem' or 's3'.
`$save`	`callable`	Receives moduleName, bucketName, fileId, data, mimeType and extension; returns void.
`$load`	`callable`	Receives moduleName, bucketName, fileId and extension; returns the file contents as a string.
`$delete`	`callable`	Receives moduleName, bucketName, fileId and extension; returns void.

Returns void

StorageFileData

Immutable id, data and metadata for a stored file. Fields and constructor only.

Properties

Property	Type	Description
`$file->id`	`int`	The file id (readonly).
`$file->data`	`string`	The file contents (readonly).
`$file->metaData`	`StorageFileMetaData`	The file metadata (readonly).

__construct

new StorageFileData(int $id = 0, string $data = "", StorageFileMetaData $metaData = new StorageFileMetaData())

Create file data from an id, its contents and its metadata.

Name	Type	Description
`$id`	`int`	The file id.
`$data`	`string`	The file contents.
`$metaData`	`StorageFileMetaData`	The file metadata.

Returns StorageFileData

StorageFileDatabase

Save, append, load and delete file blobs in a bucket. Small files are held inline in the row; larger files are written through the bucket's vendor handler and can be split across chunk rows that share the first chunk's id.

Constants

Constant	Value	Description
`StorageFileDatabase::FILE_STATUS_WRITING`	`0`	The file is being written.
`StorageFileDatabase::FILE_STATUS_READY`	`1`	The file is written and readable.
`StorageFileDatabase::FILE_STATUS_DELETING`	`2`	The file is being deleted.
`StorageFileDatabase::FILE_STATUS_DELETED`	`3`	The file has been deleted.

Functions

Append BuildLocalPath Delete Extension ExtensionFromMimeType fromRow Load LoadData LoadDataOptional LoadOptional metadataFromRow Save SaveOptional

Append

StorageFileDatabase::Append(string $moduleName, string $bucketName, int $fileId, string &$data): void

Append a chunk of data to an existing file, attaching a new chunk to the file's first chunk.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file to append to.
`$data`	`string`	The chunk of data to append.

Returns void

BuildLocalPath

StorageFileDatabase::BuildLocalPath(string $moduleName, string $bucketName, int $fileId, string $extension = '', bool $createDirectories = false): string

Build the filesystem path for a file in local storage, optionally creating the directories. Used by the default local handlers and by callers that need the path.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	The file id.
`$extension`	`string`	The file extension, or empty for a directory path.
`$createDirectories`	`bool`	True to create the directories.

Returns string The absolute path to the file, or the directory when the extension is empty.

Delete

StorageFileDatabase::Delete(string $moduleName, string $bucketName, int $fileId): void

Delete a file and all of its chunks, marking them deleting, removing the vendor-stored data, then marking them deleted.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file to delete.

Returns void

Extension

StorageFileDatabase::Extension(string $moduleName, string $bucketName, int $fileId): string

The stored file extension for a file.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file.

Returns string The file extension.

ExtensionFromMimeType

StorageFileDatabase::ExtensionFromMimeType(string $mimeType): string

The file extension for a MIME type, defaulting to jpg for unrecognised types.

Name	Type	Description
`$mimeType`	`string`	The MIME type, such as image/jpeg or image/png.

Returns string The file extension, such as jpg or png.

fromRow

StorageFileDatabase::fromRow(stdClass $row, string &$data): StorageFileData

Build a StorageFileData from a file row and its assembled contents.

Name	Type	Description
`$row`	`stdClass`	A storage_file row.
`$data`	`string`	The assembled file contents.

Returns StorageFileData The file data.

Load

StorageFileDatabase::Load(string $moduleName, string $bucketName, int $fileId): StorageFileData

Load a whole file, joining every ready chunk in order. The file id can be any chunk of a multi-chunk file. Throws when no ready rows are found.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file to load.

Returns StorageFileData The file, with its contents and metadata.

LoadData

StorageFileDatabase::LoadData(string $moduleName, string $bucketName, int $fileId): string

Load a whole file and return just its contents instead of a metadata object.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file to load.

Returns string The file contents.

LoadDataOptional

StorageFileDatabase::LoadDataOptional(string $moduleName, string $bucketName, int|null $optionalFileId): string|null

Load and return a file's contents when a file id is given, or null when the id is null.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$optionalFileId`	`int\|null`	Any chunk id of the file to load, or null.

Returns string|null The file contents, or null.

LoadOptional

StorageFileDatabase::LoadOptional(string $moduleName, string $bucketName, int $fileId): StorageFileData|null

Load a whole file, returning null when a vendor load of a chunk fails. Throws when no ready rows are found.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$fileId`	`int`	Any chunk id of the file to load.

Returns StorageFileData|null The file, or null when a chunk could not be loaded.

metadataFromRow

StorageFileDatabase::metadataFromRow(stdClass $row): StorageFileMetaData

Build a StorageFileMetaData from a file row.

Name	Type	Description
`$row`	`stdClass`	A storage_file row.

Returns StorageFileMetaData The file metadata.

Save

StorageFileDatabase::Save(string $moduleName, string $bucketName, string &$data, string $mimeType = '', string $extension = ''): int

Save a file to storage and return its id. Small files are stored inline; larger files are written through the bucket's vendor handler.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$data`	`string`	The file contents.
`$mimeType`	`string`	The MIME type, or empty.
`$extension`	`string`	The file extension, or empty.

Returns int The id of the saved file.

SaveOptional

StorageFileDatabase::SaveOptional(string $moduleName, string $bucketName, string|null $optionalData): int|null

Save a file and return its id when data is given, or null when the data is null.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$bucketName`	`string`	The bucket name.
`$optionalData`	`string\|null`	The file contents, or null.

Returns int|null The id of the saved file, or null.

StorageFileMetaData

Immutable metadata for a stored file. Fields and constructor only.

Properties

Property	Type	Description
`$metaData->mimeType`	`string`	The file MIME type (readonly).
`$metaData->extension`	`string`	The file extension (readonly).
`$metaData->size`	`int`	The file size in bytes (readonly).
`$metaData->added`	`CalendarDateTimeData`	When the file was added (readonly).

__construct

new StorageFileMetaData(string $mimeType = "", string $extension = "", int $size = 0, CalendarDateTimeData $added = new CalendarDateTimeData())

Create file metadata from a MIME type, extension, size and added datetime.

Name	Type	Description
`$mimeType`	`string`	The file MIME type.
`$extension`	`string`	The file extension.
`$size`	`int`	The file size in bytes.
`$added`	`CalendarDateTimeData`	When the file was added.

Returns StorageFileMetaData

StorageFormValidate

ApiFormValidate-compatible validators for file and image form fields. Each method returns a callable that validates a JSON file submission with fileName, mimeType, base64Data and fileSizeBytes, returning the decoded object or an error message.

Functions

File Image

File

StorageFormValidate::File(int $maxSizeBytes = 10485760): callable

A validator callable for a file form field. Accepts any file type and validates the JSON structure and base64 data.

Name	Type	Description
`$maxSizeBytes`	`int`	Maximum file size in bytes, defaulting to 10MB.

Returns callable The validator callable.

Image

StorageFormValidate::Image(int $maxSizeBytes = 10485760): callable

A validator callable for an image form field. Accepts only image MIME types: image/jpeg, image/png, image/gif, image/webp and image/heic.

Name	Type	Description
`$maxSizeBytes`	`int`	Maximum file size in bytes, defaulting to 10MB.

Returns callable The validator callable.