Getting started with verklein.nu

Installing

1. The plugin is coming to WordPress.org soon. Then, in WordPress, go to Plugins → Add New Plugin and search for verklein.nu.
2. Activate the plugin. You then find it as verklein.nu in the admin menu, right below Media.
3. Open the System & help tab and check whether your server can create WebP and AVIF.
4. Back up your database and the wp-content/uploads folder before you convert the library for the first time.

Nothing changes after installing: nothing is converted until you start it or switch on converting uploads.

The admin: five tabs

New uploads

Automatic conversion is on by default; the switch is on the New uploads tab. Every new JPG and PNG is converted while it is uploaded: WordPress writes the main file and every size straight in WebP or AVIF, without making JPGs first.

• Format and quality (under Settings): the same as for existing images by default, but uploads can have their own format or quality. AVIF makes each upload a few seconds slower; WebP is fast.
• Maximum dimensions (under Settings): photos from a camera or phone are often 4000 to 6000 pixels. Set a maximum width and height. Choose whether a larger upload is first made smaller or refused. Also works when automatic conversion is off.
• Maximum file size per image (under Settings): for example 1 MB. Larger images are refused with a message. The check happens after scaling down.
• Upload limit (under Settings): the maximum size for all files. The page shows what PHP on your server allows. A plugin can only set a lower limit; for a higher one, ask your host or change php.ini.
• Where it works: the Media Library, the block editor, the media modal of page builders, WooCommerce product imports, the REST API and wp media import. GIF, SVG and PDF are left alone on upload.

When you switch it off, uploads stay JPG or PNG until you convert them: one by one with the Convert button in the Media Library, or together with the rest of the library.

Existing images

What is already in your library you convert in one run with the wizard on the Existing images tab. While there is still something to convert, New uploads also shows a button to the wizard at the top.

1. Your library: how many images can get smaller, and whether your server can create WebP and AVIF.
2. Choose: the format (WebP, AVIF or keep JPG/PNG), what happens to the originals and how much to compress. The recommended choices are already selected.
3. Example: an image from your library in the three levels. Drag the line to compare with the original, or pick an image yourself to test with. Nothing is saved yet.
4. Convert: confirm you have a backup and start. The task runs in small batches; keep the page open for the fastest result. If you close it, the task continues through WP-Cron.

When it is done you see what was saved. New uploads get the same treatment automatically. Caches are cleared; clear your CDN or Varnish cache yourself. To run it again later, for example with other settings, just use the same tab.

Settings

These settings apply to existing images and to new uploads. For most sites the four main choices are enough.

Collapsed under More options:

• PNG, JPG, GIF and PDF: PNG to lossless WebP, PNG to 256 colours or to JPG, progressive JPGs, GIF to WebP, compressing PDFs and the effort.
• Backups and URLs: smart backup, deleting backups automatically, updating URLs in every table, redirecting old URLs and checking every page for old URLs that were left behind.
• Which images are left alone: file types, names and folders, file size, upload period, post types and the site icon.
• Image sizes: per thumbnail size, do not compress or do not create, and the maximum size.
• Fallback mode: <picture> elements, the whole page, the Accept header rule and front-end exclusions.
• Advanced: metadata, only when smaller, caches, batch length, uninstall and e-mail reports.

Exporting and importing settings as a JSON file is at the bottom of the same page.

Requirements

nginx

nginx ignores the .htaccess file that closes the backup folder, so add a rule to the server configuration yourself. The second rule sends old JPG and PNG URLs to WordPress, for the 301 redirect. The exact folder name for your site is on the System & help tab, and the system check tests whether the folder is closed.

location ^~ /wp-content/uploads/verklein-backup-<name>/ {
    deny all;
}
location ~* ^/wp-content/uploads/.+\.(jpe?g|png)$ {
    try_files $uri /index.php?$args;
}
types { image/webp webp; image/avif avif; }

Apache and LiteSpeed need nothing extra.

WP-CLI

Everything in the dashboard also works from the terminal, without time limits. Options you leave out come from the settings. wp byt still works as an alias, for scripts written for the old mu-plugin.

wp verklein convert --to=webp --dry-run        # see what would happen first
wp verklein convert --to=webp                  # convert, update URLs, clear caches
wp verklein convert --to=avif --quality=55 --effort=4
wp verklein convert --to=avif --mode=fallback  # keep JPG/PNG, add AVIF and WebP copies, <picture>
wp verklein convert --to=webp --originals=keep # leave the originals in place
wp verklein convert --to=webp --ids=12,15      # only these attachments
wp verklein convert --to=webp --network        # multisite: every site
wp --url=https://example.com/site-2 verklein convert --to=webp   # one subsite

wp verklein restore --dry-run
wp verklein restore --ids=12,15
wp verklein rewrite --dry-run
wp verklein repair
wp verklein status
wp verklein cleanup --yes
wp verklein job run                            # finish a task started in the dashboard

wp verklein convert

Converts images to WebP or AVIF, including every size and (by default) the URLs in the database. Without --to, --ids or --network the command shows its help.

wp verklein restore

Puts the original JPG and PNG files and their URLs back. Also works for images converted with the old mu-plugin. For images with copies (fallback mode) only the copies are deleted.

Other commands

For developers

Use these filters and actions to change the behaviour from your theme or your own plugin.

// Also rewrite URLs on your CDN.
add_filter( 'verklein_rewrite_hosts', function ( $hosts ) {
	$hosts[] = 'cdn.example.com';
	return $hosts;
} );

// Let editors convert too.
add_filter( 'verklein_capability', function () {
	return 'edit_others_posts';
} );

// Never convert the logo and IDs 42 and 43.
add_filter( 'verklein_excluded_ids', function ( $ids ) {
	return array_merge( $ids, array( 42, 43, (int) get_theme_mod( 'custom_logo' ) ) );
} );

// Do not convert uploads with "original" in the file name.
add_filter( 'verklein_convert_upload', function ( $convert, $file ) {
	return false === stripos( $file['name'], 'original' ) ? $convert : false;
}, 10, 2 );

// Also skip the tables of your own logging plugin.
add_filter( 'verklein_rewrite_skip_tables', function ( $prefixes ) {
	$prefixes[] = 'mylog_';
	return $prefixes;
} );

// Clear the CDN cache after a task as well.
add_action( 'verklein_purge_caches', 'my_cdn_purge_all' );

// No <picture> on the checkout page.
add_filter( 'verklein_picture_enabled', function ( $enabled ) {
	return function_exists( 'is_checkout' ) && is_checkout() ? false : $enabled;
} );

// Add a class to every <picture> element.
add_filter( 'verklein_picture_html', function ( $html ) {
	return str_replace( '<picture>', '<picture class="vk-picture">', $html );
} );

// Log how much was saved per image.
add_action( 'verklein_converted', function ( $id, $record ) {
	error_log( sprintf( 'Attachment %d: %d bytes saved', $id, $record['bytes_before'] - $record['bytes_after'] ) );
}, 10, 2 );