Configuration Reference

All configuration lives under the FileStorage key, typically in config/app.php or a dedicated config/storage.php. The plugin ships a complete, commented config/app.example.php you can copy from.

Keys at a glance

Key	Type	Default	Purpose
pathPrefix	string	'img/'	Prefix prepended to generated image paths/URLs.
hashAlgorithm	string|false	'sha256'	Algorithm for the content hash stored with each upload.
deduplicate	array	['collections' => false, 'gracePeriod' => 3600, 'root' => 'blobs']	Share identical uploads per adapter.
signatureSecret	string	Security.salt	HMAC secret for signed URLs.
adminAccess	bool|Closure|null	null	Admin backend access gate (fail-closed).
standalone	bool	false	Run the admin backend independent of your AppController.
adminLayout	string|false|null	null	Layout used by the admin backend.
adminBackUrl	array|string	(unset)	Optional "back to app" link in the admin header.
adminBackLabel	string	'Back to App'	Label for adminBackUrl.
imageVariants	array	[]	Variant definitions keyed by [Model][Collection].
behaviorConfig	array	[]	Default config for the FileStorage behavior.

Image and path settings

pathPrefix

Prefix prepended to generated image paths and URLs (used by the Image helper). Defaults to 'img/'.

imageVariants

Variant definitions in a two-level hierarchy: [ModelAlias][CollectionName]. See Image variants and versioning for the full operation list.

'imageVariants' => [
    'Users' => [
        'Avatars' => $collection->toArray(),
    ],
],

behaviorConfig

The default options array passed to the FileStorage behavior. See the Behavior Options reference for every key.

'behaviorConfig' => [
    'fileStorage' => $fileStorage,   // required FileStorage instance
    'fileProcessor' => null,         // image/file processor
    'fileValidator' => null,         // upload validator class/instance
    // 'dataTransformer' => null,    // entity<->file transformer for the queue task
],

Content hash

hashAlgorithm

An upload gets a hash of its content in the hash column of its file_storage row. Use it to verify a stored file or to find rows with identical content.

The column stays null when the content cannot be read: a failed upload, or a stream that is neither backed by a file nor seekable.

'hashAlgorithm' => 'sha256',

Accepts any name from PHP's hash_algos() whose hex digest is at most 64 characters, the width of the column. An unknown name or a longer digest throws a RuntimeException on save. Set it to false to skip hashing; replacing the file on an existing row then clears that row's hash.

Existing rows are not hashed retroactively. Their hash stays as it was, usually null.

Deduplication

deduplicate controls collection selection, the cleanup grace period (how long an unused stored file is kept before cleanup removes it), and the blob root. Its attachAuthorizer closure controls attachment by hash and must return exactly true; attachment is denied when it is unset. It requires SHA-256 hashes, atomic saves, and the blob migration. See Deduplication for configuration forms, database support, and scheduled cleanup. Use BlobAttacher to attach existing blobs and BlobImporter to register files already on an adapter.

Resumable upload classes

• FileStorage\Service\ResumableUploads: create, inspect offsets, append streamed chunks, terminate, consume, and clean up sessions.
• FileStorage\Http\TusServer: map PSR-7 requests to tus 1.0.0 responses.
• FileStorage\Controller\UploadsController: application-routed collection and resource actions.

FileStorage\Http\CompletedUpload is internal. Applications use consume() instead. See resumable uploads for configuration and examples.

Signed URLs

signatureSecret

The secret used to sign temporary file-access URLs (SignedUrlGenerator, HMAC-SHA256). It should be a strong, random, app-specific string kept secret: anyone with it can forge valid signed URLs. No default is baked in: when unset, it falls back to the app's Security.salt. Set it explicitly to decouple signed-URL invalidation from the salt.

'signatureSecret' => env('FILE_STORAGE_SECRET'),

Admin

adminAccess

The admin backend is fail-closed: leaving this unset (or null) means every action returns 403. Opt in with one of:

• true: trust an upstream gate (Authentication + Authorization, TinyAuth, custom middleware) on the Admin prefix.
• Closure(\Cake\Http\ServerRequest $request): bool: return true to allow the request.

See the Admin Backend page for examples.

standalone

When true, the admin controllers run independent of the host application's App\Controller\AppController (skipping its initialize() chain, loading only Flash). Useful for projects without their own admin shell. Leave false (default) to inherit your AppController's components.

adminLayout

The bundled Bootstrap 5 / Font Awesome 6 admin layout (CDN with SRI):

• null: use the bundled FileStorage.file_storage layout (default).
• false: fall back to the host application's default layout.
• string: use the given layout, e.g. 'App.admin'.

adminBackUrl / adminBackLabel

An opt-in "back to app" link in the admin header. When set, an outline button appears in the top navbar so admins can escape the plugin-isolated layout. adminBackUrl accepts anything Router::url() takes: a Cake URL array, a path string, or a full URL. Use 'plugin' => false to anchor the builder to the host app rather than the FileStorage plugin.

'adminBackUrl' => ['plugin' => false, 'prefix' => 'Admin', 'controller' => 'Overview', 'action' => 'index'],
'adminBackLabel' => 'Back to admin', // optional, defaults to "Back to App"

Serving

Use SignedUrlGenerator::url() for the built-in original-file download route. Custom serving routes are registered and generated through CakePHP's router; there is no FileStorage.serveRoute hook. See Serving files.