The use of "relative" paths in EWWW IO was introduced primarily for those using Pantheon's load balancing feature. The purpose is to prevent EWWW IO from losing track of images when a portion of the file system path changes regularly. It also has the side effect of disabling symlink resolution, since symlinks will often wreak havoc in these sorts of setups.

First, lets clear up what we mean by a "path". When you use something like http://www.example.com/wp-content/uploads/image.jpg that is NOT a path. That is a url to an image, and your server translates a url into a path transparently. For example, the image above may actually be located on the server at /var/www/wp-content/uploads/image.jpg or /home/example/public_html/wp-content/uploads/image.jpg or any other crazy variation that a webhost can come up with. Most web servers are running Linux or some variant of UNIX, but if you happen to run a Windows server, it might be D:\httpdocs\wp-content\uploads\image.jpg or something similar.

Now that we have that out of the way, how about an example? If you're using the aforementioned load-balancer setup, or you like to use version control on your images, you might have your images in /srv/bindings/xyz130773/wp-content/uploads/ on server 1 and /srv/bindings/zbc381822/wp-content/uploads/ on server 2. When EWWW IO scans your images for optimization, it does so in batches, so some images get stored in the database with the first path, and some get stored with the latter path. Even worse, when you start to optimize, only a few images will be optimized in each batch, and the AJAX requests will be distributed between the servers, what a mess!

Relative path support works by choosing one of three "constants" to replace within the filenames. It then replaces the value of that constant with the literal "string" name of the constant, and stores that in the database. When the path is retrieved from the database, the plugin can then see exactly which constant was used and will replace the name of the constant in the path with the value of the constant (the reverse of what happened before).

The 3 constants available are EWWW_IMAGE_OPTIMIZER_RELATIVE_FOLDER, ABSPATH, and WP_CONTENT_DIR, and they are tested in that order as well.

To continue our example, the server 1 might have ABSPATH defined as /srv/bindings/xyz130773/ and server 2 would have it defined as /srv/bindings/zbc381822/. Note that ABSPATH is generally defined automatically by WordPress, it is not something you need to configure. So lets say that the image url is http://www.example.com/wp-content/uploads/image.jpg and on server 1 this is located at /srv/bindings/xyz130773/wp-content/uploads/image.jpg and on server 2 it is at /srv/bindings/zbc381822/wp-content/uploads/image.jpg.

The first thing you need to do is define the EWWW_IMAGE_OPTIMIZER_RELATIVE constant as true in wp-config.php:


With this in place, EWWW IO will look to see if the path of the image contains the value of ABSPATH. In our example, it does, so the path is stored as "ABSPATHwp-content/uploads/image.jpg". When it comes to doing the actual optimization, EWWW IO will see that ABSPATH is in the filename, and it will replace it appropriately. If the optimization is running on server 1, then it will replace ABSPATH with /srv/bindings/xyz130773/ and happily continue with the optimization.

So, if EWWW IO is seeing your images as being inside ABSPATH or WP_CONTENT_DIR, there is nothing further to do.

However, if you store the images somewhere else, and do NOT use WP_CONTENT_DIR to tell WordPress where the images live, then you can define EWWW_IMAGE_OPTIMIZER_RELATIVE_FOLDER like so:

define( 'EWWW_IMAGE_OPTIMIZER_RELATIVE_FOLDER', '/srv/bindings/xyz130773/file/' );