Pageimages / Pageimage / $page->images

Pageimage extends Pagefile, so all Pagefile properties (url, filename, basename, description, tags, filesize, created, modified, etc.) are available in addition to the image-specific ones below.

Dimensions and appearance

Focus

Variations

WebP

Inherited from Pagefile

size($width, $height, $options)

The primary resize/crop method. Returns a new Pageimage variation — the original is never modified. Variations are created once and cached on disk; subsequent calls with the same dimensions return the cached file.

// Exact size (cropped to fit)
$thumb = $image->size(400, 300);

// Proportional — specify 0 for the dimension to auto-scale
$thumb = $image->size(400, 0);  // width=400, height auto
$thumb = $image->size(0, 300); // height=300, width auto

// Cropping direction as a string
$thumb = $image->size(400, 300, 'north');     // crop from top
$thumb = $image->size(400, 300, 'southeast');  // crop from bottom-right

// Array of options
$thumb = $image->size(400, 300, [
    'cropping'   => 'center',
    'quality'    => 80,
    'upscaling'  => false,
    'sharpening' => 'medium',
]);

// Shortcuts for the $options argument:
$thumb = $image->size(400, 300, 'north');     // string -> cropping
$thumb = $image->size(400, 300, 80);          // int    -> quality
$thumb = $image->size(400, 300, false);        // bool   -> upscaling

// Use a predefined size from $config->imageSizes 3.0.151+
$thumb = $image->size('landscape');

// If the requested size already matches the original, the original is returned
// (same object, not a clone) unless allowOriginal is explicitly disabled.

Key options:

Note: ProcessWire does not keep separate copies for different quality or upscaling values. If a variation at the same dimensions already exists, changing quality/upscaling has no effect unless you first call removeVariations() or pass forceNew => true.

width($n, $options) / height($n, $options)

Resize to a specific width (or height) with proportional dimensions. When called with no argument, returns the current width (or height) in pixels.

$thumb = $image->width(600);    // new Pageimage at 600px wide, height proportional
$px    = $image->width();       // int — width of this image

$thumb = $image->height(400);  // new Pageimage at 400px tall, width proportional
$px    = $image->height();     // int — height of this image

crop($x, $y, $width, $height, $options)

Crop a rectangle from the image starting at pixel position ($x, $y) with the given width and height. Returns a new Pageimage.

$crop = $image->crop(100, 200, 150, 100);
echo "<img src='$crop->url' />";

maxWidth($n, $options) / maxHeight($n, $options)

Return an image no larger than the given width (or height). If the source is already smaller, the original is returned (not a copy). Upscaling is disabled automatically.

$small = $image->maxWidth(1024);
$thumb = $image->maxHeight(300, ['quality' => 80]);

maxSize($width, $height, $options)

Return an image constrained within both a maximum width and height (no cropping). If the source already fits, the original is returned when allowOriginal is true; otherwise a variation is created.

$fit = $image->maxSize(800, 600);
$fit = $image->maxSize(800, 600, ['allowOriginal' => true]);

sizeName($name, $options)

Resize using a predefined size from $config->imageSizes. Each named size must contain at least width and height, and may include any other size() option.

// In site/config.php: $config->imageSizes = ['landscape' => ['width' => 600, 'height' => 300]];
$thumb = $image->sizeName('landscape');

// Override a predefined option at call time
$thumb = $image->sizeName('landscape', ['quality' => 75]);

hidpiSize($width, $height, $options)

Same as size() but the resulting variation is tagged with a -hidpi suffix and uses hidpiQuality instead of quality.

$retina = $image->hidpiSize(400, 300);

getVariations($options)

Returns a Pageimages collection of all size variations of this image. Use $options to filter by width, height, suffix, name, etc.

// All variations
$vars = $image->getVariations();
echo count($vars) . " variations\n";

// Variations at exactly 200px wide
$vars = $image->getVariations(['width' => 200]);

// Variations with a specific suffix
$vars = $image->getVariations(['suffix' => 'hidpi']);

// Get variation info arrays instead of Pageimage objects
$infos = $image->getVariations(['info' => true]);
foreach($infos as $name => $info) {
    echo "$info[width]x$info[height] — $info[url]\n";
}

Filter options: width, height, width>=, width<=, height>=, height<=, suffix (string), suffixes (array), noSuffix, noSuffixes, name, noName, regexName, info (bool), verbose (bool|int).

isVariation($basename, $options)

Check whether a given filename is a variation of this image. Returns an info array if it is, or false if not. The returned array includes original, url, path, width, height, actualWidth, actualHeight, crop, suffix, and (for variations-of-variations) parent and suffixAll.

