Events

The FileStorage behavior dispatches events while a file row is saved or deleted. The subject of every event is the file storage table. Register listeners on the global event manager:

use Cake\Event\EventInterface;
use Cake\Event\EventManager;

EventManager::instance()->on(
    'FileStorage.afterStoringFile',
    function (EventInterface $event): void {
        $entity = $event->getData('entity');
        $file = $event->getData('file');
        // ...
    },
);

Saving

In the order they fire for an upload:

Event	Data	When
FileStorage.beforeSave	entity, storageAdapter	Before the row is written.
FileStorage.beforeStoringFile	entity, file	Before the file is written to the adapter.
FileStorage.afterStoringFile	entity, file	After the file was written.
FileStorage.blobReused	entity, file	Instead of the two storing events, when a deduplicated upload found its content already stored. Nothing is written then.
FileStorage.beforeFileProcessing	entity, file	Before variants are generated.
FileStorage.afterFileProcessing	entity, file	After variants were generated.
FileStorage.afterSave	entity, storageAdapter	After the row holds its final path and variants.

entity is the file_storage row, file the library's file object, storageAdapter the Flysystem adapter the row is stored on.

The two processing events also fire when variants are regenerated by the variant command or its queue task.

Listeners on the storing events and deduplication

A listener on FileStorage.afterStoringFile, a virus scan for example, does not run for an upload that reuses stored content. Listen on FileStorage.blobReused as well if it has to see every upload.

Attaching by hash

Event	Data	When
FileStorage.blobAttached	entity	After BlobAttacher::attach() created a row for stored content. None of the saving events fire for such a row.

Deleting

Event	Data	When
FileStorage.afterDelete	entity	After the row was deleted, before its files are removed.

Existing-file conversion

FileStorage.blobConverted fires once per committed conversion by file_storage deduplicate. Its subject is the file storage table. Data:

Key	Value
id	Converted row id.
oldPath	Previous path, whose file is kept.
path	Verified blob path now stored on the row.
adapter	Row's storage adapter name.
hash	SHA-256 computed from source bytes.

The event fires after the database commit. Listener exceptions are reported as warnings; the row stays converted. Hash-only and dry runs do not fire it.

Stored-file registration

FileStorage.blobImported fires once per committed call to BlobImporter::import(). Its subject is the file storage table. Data:

Key	Value
adapter	Source and blob storage adapter name.
hash	Computed or trusted SHA-256 hash.
path	Committed blob path.
sourcePath	Original source object path.
reused	true when existing destination content was reused; false when copied.

The event fires after commit and optional source deletion. Listener exceptions are logged as warnings; the blob stays registered.

FileStorage.uploadCompleted

Dispatched after a resumable session becomes complete, including a zero-length POST. Event data contains the session array under upload, with its ID, model, collection, size, and server-computed SHA-256 hash. Delivery is at most once with no retry. Save the application entity and call ResumableUploads::consume() to create the file row. See resumable uploads.