Common Solutions

Setting the Correct “Base Path” (Document Root)

When looking at your debug messages from the template debugger (see the Troubleshooting page for more info), you'll see output like (0.038385 / 7.17MB) *** CE Image debug: Base path: '/your/current/document/root/' that displays your “Base path”. This path should match your server’s directory path to your site’s web/document root. If it isn’t set to what it should be, you can change it using the 'ce_image_document_root' setting (please take a look at Advanced Configuration for more details):

//Config Settings
$config['ce_image_document_root'] = '/some/server/path/to/document_root/';

When Relative URL Paths Don’t Match The Server Directory Structure

Sometimes, particularly on temporary development servers, there will be a discrepancy between the URL and the server path. For example, if your image is accessible via URL at, but your server path is /usr/local/apache/htdocs/, you may run into problems (notice the extra /~user segment in the URL, but not the path).

The solution to this problem, is to modify the URL before and after the plugin attempts to manipulate it, using the Advanced Configuration settings, like so:

//Config Settings

//remove the extra '/~user' from the source
$config['ce_image_src_regex'] = array( '/~user' => '' );

//after the image is manipulated, replace the first '/'
//with the extra '/~user/' so it works with the URL
$config['ce_image_made_regex'] = array( '^/' => '/~user/' );

Note: The ~user segment is arbitrary, and could be any name. For example, it could be foo or ~bar

Subdirectory Installation

Before you flip out about why you need to configure this, you need to understand that server paths and URLs are in no way tied together. PHP could not care less about the image URL; it needs the server path. Conversely, your web page does not care about server paths; it needs a relative or fully quantified URL to the image. CE Image has to try and match up the URL and the server paths to try and figure out what to do. It can normally do that out-of-the-box, but subdirectory installations need a little more configuration.

To keep a long explanation short, here are the config settings that are needed to get this to work:

//replaces the first chunk of the URL with its corresponding server path:
$config['ce_image_src_regex'] = array(
    '^http://(.*.)?' => '/server/path/to/web_root/subdirectory/',
    '^/subdirectory/' => '/server/path/to/web_root/subdirectory/'

//adds the '/subdirectory' chunk before '/images' to the relative path
$config['ce_image_made_regex'] = array( '^/images/' => '/subdirectory/images/' );

You’ll obviously want to replace, subdirectory, and /server/path/to/web_root/subdirectory/ with the actual values from your setup.

If you feel like the above configuration settings are insurmountable and you need help, please ask for support.

Frame An Image

At some point you may want to resize or constrain an image to fit within particular dimensions and then position it within an area. Although there is no native way of doing this, there are several ways of accomplishing it:

Option 1 - HTML

You could crop the image down and set it as a background image for a div, or an anchor element. In the below example, the image is being cropped to 150px by 150px and then set as the background image for a div that is 200px by 200px:

{exp:ce_img:pair src="/images/example/cow_square.jpg" max="180" crop="yes"}
<div style="width: 200px; height: 230px; background: #fff url({made}) no-repeat 10px 10px;  box-shadow: 0 0 3px rgba(0, 0, 0, .3); -webkit-box-shadow: 0 0 3px rgba(0, 0, 0, .3);"><!-- --></div>

Option 2 - Watermark

The next alternative is to use an image for your background, and then place your constrained or cropped image over it as a watermark. The background image can either be a full-sized image, or a small 1px by 1px image you can stretch to any dimensions you desire.

{exp:ce_img:pair src="/images/example/cow_square.jpg" parse="inward" max="180" crop="yes"}
{exp:ce_img:single src="/images/example/white_spec.png"
watermark="{made}|0,0|100|center,top|0,10" width="200" height="230" crop="yes" allow_scale_larger="yes"
style="box-shadow: 0 0 3px rgba(0, 0, 0, .3); -webkit-box-shadow: 0 0 3px rgba(0, 0, 0, .3)"}