Download the PHP package justinholtweb/craft-waterfall without Composer

Waterfall

Watermarking for Craft CMS 5.

Put a mark on your images — automatically, everywhere, and reversibly. Waterfall is the Craft answer to the WordPress plugin Easy Watermark: image and text watermarks applied to generated transforms, burned into the original file with a restorable backup, produced on demand from Twig, or built at your CDN by imgix, Cloudinary or ImageKit.

• Craft CMS 5.9+, PHP 8.2+
• Lite $59 · Pro $79

Why

Four problems, and Waterfall exists for all four.

A watermark applied by hand is applied inconsistently. Somebody forgets, somebody uses the wrong corner, somebody uploads the unmarked original next Tuesday.

A watermark burned into the original cannot be taken back. Waterfall backs the original up before it writes anything, and will not write if the backup fails. Restoring is one click, one element action, or one console command — in Lite as well as Pro.

The mark has to survive the image pipeline. Craft's transforms, ImageOptimize's .webp and .avif variants and Imager-X's output are all new files made from the source, so a mark that lives only in the source file disappears from every derivative that gets regenerated, and one that lives only in a transform is missing from the file people download. Waterfall covers both.

Some sites do not process images at all — the CDN does. So the CDN is a driver, not a different plugin.

Install

A profile

A profile is one watermark: what it is, how big, where it goes, how see-through, and which images get it. Profiles live in project config, so they deploy with the site.

Text watermarks are rendered as object templates, so they can carry the asset and the site with them:

Four fonts are bundled (Lato, Lato Bold, IBM Plex Mono, EB Garamond, all OFL). A profile can also point at an uploaded .ttf or .otf, which wins.

Where a watermark can be applied

Three modes, switchable per profile, because they answer different questions.

Transforms. The mark is composited into generated transforms. Originals are never touched, everything is undone by clearing the transform cache, and the mark reaches ImageOptimize's variants and Imager-X's output. What most sites want, and it needs no template changes: asset.getUrl() already returns a watermarked image.

Permanent. The stored file itself is rewritten — on upload, from the asset index, from the asset's own edit screen, or from the console. The original is copied to the backup store first. This is the only mode that protects the file somebody downloads straight from the volume.

On demand. Nothing automatic; a Twig call, an element action or a console command asks for a watermarked derivative, which Waterfall stores itself.

Twig

Most sites need none of this — a profile in transforms mode watermarks asset.getUrl() with no template changes at all. This is for the cases that need to ask.

ImageOptimize

Nothing to configure. ImageOptimize listens to the same Craft event Waterfall does, and re-saves, optimizes and derives its .webp/.avif variants from the image on that event — so the only thing that matters is running first. Waterfall registers its handler prepended, composites onto the image before ImageOptimize ever sees it, and every file ImageOptimize produces carries the mark. An integration check asserts the ordering, because if it ever regressed the symptom would be "the .webp has no watermark and nothing is in the log".

If ImageOptimize is set to transform through a service rather than on this server, Waterfall says so on its settings screen and in waterfall/doctor — mark those images with a provider instead.

Imager-X

Imager-X does not use Craft's transform pipeline, so it gets its own wiring.

Automatic. Waterfall registers a transformer that adds matching profiles to every transform, so the watermark appears with no template changes and each profile gets its own cache entry. Requires Imager-X Pro, which is the edition where transformers can be registered.

By hand, on any Imager-X edition:

The effect runs Waterfall's own compositor, so text, tiling and rotation all work — none of which Imager-X's built-in watermark parameter can do.

Delivery services (Pro)

A provider that cannot do what a profile asks for says so on the profile screen rather than quietly delivering something else. The URL template takes {src}, {srcEncoded}, {path}, {mark}, {markEncoded}, {position}, {opacity}, {scale}, {width}, {height}, {format}.

Console

waterfall/doctor is worth running once on any new server. Watermarking fails quietly more often than it fails loudly — GD compiled without FreeType draws no text, a server without Imagick has no blend modes, a provider with no credentials returns no URL — and it prints all of that in one place.

Editions

Lite ($59) — one profile, image watermarks, nine positions and offsets, scaling, opacity, GD and Imagick, all three modes, backups and restore, volume/file-type/size rules.

Pro ($79) — unlimited and stackable profiles, text watermarks, tiling, rotation, blend modes, asset conditions, the four delivery services, the Imager-X and ImageOptimize integrations, the per-asset Waterfall field, and the console tooling.

Backups and restore are in Lite deliberately. Charging for the undo of a destructive operation is not a business model.

What Waterfall refuses, and says so

Vector files, animated GIFs (unless you turn that off — re-encoding loses the animation), images below a profile's minimum size, files Craft cannot manipulate, assets in volumes a profile does not cover, and assets whose Waterfall field says never. Each refusal comes with the sentence that explains it, on the asset's edit screen, in the dry run, and in craft.waterfall.explain().

Licence

The Craft License. See LICENSE.md. Waterfall is commercial — Lite $59, Pro $79 — and is licensed through the Craft Plugin Store.

Support

[email protected]