$info = $image->isVariation('photo.200x200.jpg');
if($info) {
    echo "Variation: {$info['width']}x{$info['height']}, suffixes: " . implode(',', $info['suffix']);
}

rebuildVariations($mode, $suffix, $options)

Delete and recreate existing variations. Useful after replacing an original image or changing global resize settings.

// Safe rebuild: only non-suffix, non-crop variations (default)
$result = $image->rebuildVariations();
echo "Rebuilt: " . implode(', ', $result['rebuilt']);
echo "Skipped: " . implode(', ', $result['skipped']);

// Rebuild all variations except those with the 'hidpi' suffix
$result = $image->rebuildVariations(2, ['hidpi']);

Returns an associative array with rebuilt, skipped, errors, and reasons (each an array).

removeVariations($options)

Delete all (or filtered) variations of this image. Accepts the same filter options as getVariations(), plus:

• dryRun (bool): Return the filenames that would be deleted without deleting.
• getFiles (bool): Return an array of deleted filenames.

// Remove all variations
$image->removeVariations();

// Dry run — see what would be deleted
$files = $image->removeVariations(['dryRun' => true]);

// Remove only variations wider than 1000px
$image->removeVariations(['width>=' => 1000]);

setOriginal($image) / getOriginal()

setOriginal marks this image as a variation of the given Pageimage. getOriginal returns the original Pageimage if this is a variation, or null if this is the original.

$thumb = $image->size(200, 200);
$orig  = $thumb->getOriginal();   // returns $image
$orig  = $thumb->original;         // same via property

focus($top, $left, $zoom)

Get or set the focus area used by size() when both width and height are specified and the focus option is true (the default). Focus ensures the important part of the image is retained during cropping.

• Get (no arguments): returns an array with top, left, zoom, default, and str.
• Set (two numbers): focus(25, 70) -> 25 % from top, 70 % from left.
• Set (string): "25 70" or "top=25%, left=70%" or "25 70 30" (with zoom).
• Set (array): ['top' => 25, 'left' => 70] or [25, 70].
• Check (true): returns true if custom focus exists, false if default.
• Pixel mode (1): returns pixel coordinates instead of percentages.
• Unset (false): remove focus, reverting to default (center).

// Read focus
$focus = $image->focus();
echo "Focus: $focus[top]% top, $focus[left]% left";

// Set focus (percentages)
$image->focus(30, 70);

// Check if custom focus is set
if($image->focus(true)) { /* custom focus exists */ }

// Get focus as pixel coordinates
$px = $image->focus(1);
echo "Center at {$px['left']}, {$px['top']} px";

// Unset focus (revert to default center)
$image->focus(false);

// Set via string
$image->focus("top=30%, left=70%, zoom=0%");

Focus is stored in the image's filedata and persists across page saves.

webp($options)

Returns a PagefileExtra object representing the WebP version of this image. The WebP file is created on-demand when you access ->url or ->filename.

$webp = $image->webp();

if($webp->exists()) {
    echo "<source srcset='$webp->url' type='image/webp'>";
}

// File size comparison (the WebP may be smaller)
echo "Original: {$image->filesize} bytes, WebP: {$webp->filesize} bytes";
echo "Savings: {$webp->savingsPct}";

$options overrides 3.0.229+: useSrcUrlOnSize (bool, default from $config->webpOptions), useSrcUrlOnFail (bool), quality (int, default 90).

When $config->webpOptions['useSrcUrlOnSize'] is true (the default) and the WebP file is larger than the original, ->url falls back to the original image URL automatically. Likewise useSrcUrlOnFail falls back to the original URL if WebP creation fails.

hasWebp / webpUrl / webpFilename

Convenience property shortcuts:

if($image->hasWebp) {
    echo $image->webpUrl;       // URL to the .webp file
    echo $image->webpFilename;  // disk path to the .webp file
}

Creating WebP during resize

Pass webpAdd => true to size() to create a .webp variation alongside the primary format:

$thumb = $image->size(600, 400, ['webpAdd' => true]);
// $thumb->url           -> 600x400.jpg URL
// $thumb->webp->url     -> 600x400.webp URL

render($markup, $options)

Renders markup for this image using a template string with placeholder replacements. When called on a Pageimages collection, it iterates all images. Available placeholders:

$image = $page->images->first();

// Default:<img src='{url}' alt='{alt}' />
echo $image->render();

// Custom markup
echo $image->render("<img class='pw-image' src='{url}' alt='{alt}'>");

// Resize + custom markup
echo $image->render("<img src='{url}' alt='{alt}'>", ['width' => 300]);

