Media API Functions

Last updated: March 4, 2026

Core functions for attachment retrieval, image sizing, and media output.

Source: wp-includes/media.php

Attachment Retrieval

wp_get_attachment_image()

Returns an HTML <img> element for an attachment.

php
wp_get_attachment_image( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false, string|array $attr = '' ): string

Parameters

ParameterTypeDescription
$attachment_idintAttachment post ID
$sizestring|int[]Size name or array( width, height )
$iconboolUse mime type icon if no image
$attrstring|arrayAdditional attributes

Attributes

KeyTypeDescription
srcstringOverride image URL
classstringCSS classes
altstringAlt text
srcsetstringResponsive sources
sizesstringResponsive sizes
loadingstring|falselazy, eager, or false to omit
decodingstringasync, sync, or auto
fetchprioritystringhigh, low, or auto

Example

php
echo wp_get_attachment_image( 123, 'medium', false, array(
    'class' => 'featured-image',
    'alt'   => 'Featured product image',
    'loading' => 'eager',
) );

wp_get_attachment_image_src()

Returns an array of image data for a size.

php
wp_get_attachment_image_src( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false ): array|false

Returns

php
array(
    0 => 'https://example.com/image-300x200.jpg',  // URL
    1 => 300,   // Width
    2 => 200,   // Height
    3 => true,  // Is resized (not full size)
)

wp_get_attachment_image_url()

Returns just the URL for an attachment size.

php
wp_get_attachment_image_url( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false ): string|false

Example

php
$url = wp_get_attachment_image_url( 123, 'large' );
// 'https://example.com/wp-content/uploads/2024/01/image-1024x683.jpg'

wp_get_attachment_url()

Returns the URL for the original attachment file.

php
wp_get_attachment_url( int $attachment_id ): string|false

wp_get_attachment_metadata()

Retrieves attachment metadata array.

php
wp_get_attachment_metadata( int $attachment_id, bool $unfiltered = false ): array|false

Parameters

ParameterTypeDescription
$attachment_idintAttachment ID
$unfilteredboolSkip wp_get_attachment_metadata filter

get_attached_file()

Returns the absolute server path to an attachment.

php
get_attached_file( int $attachment_id, bool $unfiltered = false ): string|false

Example

php
$path = get_attached_file( 123 );
// '/var/www/html/wp-content/uploads/2024/01/image.jpg'

wp_attachment_is_image()

Checks if an attachment is an image.

php
wp_attachment_is_image( int|WP_Post $post = null ): bool

wp_attachment_is()

Checks if an attachment is a specific type.

php
wp_attachment_is( string $type, int|WP_Post $post = null ): bool

Example

php
if ( wp_attachment_is( 'video', $attachment_id ) ) {
    // Handle video
}
// Types: 'image', 'video', 'audio', 'pdf'

Image Sizing

add_image_size()

Registers a new image size.

php
add_image_size( string $name, int $width = 0, int $height = 0, bool|array $crop = false ): void

Parameters

ParameterTypeDescription
$namestringSize identifier
$widthintMax width in pixels (0 = no limit)
$heightintMax height in pixels (0 = no limit)
$cropbool|arrayCrop behavior

Crop Values

ValueBehavior
falseProportional resize
trueCenter crop
array( 'left', 'top' )Crop from position

Example

php
add_action( 'after_setup_theme', function() {
    add_image_size( 'hero-banner', 1920, 600, array( 'center', 'center' ) );
    add_image_size( 'card-thumb', 400, 300, true );
});

has_image_size()

Checks if a custom image size exists.

php
has_image_size( string $name ): bool

remove_image_size()

Removes a registered image size.

php
remove_image_size( string $name ): bool

set_post_thumbnail_size()

Sets dimensions for the post-thumbnail size.

php
set_post_thumbnail_size( int $width = 0, int $height = 0, bool|array $crop = false ): void

get_intermediate_image_sizes()

Returns all registered size names.

php
get_intermediate_image_sizes(): string[]

Returns

php
array( 'thumbnail', 'medium', 'medium_large', 'large', 'custom-size' )

wp_get_registered_image_subsizes()

Returns all sizes with their dimensions.

php
wp_get_registered_image_subsizes(): array[]

Returns

php
array(
    'thumbnail' => array( 'width' => 150, 'height' => 150, 'crop' => true ),
    'medium'    => array( 'width' => 300, 'height' => 300, 'crop' => false ),
    // ...
)

image_get_intermediate_size()

Gets data for a specific intermediate size.

php
image_get_intermediate_size( int $post_id, string|int[] $size = 'thumbnail' ): array|false

Returns

php
array(
    'file'   => 'image-300x200.jpg',
    'width'  => 300,
    'height' => 200,
    'path'   => '2024/01/image-300x200.jpg',
    'url'    => 'https://example.com/wp-content/uploads/2024/01/image-300x200.jpg',
)

