ConfigurationLast updated: 7 November 2025

The Cache Management panel provides comprehensive control over Image Pro's processed image cache system. Unlike the legacy JCOGS Image add-on (which supports a single storage adapter), Image Pro allows you to configure and manage multiple named connections to different storage locations simultaneously.

Overview

Image Pro's cache management system allows you to:

• Monitor cache statistics across all named connections
• Configure multiple named connections to local or cloud storage
• Audit and clear cache contents for specific connections or cache directories
• Set default cache duration and auto-management behaviour
• Switch between connections dynamically using the connection parameter in templates

Named Connections

Named connections allow you to define multiple storage locations for both source images and processed image cache. Each connection has a unique name and can point to either a local filesystem or a cloud storage service (AWS S3, Cloudflare R2, DigitalOcean Spaces, etc.).

Key Benefits

• Flexibility – Store source images on one connection, processed cache on another
• Multiple Cloud Services – Configure connections to different cloud providers simultaneously
• Testing & Staging – Use different connections for development, staging, and production environments
• Performance Optimisation – Choose optimal storage locations based on geographic distribution or cost
• Template Control – Switch connections per-tag using the connection parameter

Connection Types

Image Pro supports the following connection types:

• Local – Filesystem storage on your web server
• AWS S3 – Amazon Simple Storage Service
• Cloudflare R2 – Cloudflare's S3-compatible object storage
• DigitalOcean Spaces – DigitalOcean's object storage service

Creating a New Connection

1. Navigate to Cache Management in the Image Pro Control Panel
2. Click Add New Connection
3. Provide a unique connection name (alphanumeric, underscores allowed)
4. Select the connection type from the dropdown
5. Complete the configuration fields specific to your chosen type
6. Click Save to validate and store the connection

Default Connection

One connection must be designated as the default connection. This connection is used when no connection parameter is specified in an Image Pro tag. The default connection is typically a local filesystem connection for optimal performance.

Local Connection Configuration

Local connections store files on your web server's filesystem.

Required Settings:

• Connection Name – Unique identifier for this connection
• Default Cache Directory – Path relative to web root where processed images are stored (e.g., images/jcogs_img_pro/cache)

Optional Settings:

• Use Full URLs – Generate absolute URLs instead of relative paths to processed images
• Image Path Prefix – Add a CDN or custom prefix to image URLs (only available when "Use Full URLs" is disabled)

Cloud Connection Configuration

Cloud connections require authentication credentials and endpoint configuration. The setup process is similar across all cloud providers but with provider-specific details.

AWS S3 Configuration

Amazon S3 is a widely-used cloud storage service offering excellent performance and reliability.

Required Settings:

• Connection Name – Unique identifier
• Access Key ID – AWS IAM access key
• Secret Access Key – AWS IAM secret key
• Region – AWS region (e.g., us-east-1, eu-west-2)
• Bucket Name – S3 bucket for storing images
• Path Prefix – Optional subdirectory within bucket (e.g., processed-images/)

Optional Settings:

• Custom Endpoint – For S3-compatible services
• Cache Control Headers – Set browser caching behaviour

Cloudflare R2 Configuration

Cloudflare R2 offers S3-compatible storage with no egress fees, making it cost-effective for high-traffic sites.

Required Settings:

• Connection Name – Unique identifier
• Account ID – Cloudflare account ID
• Access Key ID – R2 API access key
• Secret Access Key – R2 API secret key
• Bucket Name – R2 bucket name
• Public URL – Custom domain or R2.dev URL for public access

DigitalOcean Spaces Configuration

DigitalOcean Spaces provides S3-compatible object storage integrated with DigitalOcean infrastructure.

Required Settings:

• Connection Name – Unique identifier
• Access Key – Spaces access key
• Secret Key – Spaces secret key
• Region – Spaces region (e.g., nyc3, sfo2)
• Space Name – Name of your Space
• CDN Endpoint – Optional CDN URL for faster delivery

Cache Statistics

The Cache Management panel displays real-time statistics for each named connection:

• Connection Name – Identifier and type (Local/Cloud)
• Cache Directories – Number of distinct cache directories in use
• Total Images – Count of processed images stored
• Total Size – Disk space consumed by processed images
• Last Audit – Timestamp of most recent cache audit
• Status – Connection validation status (Active/Error)

Statistics are updated each time you visit the Cache Management panel and reflect the current state of the cache log database.

Cache Controls

Each connection may have multiple cache directories created via the cache_dir parameter in templates. The Cache Management panel lists all directories in use and provides controls for each:

Cache Audit

Running a cache audit removes processed images that have exceeded their cache duration (set when the image was processed). This operation:

• Frees disk space by removing expired images
• Synchronises the cache log database with actual filesystem contents
• Does not affect site functionality (expired images are regenerated when next requested)
• Runs automatically based on the audit interval setting (see Advanced Settings)