// Options as first argument (markup defaults)
echo $image->render(['width' => 300, 'height' => 200]);

// Width/height as a shorthand string
echo $image->render('300x200');

// Link thumbnail to the original
echo $image->render([
    'markup' => "<a href='{original.url}'><img src='{url}' alt='{alt}'></a>",
    'width'  => 300,
    'height' => 300,
]);

$options: width, height, markup (template string), link (bool — wrap in <a href='{original.url}'>), alt (override alt text), class (override CSS class), limit (int — max images when called on a Pageimages collection), plus any size() option.

In addition to all WireArray methods (count, first, last, get, each, filter, sort, slice, etc.) and Pagefiles methods (add, delete, deleteAll, rename, findTag, getTag, tags, etc.), Pageimages provides:

add($item)

Add a Pageimage or create one from a filename string.

$page->images->add('/tmp/uploaded-photo.jpg');
$page->save('images');

getFile($name)

Returns the Pageimage matching the given basename, or null. Also finds variations — e.g., passing 'photo.200x200.jpg' finds the original Pageimage that the variation belongs to.

$file = $page->images->getFile('photo.200x200.jpg');

getAllVariations()

Returns an associative array of all variation filenames indexed by the original file basename.

$vars = $page->images->getAllVariations();
print_r($vars);
// [
//   'photo.jpg' => ['photo.200x200.jpg', 'photo.400x300.jpg'],
//   'banner.jpg' => ['banner.1200x400.jpg'],
// ]

render($markup, $options)

Renders markup for every image in the collection. Same placeholder syntax as Pageimage::render(). Accepts limit to cap the number of images.

// Default<img> output for all images
echo $page->images->render();

// Custom gallery with thumbnails
echo $page->images->render(
    "<li><a href='{original.url}'><img src='{url}' alt='{alt}'></a></li>",
    ['width' => 300, 'height' => 300, 'limit' => 12]
);

Pageimage hooks

// Log every new variation
$wire->addHookAfter('Pageimage::createdVariation', function(HookEvent $event) {
    $image = $event->arguments(0); /** @var Pageimage $image */
    $wire->log->save('variations', "Created: $image->basename");
});

Inherited hooks

Pageimage inherits hookable url(), filename(), and ___noCacheURL() from Pagefile. The url() and filename() methods are overridden in Pageimage to dispatch to the hookable ___url() / ___filename() only when hooks are registered, avoiding overhead when no hooks exist.

// Example: modify image URLs on a CDN
$wire->addHookAfter('Pageimage::url', function(HookEvent $event) {
    $event->return = str_replace(
        $event->wire('config')->urls('root'),
        'https://cdn.example.com/',
        $event->return
    );
});

Pageimage is normally obtained from a field value. To construct directly:

$pageimage = new Pageimage($page->images, '/path/to/file.png');

The first argument must be a Pageimages instance (not a generic Pagefiles). A WireException is thrown if a non-Pageimages instance is provided.

The webp property returns a PagefileExtra object — the same class that handles any extra-format version of a file. Key properties:

• Access: Pageimages and Pageimage instances are obtained from FieldtypeImage field values. Construct Pageimage directly only when needed — the first argument must be a Pageimages instance.
• Variation caching: size() creates the variation file once and returns a clone of the original Pageimage with the variation filename. On subsequent calls, the same cached file is returned. Use forceNew or removeVariations() to regenerate.
• Variation filenames follow the pattern basename.WxH[crop][suffixes].ext — e.g., photo.400x300nw-hidpi.jpg.
• SVG images: size() returns the original Pageimage unchanged (SVGs are not resized server-side). Width/height may return '100%' for SVGs without explicit dimensions.
• __toString(): Pageimage inherits __toString() from Pagefile, which returns the basename (e.g., photo.jpg).
• EXIF orientation: JPEG images are checked for EXIF orientation, and width/height are swapped for portrait orientations (when autoRotation is enabled, which it is by default).
• $config->imageSizerOptions: Default resize options are set in site/config.php and merged with per-call options.
• $config->imageSizes: Predefined size definitions used by size('name') and sizeName('name').
• Error handling: Check $image->error (or ->error property) after size() calls. An empty string means success. Errors are also logged to the image-sizer log file.
• Extends Pagefile, which extends WireData. See also Pagefiles, WireArray, and FieldtypeImage.
• Source files: wire/core/Pageimages/Pageimages.php, wire/core/Pageimages/Pageimage.php, wire/core/Pageimages/PageimageVariations.php, wire/core/Pageimages/PageimageDebugInfo.php.