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.
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.
serveRoute	array	(unset)	Route to your custom serving controller.

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' => [
        'Avatar' => $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
],

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

serveRoute

The route to your custom serving controller, used for URL generation:

'serveRoute' => [
    'controller' => 'Images',
    'action' => 'display',
    'plugin' => false,
],