Cache Clear

Clearing a cache directory removes all processed images from that location. This operation:

• Frees significant disk space
• Forces regeneration of all processed images on next request
• May temporarily impact site performance as cache rebuilds
• Useful when troubleshooting cache issues or after major configuration changes

Use cache clear sparingly – prefer cache audit for routine maintenance.

Cache Settings

Default Cache Duration

Set the default lifetime (in seconds) for processed images before they're considered expired. This setting applies to all connections unless overridden by the cache parameter in a tag.

Recommended Values:

• 2678400 (31 days) – Default, balances cache efficiency with automatic cleanup
• -1 – Perpetual cache (images never expire, similar to CE Image behaviour)
• 0 – Cache disabled (not recommended for production)
• 604800 (7 days) – Aggressive cleanup for sites with frequently changing images

Enable Cache Auto-Management

When enabled, Image Pro monitors the EE File Manager for changes to source images. If a source image is modified, all processed versions are automatically removed from the cache to ensure users see the updated image.

Important Notes:

• Template Caching – If using EE Template Caching or third-party cache systems (Speedy, Rocket), disable auto-management to avoid inconsistencies
• Performance – Auto-management adds minimal overhead to File Manager operations
• Scope – Only affects images managed through EE File Manager, not remote or arbitrary file paths

Best Practices

Connection Strategy

• Default Local – Use local filesystem as default connection for best performance
• Cloud for Scale – Configure cloud connections for high-traffic sites or CDN integration
• Separate Source and Cache – Store source images on one connection, processed cache on another for optimal organisation
• Naming Convention – Use descriptive names (e.g., aws_s3_production, local_dev) for clarity

Cache Maintenance

• Regular Audits – Allow automatic audits to run (default: weekly) to maintain cache efficiency
• Monitor Size – Check cache statistics periodically to ensure disk usage remains reasonable
• Clear on Config Changes – Clear cache after major configuration changes to ensure consistency
• Backup Connections – Document cloud connection configurations for disaster recovery

The Preset Management panel allows you to create, edit, and manage reusable parameter configurations. Presets are a Pro-exclusive feature that streamline template development by letting you define complex image processing configurations once and apply them consistently throughout your site.

Overview

Image Pro's preset system allows you to:

• Define reusable parameter combinations with descriptive names
• Apply consistent image processing across multiple templates
• Override individual preset parameters on a per-tag basis
• Maintain centralised control over common image configurations
• Simplify template code by replacing multiple parameters with a single preset parameter

Understanding Presets

A preset is a named collection of Image Pro parameters that can be applied to any Image Pro tag using the preset parameter. When you apply a preset, all parameters defined in that preset are used as if you had specified them directly in the tag.

Key Benefits

• Consistency – Ensure identical processing for related images across your site
• Maintainability – Update configurations in one place rather than editing multiple templates
• Readability – Replace lengthy parameter lists with meaningful preset names
• Reusability – Define once, use anywhere in your templates
• Flexibility – Override individual preset parameters when needed for specific cases

How Presets Work

When you specify a preset in an Image Pro tag, the add-on loads the preset's parameters and merges them with any parameters you've specified directly in the tag. Direct tag parameters always take precedence over preset parameters, allowing you to override specific settings whilst maintaining the preset's other configurations.

Example:

{exp:jcogs_img_pro:single 
    src="{product_image}" 
    preset="product_thumbnail"
    width="250"
}

In this example, all parameters from the product_thumbnail preset are applied, except width which is overridden to 250 pixels.

Creating a Preset

To create a new preset:

1. Navigate to Preset Management in the Image Pro Control Panel
2. Click Create New Preset
3. Enter a unique preset name (alphanumeric characters, underscores, and hyphens only)
4. Optionally add a description explaining the preset's purpose
5. Define parameters using the parameter builder or JSON editor
6. Click Save Preset to store the configuration

Preset Naming Conventions

Choose descriptive names that indicate the preset's purpose and context:

• Good: blog_hero_banner, product_thumbnail, gallery_lightbox
• Avoid: preset1, test, my_preset

Consider using a naming pattern like {context}_{size_or_purpose} for consistency.

Defining Parameters

Image Pro provides two methods for defining preset parameters: a visual parameter builder and a JSON editor for advanced users.

Using the Parameter Builder

The parameter builder provides a form-based interface for common parameters:

• Dimensions – Width, height, and scaling behaviour
• Format – Output format (JPG, PNG, WebP, AVIF) and quality settings
• Processing – Crop, resize mode, background colour, filters
• Output – Lazy loading, preload priority, CSS classes, attributes
• Cache – Cache directory, duration, connection

Select parameters from the available options and configure their values. The builder validates inputs and provides helpful descriptions for each parameter.

