How to Configure WebP Converter for Media with Custom WordPress Folder Structures

Many WordPress users employ custom folder structures for performance, security, or organizational reasons. This is common with setups like Roots Bedrock, custom wp-content directories, or plugins that store images outside the standard Media Library. A frequent question for the 'Converter for Media – Optimize images | Convert WebP & AVIF' plugin is how to make it work with these non-standard configurations.

Why This Happens

The plugin is designed to work with standard WordPress installations. By default, it looks for images within the standard wp-content directory structure (e.g., wp-content/uploads, wp-content/themes, wp-content/plugins). If your site uses a different structure, such as a renamed wp-content folder or a custom uploads path defined by another plugin, the converter may not locate your images or may display errors in its settings panel.

Common Solutions

Fortunately, the plugin provides filters that allow advanced users to redefine its file paths. The most common solution involves adding code to your theme's functions.php file.

1. For Custom wp-content Directories

If you have redefined your content directory using WP_CONTENT_DIR and WP_CONTENT_URL constants in your wp-config.php file, you can help the plugin recognize this change. The following code snippet tells the plugin to use your custom root path.

add_filter( 'webpc_site_root', function( $path ) {
    // Replace this with the absolute server path to your site's root
    return '/your/custom/root/path';
} );

2. For Custom Uploads Paths (e.g., Outside wp-content)

If you are using a plugin like WP Original Media Path to store uploads in a completely different location, you can use the webpc_dir_name filter to redirect the plugin. This example changes the 'uploads' directory path.

add_filter( 'webpc_dir_name', function( $path, $directory ) {
    if ( $directory !== 'uploads' ) {
        return $path;
    }
    return 'app/uploads'; // Your custom directory name
}, 10, 2 );

3. Complete Example for Bedrock (or Similar)

Users of the Roots Bedrock stack have shared a successful configuration. This involves defining a custom path via an environment variable and then applying multiple filters.

In your .env file:
WEBPC_UPLOADS_ROOT='/var/www/html/web'

In your theme's functions.php:

add_filter( 'webpc_site_root', function( $path ) {
    return defined('WEBPC_UPLOADS_ROOT') ? WEBPC_UPLOADS_ROOT : $path;
} );

add_filter( 'webpc_dir_name', function( $path, $directory ) {
    if ( $directory !== 'uploads' ) {
        return $path;
    }
    return 'app/uploads';
}, 10, 2 );

Important Limitations to Note

• Plugin Compatibility: The plugin may not automatically convert images for every third-party plugin. For instance, images stored in folders created by the Ultimate Member or wpDiscuz plugins are not natively supported. The provided filters are the primary method for adding support for such custom paths.
• Testing: After adding any custom code, always clear your cache and test that WebP images are being served by checking your site's frontend with browser developer tools.
• Child Theme: Always add code to a child theme's functions.php file to prevent it from being overwritten during theme updates.

By using these filters, you can extend the functionality of the 'Converter for Media' plugin to work seamlessly with a wide variety of custom WordPress installations.