Dimension Calculations

wp_constrain_dimensions()

Calculates dimensions to fit within max bounds.

php
wp_constrain_dimensions( int $current_width, int $current_height, int $max_width = 0, int $max_height = 0 ): int[]

Example

php
list( $w, $h ) = wp_constrain_dimensions( 1920, 1080, 800, 600 );
// $w = 800, $h = 450 (maintains aspect ratio)

image_resize_dimensions()

Calculates resize dimensions for cropping.

php
image_resize_dimensions( int $orig_w, int $orig_h, int $dest_w, int $dest_h, bool|array $crop = false ): array|false

Returns

Array matching imagecopyresampled() parameters:

php
array( $dst_x, $dst_y, $src_x, $src_y, $dst_w, $dst_h, $src_w, $src_h )

wp_image_matches_ratio()

Checks if two images have matching aspect ratios.

php
wp_image_matches_ratio( int $source_width, int $source_height, int $target_width, int $target_height ): bool

Responsive Images

wp_get_attachment_image_srcset()

Gets the srcset attribute value for an attachment.

php
wp_get_attachment_image_srcset( int $attachment_id, string|int[] $size = 'medium', array $image_meta = null ): string|false

Example

php
$srcset = wp_get_attachment_image_srcset( 123, 'medium' );
// 'image-300x200.jpg 300w, image-768x512.jpg 768w, image-1024x683.jpg 1024w'

wp_calculate_image_srcset()

Calculates srcset sources from image metadata.

php
wp_calculate_image_srcset( int[] $size_array, string $image_src, array $image_meta, int $attachment_id = 0 ): string|false

wp_get_attachment_image_sizes()

Gets the sizes attribute value for an attachment.

php
wp_get_attachment_image_sizes( int $attachment_id, string|int[] $size = 'medium', array $image_meta = null ): string|false

wp_calculate_image_sizes()

Calculates the sizes attribute value.

php
wp_calculate_image_sizes( string|int[] $size, string $image_src = null, array $image_meta = null, int $attachment_id = 0 ): string|false

Image Processing

wp_get_image_editor()

Returns a WP_Image_Editor instance for a file.

php
wp_get_image_editor( string $path, array $args = array() ): WP_Image_Editor|WP_Error

Example

php
$editor = wp_get_image_editor( '/path/to/image.jpg' );
if ( ! is_wp_error( $editor ) ) {
    $editor->resize( 800, 600, true );
    $editor->rotate( 90 );
    $editor->save( '/path/to/output.jpg' );
}

wp_image_editor_supports()

Checks if any editor supports given requirements.

php
wp_image_editor_supports( string|array $args = array() ): bool

Example

php
// Check mime type support
if ( wp_image_editor_supports( array( 'mime_type' => 'image/webp' ) ) ) {
    // WebP editing available
}

// Check method support
if ( wp_image_editor_supports( array( 'methods' => array( 'rotate', 'flip' ) ) ) ) {
    // Rotation and flipping available
}

image_make_intermediate_size()

Creates a resized image file.

php
image_make_intermediate_size( string $file, int $width, int $height, bool|array $crop = false ): array|false

Returns

php
array(
    'file'      => 'image-300x200.jpg',
    'width'     => 300,
    'height'    => 200,
    'mime-type' => 'image/jpeg',
    'filesize'  => 15000,
)

Content Filtering

wp_filter_content_tags()

Processes img/iframe tags in content for optimization.

php
wp_filter_content_tags( string $content, string $context = null ): string

Adds:

  • srcset and sizes attributes
  • loading="lazy" for below-fold images
  • fetchpriority="high" for first large image
  • decoding="async" to images

wp_img_tag_add_loading_optimization_attrs()

Adds loading optimization attributes to an img tag.

php
wp_img_tag_add_loading_optimization_attrs( string $image, string $context ): string

wp_lazy_loading_enabled()

Checks if lazy loading is enabled for a tag type.

php
wp_lazy_loading_enabled( string $tag_name, string $context ): bool

Shortcodes

More in Media

WP_Image_Editor Classes

Abstract base class and implementations for image manipulation in WordPress. Source: wp-includes/class-wp-image-editor.php, wp-includes/class-wp-image-editor-gd.php, wp-includes/class-wp-image-editor-imagick.php Class…

Media API Hooks

Actions and filters for media processing, image manipulation, and attachment handling. Source: wp-includes/media.php, wp-includes/class-wp-image-editor.php Image…

WordPress Media API

Comprehensive system for managing media files including image manipulation, upload handling, and attachment management. Source:…

WP_Image_Editor Classes

Abstract base class and implementations for image manipulation in WordPress. Source: wp-includes/class-wp-image-editor.php, wp-includes/class-wp-image-editor-gd.php, wp-includes/class-wp-image-editor-imagick.php Class…

All WordPress Core Docs View all Media
View on GitHub