Using the JSON Editor

For advanced configurations or when working with parameters not available in the builder, use the JSON editor. Define parameters as a JSON object:

{
    "width": 800,
    "height": 600,
    "mode": "crop",
    "format": "webp",
    "quality": 85,
    "lazy": "y",
    "class": "img-fluid rounded",
    "cache_dir": "products"
}

The JSON editor supports all Image Pro parameters, including Pro-exclusive options like face_detection_quality and advanced filter configurations.

Available Parameters

Presets support all Image Pro parameters except src (source image path) and preset (to prevent circular references). Refer to the Parameters documentation for a complete list of available options.

Managing Presets

Editing a Preset

To modify an existing preset:

1. Locate the preset in the Preset Management list
2. Click Edit
3. Modify the preset name, description, or parameters
4. Click Save Changes

Changes to a preset affect all templates using that preset immediately (subject to template caching).

Duplicating a Preset

To create a new preset based on an existing one:

1. Locate the preset you want to duplicate
2. Click Duplicate
3. Enter a new preset name
4. Modify parameters as needed
5. Click Save Preset

Duplication is useful when creating variations of similar configurations.

Deleting a Preset

To remove a preset:

1. Locate the preset in the Preset Management list
2. Click Delete
3. Confirm the deletion

Warning: Deleting a preset does not affect existing processed images in the cache, but templates using the deleted preset will fall back to default parameters or explicitly specified tag parameters.

Using Presets in Templates

Basic Usage

Apply a preset using the preset parameter:

{exp:jcogs_img_pro:single 
    src="{featured_image}" 
    preset="hero_banner"
}

Overriding Preset Parameters

Override specific preset parameters by specifying them directly in the tag:

{exp:jcogs_img_pro:single 
    src="{featured_image}" 
    preset="hero_banner"
    width="1400"
    quality="90"
}

In this example, the hero_banner preset is applied, but width and quality are overridden with custom values.

Combining with Named Attributes

Presets work seamlessly with named attributes for complex configurations:

{exp:jcogs_img_pro:single 
    src="{featured_image}" 
    preset="product_detail"
    attr:data-product-id="{entry_id}"
    attr:data-variant="{variant_sku}"
}

Preset Parameter Precedence

When parameters are defined in multiple places, Image Pro applies them in this order (highest to lowest priority):

1. Direct Tag Parameters – Parameters specified in the Image Pro tag
2. Preset Parameters – Parameters defined in the preset
3. Config.php Overrides – Settings defined in EE config.php
4. Control Panel Settings – Site-wide defaults from CP configuration

Best Practices

Preset Strategy

• Purpose-Driven Names – Name presets based on their purpose and context, not technical details
• Avoid Over-Specification – Only define parameters that differ from sensible defaults
• Document Complex Presets – Use the description field to explain non-obvious configurations
• Group Related Presets – Use consistent naming patterns for related presets (e.g., blog_thumbnail, blog_hero, blog_inline)
• Limit Preset Count – Create presets for truly reusable configurations, not one-off variations

Parameter Selection

• Core Settings Only – Include parameters that define the preset's essential characteristics
• Dimension Guidelines – Specify exact dimensions for fixed-size images, use aspect ratios for flexible layouts
• Format Choices – Consider browser compatibility when specifying advanced formats like WebP or AVIF
• Performance Settings – Include lazy loading and preload settings appropriate to the preset's typical usage

Maintenance

• Regular Review – Periodically audit presets to identify unused or outdated configurations
• Version Control – Export preset configurations for backup and version control
• Testing Changes – Test preset modifications on staging before updating production configurations
• Clear Cache After Changes – Clear relevant cache directories after significant preset modifications to ensure consistency

{
    "width": 1200,
    "height": 600,
    "mode": "crop",
    "format": "webp",
    "quality": 85,
    "lazy": "n",
    "preload_critical": "y",
    "class": "hero-image",
    "cache_dir": "blog_heroes"
}

{
    "width": 300,
    "height": 300,
    "mode": "crop",
    "format": "jpg",
    "quality": 80,
    "lazy": "y",
    "class": "product-thumb img-fluid",
    "cache_dir": "products"
}

{
    "width": 1920,
    "height": 1080,
    "mode": "fit",
    "format": "jpg",
    "quality": 90,
    "lazy": "n",
    "class": "gallery-image",
    "attr:data-lightbox": "gallery",
    "cache_dir": "gallery"
}

The Image Processing Defaults panel provides comprehensive control over how Image Pro processes and outputs images. These settings establish site-wide defaults for image manipulation operations, output formats, quality levels, lazy loading behaviour, and operational constraints.

Overview

Image Pro's processing defaults allow you to:

