Images and Media API

An image attachment is a post of type attachment with three meta keys (_wp_attached_file, _wp_attachment_metadata, _wp_attachment_image_alt), as described in Media Library. Code reads them through functions:

The featured image of an lp_book is its cover. An <img> built from wp_get_attachment_url() would lose srcset, the dimensions that prevent layout shift and every loading attribute.

add_image_size( $name, $width, $height, $crop ) (2.9) adds a size that WordPress generates for every image uploaded afterwards. A width or height of 0 means unconstrained. The crop argument decides how the image fits the box:

WordPress never upscales: a size is made only when the original is larger than the box. set_post_thumbnail_size() registers post-thumbnail. Sizes live in a global array, so they are registered on every request (after_setup_theme). Covers are 2:3 portraits shown at 600 px on the book page and 300 px on cards. The plugin registers both, offers the larger one in the editor’s resolution control, and skips the two very large core sizes for covers:

Source: Code Reference: add_image_size(), Code Reference: intermediate_image_sizes_advanced

Two filters are needed because the upload paths ask different questions: wp_create_image_subsizes() on the server filters the list through intermediate_image_sizes_advanced ($attachment_id since 5.3), while the REST API behind the 7.1 client-side processing asks wp_get_missing_image_subsizes(); with only the first filter, the cover imported below reports 1536x1536, 2048x2048 as missing. post_parent is set before the sizes are made when a file is uploaded or sideloaded to a book; an image uploaded in the Library and chosen as featured image later gets every size. WP-CLI 2.12’s wp media image-size prints a crop-position array as soft, although the files are cropped to exactly 300 × 450.

wp_get_attachment_image() adds, in order: src, width, height, class (attachment-<size> size-<size>) and alt; the loading attributes; srcset and sizes; auto in sizes for lazy images; then it runs the wp_get_attachment_image_attributes filter. Attributes in $attr win, and false for loading or fetchpriority removes the attribute.

srcset (4.4) comes from wp_calculate_image_srcset(): every generated file of the same image whose aspect ratio matches the requested size within one pixel, including "full", but not files wider than max_srcset_image_width (2048 px) unless that file is the src. A cover with no other 2:3 file gets no srcset. sizes comes from wp_calculate_image_sizes(), whose default (max-width: <width>px) 100vw, <width>px is right only for an image as wide as its column. A cover in a two-column grid needs its own value (in $attr, or for all images through the wp_calculate_image_sizes filter), or phones download a file twice as wide as needed.

Source: Code Reference: wp_get_attachment_image()

The render.php of lumen/latest-books calls it in its WP_Query loop (see Static and Dynamic Blocks). For "The Lighthouse Ledger" (book 6, cover 7) the card call returns (line breaks added, upload URLs shortened to …/):

Source: Common APIs Handbook: Responsive Images

The src file comes first, the 150 × 150 thumbnail is missing (other ratio), and the 1600 px "full" file is in (not wider than 2048 px). The single-book template passes lp-book-cover, (max-width: 700px) 90vw, 600px, fetchpriority => 'high' and loading => false, and gets no loading and therefore no auto.

For a lazy image the browser knows the rendered width when the download starts, so sizes="auto" lets it pick the candidate from the real layout. Since 6.7, wp_get_attachment_image() and the content filters (wp_img_tag_add_auto_sizes()) prepend auto, when the image has loading="lazy", a width and a sizes, and auto is not already first. Browsers without support skip it, so the explicit value still matters. Since 6.7.1 core also prints a contain-intrinsic-size rule for such images (the wp-img-auto-sizes-contain style since 6.9). Returning false from the wp_img_tag_add_auto_sizes filter (6.7.1) removes both.

Three functions in wp-admin/includes/media.php turn a file into an attachment with its sizes and return the ID or a WP_Error. Outside admin screens, code first requires media.php, file.php and image.php from that folder.

All three run the upload checks of wp_handle_upload() / wp_handle_sideload(), file the upload under the parent post’s date (media_handle_upload() makes an exception for pages), so a cover attached to a book published in 2024 lands in uploads/2024/<month>/, and take the title, caption and (since 7.0, through wp_get_image_alttext()) alt text embedded in the image unless $desc or $post_data overrides them. Covers delivered as files on disk use media_handle_sideload() with a copy, because it moves tmp_name away:

Source: Code Reference: media_handle_sideload()

wp_generate_attachment_metadata( $id, $file ) (wp-admin/includes/image.php) builds the metadata: for images it scales big originals, creates the sub-sizes and reads EXIF/IPTC; for PDFs it renders previews; for audio and video it reads length and codecs. Uploads save it with wp_update_attachment_metadata(), and code that replaces a file in place calls the same pair. For cover 7 (wp eval over wp_get_attachment_metadata( 7 )):

Source: Code Reference: wp_get_attachment_metadata()

The array holds width, height, file (relative to the uploads directory), filesize (6.0), sizes (each with file, width, height, mime-type, filesize), image_meta (camera, caption, copyright, keywords, orientation, alt) and, after scaling, rotation or conversion, original_image. The REST API exposes it as media_details; see REST API: Using It.

WP_Image_Editor (3.5) is the abstract class behind every resize, crop and rotation in core, implemented by WP_Image_Editor_Imagick and WP_Image_Editor_GD. wp_get_image_editor( $path, $args ) loads the file with the first class in the wp_image_editors filter (Imagick, then GD) that passes test(), supports the input type and has the methods in $args['methods'], preferring one that can write the mapped output format; otherwise it returns image_no_editor. wp_image_editor_supports( $args ) asks without a file.

On the official image both libraries handle JPEG, PNG, GIF, WebP and AVIF (GD is the bundled 2.1 with AVIF), and only Imagick reads HEIC, which is why HEIC uploads need it. wp_image_editor_supports( array( 'mime_type' => 'image/heic' ) ) returned true, and false with wp_image_editors reduced to WP_Image_Editor_GD. Imagick keeps colour profiles and allocates outside PHP’s memory_limit; GD decodes the bitmap into PHP memory at about 4 bytes per pixel (roughly 100 MB for 6000 × 4000). If ImageMagick lacks a delegate (WebP, say), core falls back to GD for that type. Tools > Site Health > Info > Media Handling shows what a server has.

Source: Code Reference: wp_image_editors

The image_editor_output_format filter (5.8) maps an input MIME type to the type the editor writes; its default since 6.7 maps HEIC and HEIF to JPEG. The mapping applies to every save of that input type: every sub-size and a converted "full" copy, with the uploaded file then named in original_image, while the attachment’s post_mime_type keeps the uploaded type. The site-owner side, with an AVIF example, is in Media Library. Lumen Press writes WebP and lowers the quality of small sizes with the $size argument that wp_editor_set_quality gained in 6.8:

Source: Code Reference: image_editor_output_format, Code Reference: wp_editor_set_quality

wp media regenerate 9 --yes on "The Glass Orchard" cover then produced a metadata file of 2026/10/978-1-23456-790-3.webp, every size as image/webp (862 bytes for 300 × 450, 2,930 for 600 × 900) and original_image set to the JPEG. An editor that cannot write the mapped type keeps the input format, so the filter needs no support check. The mapping also applies to plugin code that calls save() with an explicit image/jpeg: under this filter that file comes out as WebP, with a .webp extension.

See also Where Older Books and Tutorials Are Outdated.