The bg_color= parameter allows you to input a background fill color as a hexadecimal value. Leave blank or not specified for transparency (if a png or gif) or to default to white (if a jpeg). This parameter comes in handy if you want to add a background color or save a transparent png as a different format.

The default background fill color to be used, in the form of a hexadecimal value. By default, PHP will convert transparency to black pixels. So, for example, if you are saving a mostly transparent png image to jpg format, the transparent pixels would end up appearing black. CE Image already changes that default to white ( #ffffff ), and this parameter allows you to override that default to the color value of your choice.

This parameter is particularly useful if you want to apply filters to a png image that will be saved as a jpg, as it allows you apply the filters to the png image before the background color is applied.

This parameter allows you to create a solid color border around your image. If you are using this parameter in combination with rounded_corners=, the borders will be antialiased, to give a nice smooth appearance. The general syntax for this parameter is border="thickness|color" . The color can be a 3 or 6 digit hexadecimal (with or without the #), and defaults to 'ffffff' if not specified.

Note : Like borders applied with CSS, the border is created on the outer edge of the image (as opposed to an inner border). If you have a 100px by 100px image for example, with a border-width of 10 passed in, your final image dimensions would be 120px by 120px.

Pass in the name of the Amazon S3 bucket you would like the manipulated image(s) to be saved to.

This parameter allows you to specify a cache directory. If this parameter is not specified, or left blank ( "" ), then the default cache directory will be used. The default cache directory can be specified in the pi.ce_img.php file, by assigning a value to the $cache_dir variable (initially set to '/images/made/' ).

cache_dir set to "/images/made/" relative path:
/images/made/images/example/cow_square_100_100.jpg

cache_dir set to "/images/test/" relative path:
/images/test/images/example/cow_square_100_100.jpg

This parameter allows you to return an image tag without having to type out all of the boilerplate code. This parameter changes depending if you are using the single tag (no tag data) or tag pair (has a closing tag) syntax.

If you are using a single tag, this value defaults to "yes" . The following two plugin calls are identical:

When the tag is created, the width, height, and a blank alt attribute are automatically set for you. So, the above plugin calls will both return the following HTML:

Note : If create_tag is set to "no" for a single tag, nothing will be returned.

The width and height attributes will be added to the image tag, along with any attributes you pass in. Here’s an example:

Note : Please note that the alt tag is not automatically added if you are passing in attributes, but the width and height attributes are still included.

If you are using a pair tag, this value defaults to "no" . Here is an example of using pair tag syntax:

When the tag is created, the width, height, and a blank alt attribute are automatically set:

There are two ways to add attributes when using tag pair syntax. The first way, like the single tag syntax above, is to pass in the attributes directly to the plugin tag. Additionally you can pass the attributes in as tag data. Here are examples of the two ways to specify attributes using the tag pair syntax:

The above two plugin calls result in the same HTML:

Note : As of version 2.1.4, this parameter has been deprecated and is not longer needed. The plugin will automatically enable debug mode if you are logged in as a Super Admin and have template debugging enabled.

When you download images from other domains, the plugin can optionally run CodeIgniter®’s XSS filter. Sometimes the filter may flag your image as malicious, even when you know it is not. You can enable this filter if you do not trust the source of the remote images you are downloading (for example, you are manipulating images from a user provided URL). To enable the filter, simply add this to your CE Image tag: disable_xss_check="no" .

If your images do not pass the XSS filter, a debug message will be logged in your Template Debugging console like:

Essentially, this replaces spaces with %20 so that they validate. This parameter is enabled by default, but can be disabled by setting it to "no" .

In the example below, you can see the default behavior to encode the space in the filename, immediately followed by the parameter being disabled.

Sometimes you may want to specify a fallback image. For example, if you are showing thumbnails of the photos for different users on your site, and some of the users are missing photos, you could designate a default photo to replace the missing photos (like one of those unisex silhouette images) via the fallback_src= parameter.

In the example below, the source image does not exist, so the fallback_src would be used.

The filename you would like the image saved as. By default, the filename of the source image is used.

In the below example, the original image ( cow_square.jpg ) is saved with a new filename of moo.jpg .

Optionally add a prefix to the filename of the manipulated image.

In the below example, the original image ( cow_square.jpg ) is prefixed with my_ .

Optionally add a suffix to the filename of the manipulated image.

In the below example, the original image ( cow_square.jpg ) is concatenated with the suffix _foo .

The flip parameter allows you to flip your image horizontally (x-axis), vertically (y-axis), or both (x and y axes). You can simply pass in one of the following: h , v , h|v , v|h

Note : For reasons unknown, the image quality may be changed when using this parameter (although the difference should not be too noticeable). The below 3 images all result in different file sizes…

Below are some examples of the flip parameter in action.

In rare occasions, you may have a script on your current domain that is serving up the images (from a database or something) rather than using actual image assets on your server. By specifying the fully quantified URI to the image (example: http://www.example.com/image_script.php?id=blah) and using this parameter, CE Image will know to attempt to retrieve the image over http, instead of looking for an actual image asset. The image will then be downloaded to the server and manipulated in the same manner as a remote image.

This parameter allows you to hide the name of the image by using a hash as the final filename, which means your site users will not be able to tell what the original filename was. Possible values are "yes" and "no" , with the default being "no" .

In the below example, the original image is first saved without hashing the filename (default behavior, resulting in {exp:ce_img:pair src="/images/example/cow_square.jpg" manipulate="no"}{name}.{extension}{/exp:ce_img:pair} ) and then again with the filename hashed (resulting in {exp:ce_img:pair src="/images/example/cow_square.jpg" hash_filename="yes"}{name}.{extension}{/exp:ce_img:pair} for the filename).

The maximum height you would like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero). You can also pass in a percentage of the source image’s height. If a percentage is used, the plugin will convert it to a pixel value and size the image accordingly.

In the first example below, a max height of 100px is specified. Since a max width is not specified, the image’s width is scaled proportionately to the new height (in this case, the width is automatically sized to 67px). For the second example, the image is resized as a percentage of the source image’s height.

This parameter allows you to hide the relative path of the original file. This can be useful, if you do not want to give away the relative path to the original image. Possible values are "yes" and "no" , with the default being "no" .

This parameter allows you to specify whether or not a generated image will be interlaced. Possible values are "yes" and "no" , with the default being "no" .

Note : For JPEG images, this is often referred to as “progressive” JPEGs.

The manipulate parameter tells the plugin whether or not you want to manipulate the image. The default is "yes" .

Sometimes you may want to get an images info, without the overhead of manipulating it. To do so, simply set this parameter to "no" .

There are a number of reasons you may want to get the original image without manipulating it. For example, you want to know the filename, file size, generate ascii_art, get the top_colors, etc.

Any manipulation parameters that are passed into the plugin will be ignored.

The maximum width and height you would like the image to be constrained to. Should be a whole number, an empty string ( "" ), or zero.

Sometime you may want to output something other than the image tag. Many times you can simply do this with the tag pair syntax, but you may want to do this from a single tag too. This parameter lets you customize the plugins output.

Overwrites the cached image and will always generate a new image. This will drastically hinder performance if set to "yes" , as the image will be created each time the plugin is called. Accepted values are "yes" and "no" , and the default is "no" .

overwrite_cache="yes"

Sets the quality of a jpg/jpeg file. The quality can range from 0 (lowest) to 100 (highest) and should be a whole number. The default quality is 100.

Note : This parameter has no effect if the final image is a png or a gif, as they are always saved at their respective highest qualities.

You can see in the example below that the quality of the first image is very low (10%), compared to the default quality used in the image on the right (100%). The advantage of setting the quality lower is reduced file size (and ultimately page loading speed). Setting a quality of 80 is often a good way to radically lower file size without drastically affecting the image’s appearance.

The reflection= parameter allows you to create a reflection for the image, otherwise known as the “wet floor effect.” The general syntax for this parameter is reflection="gap_height,start_opacity,end_opacity,reflection_height" . Here’s a look at each of the sub parameters in more detail:

gap_height : The vertical space, in pixels, between the image and its reflection.

start_opacity : The opacity of the reflection at the top of the reflection. This can be any number between 0 (completely transparent) and 100 (completely opaque). The default is 80.

end_opacity : The opacity of the reflection at the bottom of the reflection. This can be any number between 0 (completely transparent) and 100 (completely opaque). The default is 0.

reflection_height : The height of the reflection, either in pixels, or as the percentage of the image. If specifying as a percentage, then a % should be concatenated on the end. For example, if the made image was 100px tall, and a reflection height of 50% was specified, then the resulting reflection would be 50px tall.

The default settings are: reflection="0,80,0,50%" .

This parameter allows you to override the minimum specified interval a remote image should be cached before having to re-download the image. The default is '-1', which means CE Image will never attempt to re-download the image. The default can be changed globally by assigning a value to the $remote_cache_time variable in pi.ce_img.php , but can be overridden in config.php , and authoritatively overridden by this parameter.

PHP can only manipulate images that are on the local server. So if an image is located on another server, it must first be downloaded to your server before it is manipulated. This parameter allows you to specify a cache directory for the downloaded remote images. The downloaded image will then be used to manipulate and cache your final image, using the same parameters as a default image on your site.

If this parameter is not specified, or left blank ( '' ), then the default remote cache directory will be used. The default remote cache directory can be specified in the pi.ce_img.php file, by assigning a value to the $remote_dir variable (initially set to '/images/remote/' ).

Example:

remote_dir="/images/a_different_directory/"

The rounded_corners parameter allows you to round one or more corners to a certain radius with antialiasing. If you are saving to png format, you can also have the corners be completely transparent. Rounded corners are applied after all resizing, filters, and watermarking has been completed.

There are a number of options for this parameter that empower you with a great deal of control. The general syntax for this parameter is rounded_corners="corner_identifier,radius,color" . You can specify any number of comma separated corners, each with their own radius and color information. Corners specified later take precedence over previously specified ones. Here’s a look at each of the sub parameters in more detail:

corner_identifier : This sub parameter can have a value of any one of the following: all , tl , tr , bl , br . If all is used, it will set the preferences for each of the corners.

radius : The radius of the corner. If this is set to 0, the corner will not be rounded. This value defaults to 15 if not specified.

The image type you would like to save the image as. You can easily convert an image of one type to a different image type by specifying this parameter. Simply do not include this parameter or leave the parameter blank ( "" ) to save as the image type of the original image, or specify the save type as one of the following: png , jpg , jpeg , gif

In the example below, the first image is a jpg being saved as a png, and the second image is a png being saved as a gif (notice the chunky gif look).

This is the path to your image, and can be: a full server path, a relative path to your web root directory, a URL, an external URL, or HTML.

The source can be a relative path:

src="/images/example/cow.jpg"

src="images/example/cow.jpg"

src="./../../directory_above_web_root/blah.jpg"

A URL:

src="http://www.your_current_domain.com/images/example/cow.jpg"

An external URL:

src="http://www.an_external_domain.com/blah/example.jpg"

A full server path:

src="/var/www/vhosts/example.com/httpdocs/images/example/cow.jpg"

Or HTML:

src='<p>Some HTML. An image: <img src="/images/example/cow.jpg" alt="" /></p>'

If HTML is passed in, the plugin will attempt to use the src= attribute of the first found image tag. If you are planning on using HTML, it should be minimal, like just an image tag. Additionally, you will most likely need to wrap the value in single quotes, as opposed to double quotes.

Enables text to be added to the manipulated image.

The syntax for this parameter takes the form:
text="the_text,​minimum_dimensions,​font_size,​line_height,​font_color,​font_src,​text_align,​width_adjustment,​position,​offset,​opacity,​shadow_color,​shadow_offset,​shadow_opacity" . Here’s a look at each of the sub parameters in more detail:

the_text : The text to add to the image. HTML entities will automatically be converted to their text equivalents.

minimum_dimensions : This is a pair of comma separated integers that specify the minimum width and height dimensions needed for the text to appear. The default for this sub-parameter is 0,0 (representing minimum_width,minimum_height respectively). Setting a dimensions to 0 (zero) means that there is no minimum (since the default is 0,0 , the text will always appear). If the manipulated image has dimensions that are less than one or both of the dimensions specified, and are not set to zero, then the text will not appear.

font_size : The text font size. The default is 12.

line_height : The line height. This can be an integer (to specify the pixel value, eg: 15 ), or a percentage of the font_size (eg: 120% ). The default is 125% . Similar to CSS, this value can be used to set the text leading.

font_color : The text color. Can be a 3 or 6 digit hexadecimal number (with or without the #). The default is #ffffff .

This parameter will organize the colors used in your image by frequency, and allow you to group them to a certain threshold. The general syntax for this parameter is top_colors="number_of_color_groups_to_return|threshold" . Here are more details for these sub parameters:

number_of_color_groups_to_return : This sub parameter allows you to specify the maximum number of colors you would like to be returned. Colors are grouped depending on the threshold you provide for the second sub parameter. This is useful because instead of returning thousands of colors individually, similar colors are grouped and their average hexadecimal color value is returned.

threshold : This sub parameter can be any value from 0 (very low grouping) to 100 (very high grouping). If no threshold is specified, it will default to 33.

To access the colors, you use the { top_colors } { / top_colors } tag pair. Inside the tag pair, the following two variables are available: { color } (which is the averaged hex color value of the returned color group) and { color_percent } which is a rough estimate of the percentage of the image that the color group represents. Here is what the code for this looks like:

Note : Since this parameter has additional tags that need to be parsed, it should not be used with the `create_tag="yes"` parameter.

Note : The color values of completely transparent pixels are ignored.

When an image is manipulated, a string is generated that reflects the actions that were done to the image. This string is used to ensure the manipulated image is cached to a unique file for the actions that were applied to it. The options for the plugin are "filename" , "directory_name" , and "none" .

The "filename" option is default, and means the unique string will be added to the filename.

unique="filename"

The "directory_name" option creates a folder using the string, and places the manipulated image (with the original filename), inside the folder, thereby preserving the image name.

unique="directory_name"

And finally, the "none" option will not change the filename or create a special folder. Setting this parameter to "none", is not recommended, as it increases the risk of different manipulations of the same image being cached to the same file, causing unexpected results.

unique="none"

This parameter simply returns the relative URL for the image. This can be very useful in certain situations.

Enables a watermark to be added to the manipulated image.

The syntax for this parameter is in the form: watermark="watermark_src|minimum_dimensions|opacity|position|offset|blend" . Let’s take a closer look at the watermark sub parameters:

watermark_src : This is a relative path to the image to be used as the watermark.

minimum_dimensions : This is a pair of comma separated integers that specify the minimum width and height dimensions needed for this watermark to appear. The default for this sub-parameter is 0,0 (representing minimum_width,minimum_height respectively). Setting a dimensions to 0 (zero) means that there is no minimum (since the default is 0,0 , the watermark will always appear). If the manipulated image has dimensions that are less than one or both of the dimensions specified, and are not set to zero, then the watermark will not appear.

opacity : The transparency of the watermark, ranging from 0 (completely transparent) to 100 (completely opaque).

position : This allows you to specify the position of the watermark. There are two ways to do this:

offset : The offset of the watermark after it is positioned in the form offset_x,offset_y . For example, if right,bottom is specified for the position, you may want to provide an offset of -10,-10 to move the watermark 10px to the left and 10px up so the watermark is not placed so snug to the edges. The default offset is 0,0 .

blend : The blend mode affords you the ability to blend the watermark with the image. Currently, there is only one blend mode: multiply . If this option is not specified, or left blank, then no blend mode will be applied.

One of the inherit difficulties of using dynamic watermarks is ensuring that the size of the final image is not too small for the watermark. This can be especially problematic if the images are submitted by users or clients that are not tech savvy. The minimum_dimensions sub parameter helps to mitigate this problem, however “all or nothin’” didn’t seem good enough, so we added the ability to waterfall watermarks for different dimensions. You can pass in multiple configuration options delimited by a # (hash mark). The first configuration option that meets the dimension limitations will be used.

Here is an example of what we like to call “the watermark waterfall.” As you can see below, multiple watermark settings can be specified for various sizes. The first watermark configuration that works for the dimensions is used.

The maximum width you like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero). You can also pass in a percentage of the source image’s width. If a percentage is used, the plugin will convert it to a pixel value and size the image accordingly.