• Set default output formats and quality levels for different image types
• Configure lazy loading and progressive enhancement strategies
• Define fallback images for missing or failed source images
• Establish operational limits for source image processing
• Control automatic image adjustments and optimisations

All settings can be overridden on a per-tag basis using parameters or via presets.

Output Format Settings

Control the default output format for processed images and how Image Pro handles format conversion.

Default Image Format

The default format used when no format parameter is specified in a tag. Image Pro supports JPG, PNG, WebP, AVIF, and GIF formats.

Format Options:

• JPG (default) – Best for photographs and images with many colours. Excellent compression with acceptable quality loss. Universal browser support.
• PNG – Best for graphics, logos, and images requiring transparency. Lossless compression but larger file sizes. Universal browser support.
• WebP – Modern format offering superior compression for both lossy and lossless images. Image Pro automatically substitutes JPG/PNG for browsers lacking WebP support.
• AVIF – Next-generation format with exceptional compression efficiency. Image Pro automatically substitutes WebP or JPG for browsers lacking AVIF support.
• GIF – Legacy format for simple animations. Not recommended for static images (use PNG or WebP instead).

Recommended Values:

• jpg – Safe default with universal browser support
• webp – Modern sites targeting recent browsers
• avif – Cutting-edge sites with progressive enhancement strategy

SVG Passthrough

When enabled, SVG source images bypass processing and are served directly. This preserves vector quality and eliminates unnecessary processing overhead.

Recommended Setting:

• Enabled (default) – SVG files retain their scalability and small file size
• Disabled – Force SVG rasterisation to specified dimensions (useful when you need pixel-perfect control)

Animated GIF Handling

Control whether animated GIFs are preserved during format conversion or treated as static images.

Options:

• Preserve Animation (default) – Animated GIFs remain animated when converted to formats supporting animation
• First Frame Only – Extract first frame only, treating animated GIFs as static images

Quality Settings

Configure default quality levels for different output formats. Quality affects both file size and visual fidelity.

JPG Quality

Quality level for JPG output, ranging from 0 (lowest quality, smallest file) to 100 (highest quality, largest file).

Recommended Values:

• 85 (default) – Excellent balance between quality and file size for most photographs
• 90-95 – High-quality images where fidelity is critical
• 75-80 – Aggressive compression for bandwidth-constrained environments
• 60-70 – Thumbnail images where slight quality loss is acceptable

PNG Compression Level

PNG compression level, ranging from 0 (no compression) to 9 (maximum compression). Higher values produce smaller files but take longer to process.

Recommended Values:

• 6 (default) – Good balance between compression efficiency and processing time
• 9 – Maximum compression for production builds (slower processing)
• 3-5 – Faster processing during development

WebP Quality

Quality level for WebP output (lossy compression), ranging from 0 to 100.

Recommended Values:

• 85 (default) – Excellent quality with superior compression compared to equivalent JPG
• 75-80 – Aggressive compression with minimal perceptible quality loss

AVIF Quality

Quality level for AVIF output, ranging from 0 to 100.

Recommended Values:

• 75 (default) – Exceptional compression with excellent visual quality
• 60-70 – Very aggressive compression whilst maintaining acceptable quality

Dimension Defaults

Set default dimensions and scaling behaviour when explicit dimensions aren't specified in tags.

Default Width

Default width in pixels when no width parameter is specified.

Recommended Values:

• 800 (default) – Suitable for most content images in modern responsive layouts
• 1200 – High-resolution displays or hero images
• 400-600 – Thumbnail or sidebar images

Default Height

Default height in pixels when no height parameter is specified.

Recommended Values:

• 600 (default) – Balanced aspect ratio with 800px default width
• Auto – Maintain source aspect ratio (leave blank or set to 0)

Allow Scale Larger

Control whether Image Pro can scale images larger than their original dimensions.

Options:

• Disabled (default) – Images are never scaled beyond original dimensions (preserves quality)
• Enabled – Allow upscaling when requested dimensions exceed source size (may reduce quality)

Default Background Colour

Hexadecimal colour value used for letterboxing, padding, or replacing transparency. Specified without the # symbol.

Recommended Values:

• ffffff (default) – White background, suitable for most sites
• 000000 – Black background for dark-themed sites
• f5f5f5 – Light grey, less harsh than pure white

Lazy Loading Settings

Configure default lazy loading behaviour to optimise page load performance.

Enable Lazy Loading

When enabled, images are loaded only when they enter (or approach) the viewport. This significantly improves initial page load times.

Options:

• Disabled (default) – All images load immediately with the page
• Enabled – Images load on-demand as users scroll

Lazy Loading Mode

The strategy used for lazy loading implementation when lazy loading is enabled.

Mode Options:

