Image processing and media #

This page is for system administrators and support staff at a hosting company. It answers: which image libraries and programs an Exponential server needs, how images and their variations are stored, which uploads are accepted, what Velocity adds, and which PHP and permission settings affect media. The settings are in settings/image.ini; the operator's summary is chapter 10.8.

Contents #

1. What the server needs
2. The converters and their order
3. Image aliases and storage
4. Uploads: types, validation and limits
5. Velocity's image pipeline
6. Permissions for media
7. Commands
8. Checklist
9. Related pages

What the server needs #

The setup wizard looks for convert in /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin, and switches the ImageMagick converter off when it finds none. Check with convert -version and php --ri gd.

The converters and their order #

settings/image.ini, [ImageConverterSettings] ImageConverters[] lists the converters in order; the first that can handle an image is used:

ImageConverters[]
ImageConverters[]=GD
ImageConverters[]=ImageMagick

• GD comes first: it is built into PHP, converts in process without starting a program per image, and reads and writes JPEG, PNG, GIF and WBMP.
• ImageMagick is the fallback for formats GD cannot read (for example PSD, TIFF, PDF or WebP) and for filters only it supports. It takes over completely when GD is missing or [GD] IsEnabled=false.
• [ImageMagick] ExecutablePath (empty: the search path) and Executable (convert) find the program.

To prefer ImageMagick, override the list in settings/override/image.ini.append.php with ImageMagick first.

[ImageConverterSettings] LockTimeout (shipped 60) is how many seconds a process waits while another generates the same alias; after that the waiting process ends the other one and generates the alias itself.

Image aliases and storage #

• Uploaded images live in the site's storage directory, var/<site var dir>/storage/images (image.ini [FileSettings] PublishedImages=images; drafts and archived versions in images-versioned).
• Their variations, the aliases, are generated on first use. [AliasSettings] AliasList[] names them (reference, small, tiny, medium, large, rss and those of the site's design).
• [OutputSettings] AllowedOutputFormat[] lists the formats pages may show: JPEG, PNG, WebP and GIF.
• Temporary image files go to the imagetmp subdirectory of the cache ([FileSettings] TemporaryDir).

For a host this means: image storage grows with uploads and with the number of aliases a design defines, and the first view of a new page can cost CPU while its variations are made.

Uploads: types, validation and limits #

image.ini [ImageUploadSettings] decides which uploaded files are accepted as images, for every way in (the edit form, the upload module, the rich text editor, the AJAX uploader, WebDAV, imports):

Serve SVG files with the headers in SVG images.

Upload size is PHP's: upload_max_filesize and post_max_size must be as large as the largest file customers upload; Exponential does not test them. State the limit in the plan and set it in the pool (PHP settings for Exponential).

Velocity's image pipeline #

When Velocity serves the site, it answers static files itself and can resize images on request (Velocity static files and images):

• ?w=400 or ?h=300 on an image URL resizes it, never above the source's size; AVIF or WebP is chosen for browsers that accept them; Save-Data: on lowers the quality.
• Results are cached; Q.images.cache.maxSize (shipped 268435456 bytes) bounds the cache.
• It needs PHP's GD (without it the original is served), WebP support in GD for WebP, and imageavif() (PHP 8.1 with libavif) for AVIF.

This is separate from the kernel's image aliases above, which work under every web server.

Permissions for media #

image.ini [FileSettings] has its own modes for image directories and files, shipped world-writable:

# settings/override/image.ini.append.php
[FileSettings]
DirPermissions=0770
ImagePermissions=0660

image.ini itself prefers 0770 and 0660 with the right user and group. Every process that may generate an alias (the web PHP, Velocity's workers, cron and console) must be able to write the storage directory; see Writable directories and permissions.

Commands #

After an alias definition changes, remove the generated variations so they are made again:

php bin/php/cache.php imagealias clear --allow-root-user

The same is available as exp:cache imagealias in the console. Images and their variations are part of var/storage, which every backup must include (What to back up).

Checklist #

• To do: GD (with FreeType) and ImageMagick installed; convert -version and php --ri gd answer.
• To do: fileinfo loaded in the web and the command line PHP.
• To do: system not in disable_functions where ImageMagick is used.
• To do: Upload limits set and stated in the plan.
• To do: image.ini [FileSettings] modes hardened.
• To do: var/storage included in backups and in disk monitoring.

Related pages #

• Chapter 10.8: Search indexing and image handling
• Media and uploads (for editors)
• Velocity static files and images
• Sizing memory, CPU and disk
• CDN
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.