Implement a custom cloud storage handler

By default, Chamevo stores all files on the local WordPress filesystem under wp-content/uploads/chamevo/. The chamevo_storage_handler filter lets you redirect two folder types — customer uploads and generated print-ready files — to any external storage provider: Amazon S3, Hetzner Object Storage, Google Cloud Storage, Dropbox (programmatic), or any service with a PHP SDK.

The built-in Dropbox and AWS S3 delivery settings handle the most common cases without code. Use this API when you need a provider that is not built in, or when you need different buckets, CDN configurations, or business logic per folder type.

Scope

Only two folder types can be redirected to cloud storage:

Folder type	Contents	Default local path
`uploads`	Customer-uploaded files from the frontend customizer (images, PDFs, SVGs)	`wp-content/uploads/chamevo/uploads/`
`print_files`	Generated print-ready exports (PDF, PNG, SVG, ZIP)	`wp-content/uploads/chamevo/print_files/`

All other folders (_temp, fonts, 3d_models, patterns_svg, etc.) always remain local and cannot be redirected.

File flow

Files are always processed locally first, regardless of which storage handler is active:

Method	When called	Notes
`putFromLocal(string $relativePath, string $localAbsolutePath): bool`	After every customer upload and every print file generation	Most common write path. Receives the absolute local path of the already-processed file.
`put(string $relativePath, string $contents): bool`	When writing content directly, not from a local file	Less common. Ensure parent "directories" exist in your storage if needed.
`get(string $relativePath): ?string`	When email attachments need a local copy of a cloud-stored print file	`wp_mail()` requires a local path, so Chamevo downloads the file to `_temp/` before attaching. Return `null` if the file does not exist.
`url(string $relativePath): string`	Every time a file URL is needed — frontend response, email links, Printful API	Must return a publicly accessible URL. For Printful integration, the URL must be reachable from Printful's servers.
`delete(string $relativePath): bool`	When individual files are cleaned up	Should be idempotent — return `true` if the file does not exist.
`deleteDirectory(string $relativePath): bool`	Admin "Empty print-ready directory" maintenance action	An empty string means clear everything. Chamevo also clears the local directory separately.
`exists(string $relativePath): bool`	Before serving or processing a file	Used to verify file availability before operations.

Folder type	Recommended	Why
`uploads`	Safe to enable	After cloud push, only the URL is needed.
`print_files`	Use with caution	Printful reads local files for ZIP extraction. Email attachments download from cloud to `_temp/` when using cloud storage, which adds latency. Enable only if you are not using Printful and accept the email latency.

Filter	Args	Default	Description
`chamevo_storage_handler`	`$handler` (null), `$folderType` (string)	`null`	Return a `StorageHandlerInterface` instance to override storage for the given folder type. Return `null` or the original `$handler` to keep local storage.
`chamevo_storage_delete_local_after_push`	`$delete` (bool), `$folderType` (string)	`false`	Return `true` to delete the local file after a successful cloud push. Only takes effect when a cloud handler is active.

Loading guides

Loading Support Center

Loading guides

Implement a custom cloud storage handler

Scope

File flow

Related articles

Register a handler

Implement StorageHandlerInterface

Method reference

Relative paths

Delete local files after cloud push

StorageManager API

Special behaviors

Print file downloads

Email attachments

Database compatibility

Filter reference

Testing your handler

FAQ