• LQIP (Low Quality Image Placeholder, default) – Show blurred preview whilst full image loads
• Native – Use browser's native lazy loading (loading="lazy" attribute)
• Blank – Show blank placeholder until image loads
• Colour – Show solid colour placeholder (uses default background colour)

Mode Comparison:

• LQIP – Best user experience, slight processing overhead for preview generation
• Native – Minimal overhead, relies on browser implementation (good modern browser support)
• Blank/Colour – Simplest implementation, may cause layout shift

Progressive Enhancement

When enabled with LQIP mode, generates progressively-encoded JPEGs that render incrementally as they download.

Options:

• Disabled (default) – Standard baseline JPEGs
• Enabled – Progressive JPEGs that improve perceived load time

Default Preload Critical

Whether to add rel="preload" hints for above-the-fold images by default.

Options:

• Disabled (default) – No preload hints added
• Enabled – Add preload hints to prioritise critical images

Recommended Usage:

• Keep disabled globally
• Enable selectively via preload_critical="y" parameter for hero images and above-the-fold content
• Use sparingly – too many preload hints reduce effectiveness

Fallback Image Settings

Configure how Image Pro handles missing or failed source images.

Enable Default Fallback Image

When enabled, Image Pro generates a placeholder image if the source image is missing or inaccessible.

Options:

• Disabled – Return empty result or error for missing images
• Solid Colour (default) – Generate solid colour placeholder
• Local File – Use specified local fallback image
• Remote URL – Fetch and use specified remote fallback image

Fallback Image Colour

Hexadecimal colour for generated placeholder images when using solid colour fallback mode.

Recommended Values:

• dddddd (default) – Light grey, indicates missing image without being intrusive
• f0f0f0 – Very light grey, subtle indication
• cccccc – Medium grey, more prominent

Fallback Image Local Path

Path to a local image file to use as fallback (relative to EE base path). Only used when fallback mode is set to "Local File".

Example:

• images/defaults/placeholder.jpg
• assets/img/no-image-available.png

Fallback Image Remote URL

Full URL to a remote image to use as fallback. Only used when fallback mode is set to "Remote URL".

Example:

• https://via.placeholder.com/800x600/dddddd/999999
• https://cdn.example.com/defaults/placeholder.jpg

Automatic Adjustments

Configure automatic image enhancement features.

Enable Auto-Sharpen

Apply subtle sharpening to processed images to compensate for softening that occurs during resize operations.

Options:

• Enabled (default) – Automatically sharpen resized images
• Disabled – No automatic sharpening applied

Recommended Setting:

• Keep enabled for most use cases – the effect is subtle and improves perceived image quality
• Disable if you prefer full manual control or are applying custom filters

Enable Auto-Adjust

Automatically adjust exposure, contrast, and colour balance to optimise image appearance.

Options:

• Disabled (default) – No automatic adjustments
• Enabled – Apply automatic image enhancement

Recommended Setting:

• Keep disabled for most use cases – automatic adjustments can produce unexpected results
• Consider enabling for user-generated content where image quality varies significantly

Operational Limits

Set constraints on source image processing to prevent resource exhaustion and ensure reliable operation.

Maximum Source Image Size

Maximum filesize (in megabytes) for source images. Images exceeding this limit are rejected.

Recommended Values:

• 25 (default) – Suitable for most hosting environments
• 50-100 – High-memory servers or sites handling professional photography
• 10-15 – Shared hosting or resource-constrained environments

Maximum Image Dimension

Maximum width or height (in pixels) for source images. Larger dimensions are rejected to prevent excessive memory usage.

Recommended Values:

• 3000 (default) – Accommodates most high-resolution images
• 5000 – Professional photography or print-quality sources
• 2000 – Conservative limit for standard web content

Minimum PHP Memory

Minimum PHP memory limit (in megabytes) required for image processing. Image Pro checks available memory before processing large images.

Recommended Values:

• 256 (default) – Standard PHP configuration
• 512 – Processing very large images or complex operations
• 128 – Minimum viable for basic image processing

Minimum PHP Process Time

Minimum PHP max_execution_time (in seconds) required for processing. Ensures sufficient time for complex operations.

Recommended Values:

• 30 (default) – Standard PHP timeout
• 60 – Processing very large images or slow remote sources
• 120 – Batch processing or development environments

Remote Connection Timeout

Maximum time (in seconds) to wait when fetching remote images before giving up.

Recommended Values:

• 20 (default) – Reasonable timeout for most remote sources
• 10 – Faster failure for unavailable sources
• 30-60 – Slow or unreliable remote sources

User Agent String

User-agent header sent when fetching remote images. Some servers require valid user-agent strings.

Default Value:

• Mozilla/5.0 (Macintosh; Intel Mac OS X 15.7; rv:144.0) Gecko/20100101 Firefox/144.0

Usage Notes:

• Most sites work fine with the default value
• Update if specific remote sources reject the default user-agent
• Use a realistic browser user-agent string for best compatibility

Output Behaviour

Control how Image Pro generates output markup and handles edge cases.

Class Consolidation

When enabled, duplicate CSS classes in the output are automatically removed.

Options:

• Enabled (default) – Remove duplicate classes
• Disabled – Output all specified classes as-is

HTML Decoding

Automatically decode HTML entities in parameter values (useful when parameters come from EE variables or database fields).

Options:

• Enabled (default) – Decode HTML entities in parameters
• Disabled – Use parameter values exactly as provided

Always Output Full URLs

Generate absolute URLs for all image paths instead of relative paths.

Options:

• Disabled (default) – Use relative paths for local images
• Enabled – Always generate absolute URLs

When to Enable:

• Content distributed via RSS/feeds
• Email templates
• External API consumption
• Sites using CDNs (combine with path prefix)

The System Settings panel provides control over Image Pro's operational behaviour, including enable/disable controls, action links, debugging features, and integration options. These settings affect how Image Pro functions within your ExpressionEngine installation.

Overview

Image Pro's system settings allow you to:

• Enable or disable the add-on globally without uninstalling
• Generate direct action links for image processing
• Enable debugging to troubleshoot processing issues
• Configure cache audit behaviour and scheduling
• Control browser capability detection

These settings typically require attention only during initial setup or when troubleshooting specific issues.

Enable/Disable Controls

Enable Image Pro

Master control to enable or disable Image Pro add-on functionality across your entire site.

Options:

• Enabled (default) – Image Pro processes images normally
• Disabled – All Image Pro tags return empty output without processing

Use Cases:

• Temporary Disable: Quickly disable image processing without removing tags from templates
• Maintenance Mode: Disable during server maintenance or migrations
• Troubleshooting: Isolate Image Pro from other site issues
• Staging Sites: Disable on development environments whilst maintaining template compatibility

Speedy Escape

Enable ultra-fast tag parsing mode that bypasses normal parameter processing. Only recommended for experienced users optimising high-performance sites.

Options:

• Disabled (default) – Normal parameter processing with full validation
• Enabled – Skip parameter validation for maximum performance

Important Notes:

• Performance Gain: Minimal in most scenarios (microseconds per tag)
• Risk: Invalid parameters may cause unpredictable behaviour or errors
• Recommendation: Keep disabled unless you've profiled and confirmed parameter processing is a bottleneck
• Use Only When: You're certain all Image Pro tags use valid, tested parameters

Action Links

Action links are direct URLs that trigger image processing without requiring template parsing. They're useful for dynamic image generation, API integration, and external applications.

Enable Action Links

Allow Image Pro to generate and respond to action link URLs.

Options:

• Disabled (default) – Action links are not generated or processed
• Enabled – Generate action links when requested

Security Considerations:

• Action links contain encoded parameters that could be modified
• Enable only if you need this functionality
• Monitor server resources if action links are publicly accessible
• Consider rate limiting at server level for production sites

Append Path to Action Links

Include the full processed image path in action link URLs for improved SEO and clarity.

Options:

• Disabled (default) – Action links use query string parameters only
• Enabled – Append processed image path to URL

Example URLs:

• Disabled: https://example.com/?ACT=123&params=encoded_data
• Enabled: https://example.com/?ACT=123&params=encoded_data/images/cache/product-800x600.jpg

Cache Auditing

Enable Cache Audit

Enable automatic periodic cache auditing to remove expired processed images.

Options:

• Disabled (default) – Cache audits run only when manually triggered via Control Panel
• Enabled – Automatic cache audits run based on audit interval

How It Works:

• Image Pro checks whether an audit is due each time a page with Image Pro tags loads
• Audits run in the background without blocking page rendering
• Only images exceeding their cache duration are removed
• Audit timestamps are tracked per connection in the cache log database

Default Cache Audit Interval

Time period (in seconds) between automatic cache audits when cache audit is enabled.

Recommended Values:

• 604800 (7 days, default) – Weekly audits suitable for most sites
• 86400 (1 day) – Daily audits for high-traffic sites with frequent image changes
• 2592000 (30 days) – Monthly audits for stable sites with infrequent changes
• 43200 (12 hours) – Aggressive auditing for development or testing environments

Considerations:

• More frequent audits keep cache cleaner but add processing overhead
• Balance audit frequency with cache duration settings
• Audit intervals shorter than cache durations provide minimal benefit

Debugging and Diagnostics

Enable Debugging

Enable detailed debugging output to help diagnose image processing issues.

Options:

• Disabled (default) – Normal operation without debug output
• Enabled – Generate detailed processing information

Debug Information Includes:

• Parameter values received and processed
• File paths and URLs being accessed
• Image processing pipeline stages and timings
• Cache hit/miss information
• Error messages and stack traces
• Memory usage and resource consumption

Important Notes:

• Security: Debug output may expose server paths and configuration details – never enable on production sites
• Performance: Debugging adds processing overhead
• Output Location: Debug messages appear via ee('jcogs_img:Utilities')->debug_message() method
• Development Only: Use exclusively in development or staging environments

Enable Browser Capability Check

Enable automatic browser capability detection to serve optimal image formats based on client support.

Options:

• Disabled (default) – Serve requested format without browser detection
• Enabled – Automatically detect browser capabilities and substitute compatible formats

How It Works:

• Image Pro examines request headers (Accept header) to determine supported formats
• If browser doesn't support requested format (e.g., WebP, AVIF), Image Pro substitutes a compatible format
• Fallback hierarchy: AVIF → WebP → JPG/PNG
• Format substitution is transparent to templates

Recommended Setting:

• Enable this feature to safely use modern formats like WebP and AVIF
• With browser checking enabled, you can specify WebP or AVIF as defaults knowing older browsers will receive compatible formats automatically
• Disable only if you have a custom format handling strategy or need absolute format predictability

Cache Log Management

Cache Log Preload Threshold

Maximum number of cache log entries to preload into memory for performance optimisation.

Recommended Values:

• 10000 (default) – Suitable for most sites
• 25000-50000 – Sites with extensive image libraries and high memory limits
• 5000 – Memory-constrained environments or smaller sites
• 0 – Disable preloading (rely on database queries for each cache lookup)

How It Works:

• Image Pro can preload recent cache entries into memory on first Image Pro tag execution
• Subsequent cache lookups check memory first before querying database
• Improves performance when multiple Image Pro tags appear on same page
• Trade-off between memory consumption and database query reduction

Performance Impact:

• Preloading 10,000 entries uses approximately 2-5MB memory
• Reduces database queries by 80-90% on pages with many Image Pro tags
• Most beneficial on high-traffic pages with numerous processed images

The Advanced Settings panel provides fine-grained control over specialised Image Pro behaviours, edge case handling, and technical optimisations. These settings should typically remain at their defaults unless you're addressing specific technical requirements or troubleshooting unusual scenarios.

Overview

Image Pro's advanced settings allow you to:

• Configure CSS class and style attribute consolidation
• Control attribute variable expansion behaviour
• Customise cache filename generation
• Adjust PHP resource limit checking
• Fine-tune remote image handling

Most users will never need to modify these settings. They exist to handle edge cases and provide maximum flexibility for complex implementations.

Output Consolidation

Class Consolidation Default

Control whether duplicate CSS classes are automatically removed from generated image tags.

Options:

• Enabled (default) – Automatically remove duplicate class names
• Disabled – Output all specified classes, including duplicates

How It Works:

• When multiple sources add the same class (preset + tag parameter + template variable), duplicates are removed
• Classes are space-separated and de-duplicated whilst preserving order
• This setting provides the default behaviour; override per-tag using class_consolidation parameter

Example:

• Input: class="img-fluid rounded img-fluid"
• Consolidated: class="img-fluid rounded"
• Not Consolidated: class="img-fluid rounded img-fluid"

When to Disable:

• You're using CSS frameworks that rely on class repetition (rare)
• Debugging class inheritance from multiple sources
• Maintaining exact output for testing or comparison purposes

Attribute Variable Expansion Default

Control whether EE template variables within attribute values are automatically parsed and expanded.

Options:

• Enabled (default) – Parse variables in attribute values
• Disabled – Use attribute values literally without variable parsing

How It Works:

• When enabled, variables like {entry_id} or {custom_field} within attribute values are parsed by ExpressionEngine
• Applies to all custom attributes added via attr:* parameters
• This setting provides the default behaviour; override per-tag using attr_expand parameter

Example:

• Template: attr:data-entry-id="{entry_id}"
• Expanded: data-entry-id="12345"
• Not Expanded: data-entry-id="{entry_id}"

When to Disable:

• You need literal curly braces in attribute values (e.g., JSON data attributes)
• Performance optimisation when no variables are used in attributes
• Preventing potential parsing conflicts with JavaScript template syntax

Cache Filename Handling

Default Filename Separator

Character(s) used to separate components in generated cache filenames.

Default Value:

• __ (double underscore) – Clearly distinguishes filename components

Alternative Values:

• - (hyphen) – More URL-friendly, slightly harder to parse visually
• _ (single underscore) – Compact but may conflict with underscores in source filenames
• . (period) – Extremely compact but can confuse file extension detection

Filename Structure:

• Cache filenames typically contain: source name, dimensions, format, hash
• Example with __: product__800x600__webp__a1b2c3d4.webp
• Example with -: product-800x600-webp-a1b2c3d4.webp

When to Change:

• URL aesthetics or SEO requirements prefer different separators
• Integration with external systems that have filename requirements
• Avoiding conflicts with characters in source filenames

Maximum Source Filename Length

Maximum number of characters from the source filename to include in cache filenames. Longer source names are truncated.

Recommended Values:

• 100 (default) – Balances readability with filesystem compatibility
• 50-75 – Conservative limit for very long source filenames or filesystem constraints
• 150-200 – Preserve more of the source filename for debugging (ensure filesystem supports longer names)

Filesystem Limits:

• Most modern filesystems support 255-character filenames
• Cache filenames include source name + separator + dimensions + format + hash + extension
• Setting too high may cause issues on filesystems with shorter limits
• Truncation preserves file extension and adds processing details

Include Source in Filename Hash

Control whether the source filename is included when generating the cache filename hash component.

Options:

• Enabled (default) – Source filename affects hash value
• Disabled – Hash based only on processing parameters

How It Works:

• The hash component ensures unique cache filenames for different source/parameter combinations
• Including source filename means different sources with identical processing create separate cache files
• Excluding source filename allows parameter-based cache sharing across similar source images

Impact:

• Enabled: More cache files, clearer source attribution, no risk of collision
• Disabled: Potential cache reuse across sources, slightly smaller cache, requires parameter uniqueness

When to Disable:

• You want to share processed versions across multiple identical source images with different names
• Reducing cache size is critical and you're certain parameter combinations are unique
• Advanced cache optimisation scenarios (requires thorough testing)

PHP Resource Validation

Default Minimum PHP RAM

Minimum PHP memory_limit (in megabytes) required for image processing. Image Pro checks available memory before processing.

Recommended Values:

• 256 (default) – Standard PHP memory configuration
• 512 – Large images or complex processing operations
• 128 – Minimal viable for basic processing (may limit source image size)

How It Works:

• Before processing, Image Pro checks PHP's memory_limit setting
• If available memory is below this threshold, processing may be skipped or limited
• This prevents memory exhaustion errors during processing
• Set based on your server's PHP configuration and expected image sizes

Default Minimum PHP Process Time

Minimum PHP max_execution_time (in seconds) required for processing. Ensures sufficient time for complex operations.

Recommended Values:

• 30 (default) – Standard PHP timeout, suitable for most processing
• 60 – Large images or slow remote sources
• 120 – Complex batch operations or development environments
• 300 – Extensive processing or very large source images (use with caution)

Considerations:

• Image Pro attempts to extend execution time for individual processing operations
• This setting defines minimum acceptable baseline before attempting processing
• Server-level limits may override PHP ini settings
• Balance against user experience – very long timeouts may indicate processing issues

Remote Image Handling

Default PHP Remote Connection Time

Maximum time (in seconds) to wait when fetching remote images before timing out.

Recommended Values:

• 20 (default) – Reasonable timeout for most remote sources
• 10 – Faster failure for unavailable sources, better user experience
• 30-45 – Slow or unreliable remote sources, international connections
• 60+ – Development/debugging only (production timeouts should be shorter)

Impact on User Experience:

• Shorter timeouts mean faster page loads when remote sources are unavailable
• Longer timeouts increase success rate for slow connections but delay page rendering
• Failed fetches can fall back to configured fallback images
• Successfully fetched images are cached, eliminating timeout delays on subsequent requests

Default User Agent String

User-agent header sent when fetching remote images. Some remote servers require recognisable user-agent strings.

Default Value:

• Mozilla/5.0 (Macintosh; Intel Mac OS X 15.7; rv:144.0) Gecko/20100101 Firefox/144.0

When to Change:

• Remote servers reject or rate-limit the default user-agent
• You need to identify your site specifically in remote server logs
• Compliance with API terms requiring specific user-agent identification
• Testing different user-agent handling by remote sources

Best Practices:

• Use realistic browser user-agent strings for maximum compatibility
• Avoid empty or generic user-agents (may be blocked by security filters)
• Include version numbers to appear as legitimate browser traffic
• Consider custom user-agent like YourSite/1.0 (+https://yoursite.com) if identifying your site is important

Legacy CE Image Compatibility

CE Image Remote Directory Mode

Configure directory structure when processing remote images for CE Image compatibility mode.

Options:

• made (default) – Store remote images in made/remote/ subdirectory
• remote – Store remote images in remote/ subdirectory
• root – Store remote images in root cache directory

Purpose:

• Provides compatibility with sites migrating from CE Image
• Matches CE Image's directory organisation for remote image cache
• Maintains existing URLs when transitioning from CE Image to Image Pro

Recommendation:

• Keep default made unless specifically migrating from CE Image
• Match your previous CE Image configuration if maintaining URL compatibility is required
• After migration is complete, this setting has minimal ongoing impact