Media API Functions
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.
wp_get_attachment_image( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false, string|array $attr = '' ): string
Parameters
| Parameter | Type | Description |
|---|---|---|
$attachment_id |
int | Attachment post ID |
$size |
string|int[] | Size name or array( width, height ) |
$icon |
bool | Use mime type icon if no image |
$attr |
string|array | Additional attributes |
Attributes
| Key | Type | Description |
|---|---|---|
src |
string | Override image URL |
class |
string | CSS classes |
alt |
string | Alt text |
srcset |
string | Responsive sources |
sizes |
string | Responsive sizes |
loading |
string|false | lazy, eager, or false to omit |
decoding |
string | async, sync, or auto |
fetchpriority |
string | high, low, or auto |
Example
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.
wp_get_attachment_image_src( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false ): array|false
Returns
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.
wp_get_attachment_image_url( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false ): string|false
Example
$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.
wp_get_attachment_url( int $attachment_id ): string|false
wp_get_attachment_metadata()
Retrieves attachment metadata array.
wp_get_attachment_metadata( int $attachment_id, bool $unfiltered = false ): array|false
Parameters
| Parameter | Type | Description |
|---|---|---|
$attachment_id |
int | Attachment ID |
$unfiltered |
bool | Skip wp_get_attachment_metadata filter |
get_attached_file()
Returns the absolute server path to an attachment.
get_attached_file( int $attachment_id, bool $unfiltered = false ): string|false
Example
$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.
wp_attachment_is_image( int|WP_Post $post = null ): bool
wp_attachment_is()
Checks if an attachment is a specific type.
wp_attachment_is( string $type, int|WP_Post $post = null ): bool
Example
if ( wp_attachment_is( 'video', $attachment_id ) ) {
// Handle video
}
// Types: 'image', 'video', 'audio', 'pdf'
Image Sizing
add_image_size()
Registers a new image size.
add_image_size( string $name, int $width = 0, int $height = 0, bool|array $crop = false ): void
Parameters
| Parameter | Type | Description |
|---|---|---|
$name |
string | Size identifier |
$width |
int | Max width in pixels (0 = no limit) |
$height |
int | Max height in pixels (0 = no limit) |
$crop |
bool|array | Crop behavior |
Crop Values
| Value | Behavior |
|---|---|
false |
Proportional resize |
true |
Center crop |
array( 'left', 'top' ) |
Crop from position |
Example
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.
has_image_size( string $name ): bool
remove_image_size()
Removes a registered image size.
remove_image_size( string $name ): bool
set_post_thumbnail_size()
Sets dimensions for the post-thumbnail size.
set_post_thumbnail_size( int $width = 0, int $height = 0, bool|array $crop = false ): void
get_intermediate_image_sizes()
Returns all registered size names.
get_intermediate_image_sizes(): string[]
Returns
array( 'thumbnail', 'medium', 'medium_large', 'large', 'custom-size' )
wp_get_registered_image_subsizes()
Returns all sizes with their dimensions.
wp_get_registered_image_subsizes(): array[]
Returns
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.
image_get_intermediate_size( int $post_id, string|int[] $size = 'thumbnail' ): array|false
Returns
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.
wp_constrain_dimensions( int $current_width, int $current_height, int $max_width = 0, int $max_height = 0 ): int[]
Example
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.
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:
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.
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.
wp_get_attachment_image_srcset( int $attachment_id, string|int[] $size = 'medium', array $image_meta = null ): string|false
Example
$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.
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.
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.
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.
wp_get_image_editor( string $path, array $args = array() ): WP_Image_Editor|WP_Error
Example
$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.
wp_image_editor_supports( string|array $args = array() ): bool
Example
// 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.
image_make_intermediate_size( string $file, int $width, int $height, bool|array $crop = false ): array|false
Returns
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.
wp_filter_content_tags( string $content, string $context = null ): string
Adds:
srcsetandsizesattributesloading="lazy"for below-fold imagesfetchpriority="high"for first large imagedecoding="async"to images
wp_img_tag_add_loading_optimization_attrs()
Adds loading optimization attributes to an img tag.
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.
wp_lazy_loading_enabled( string $tag_name, string $context ): bool
Shortcodes
gallery_shortcode()
Outputs the shortcode.
gallery_shortcode( array $attr ): string
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
ids |
string | — | Comma-separated attachment IDs |
columns |
int | 3 | Number of columns |
size |
string | thumbnail |
Image size |
link |
string | — | Link target: file, none, or attachment page |
orderby |
string | menu_order ID |
Sort field |
order |
string | ASC |
Sort order |
wp_audio_shortcode()
Outputs the shortcode.
wp_audio_shortcode( array $attr, string $content = '' ): string|void
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
src |
string | — | Audio file URL |
loop |
bool | false | Loop playback |
autoplay |
bool | false | Auto-start |
preload |
string | none |
none, metadata, auto |
wp_video_shortcode()
Outputs the shortcode.
wp_video_shortcode( array $attr, string $content = '' ): string|void
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
src |
string | — | Video file URL |
poster |
string | — | Poster image URL |
width |
int | 640 | Player width |
height |
int | 360 | Player height |
loop |
bool | false | Loop playback |
autoplay |
bool | false | Auto-start |
muted |
bool | false | Mute audio |
preload |
string | metadata |
Preload behavior |
wp_playlist_shortcode()
Outputs the shortcode.
wp_playlist_shortcode( array $attr ): string
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | audio |
audio or video |
ids |
string | — | Comma-separated attachment IDs |
style |
string | light |
light or dark |
tracklist |
bool | true | Show track list |
tracknumbers |
bool | true | Show track numbers |
images |
bool | true | Show thumbnails |
artists |
bool | true | Show artist names |
Utility Functions
image_hwstring()
Returns width/height attributes string.
image_hwstring( int $width, int $height ): string
Example
echo image_hwstring( 800, 600 );
// 'width="800" height="600" '
get_image_tag()
Builds an img tag for an attachment.
get_image_tag( int $id, string $alt, string $title, string $align, string|int[] $size = 'medium' ): string
wp_get_attachment_link()
Returns an anchor element linking to an attachment.
wp_get_attachment_link( int|WP_Post $post = 0, string|int[] $size = 'thumbnail', bool $permalink = false, bool $icon = false, string|false $text = false, array $attr = '' ): string
attachment_url_to_postid()
Converts an attachment URL to its post ID.
attachment_url_to_postid( string $url ): int
wp_prepare_attachment_for_js()
Prepares attachment data for JavaScript (Media Library).
wp_prepare_attachment_for_js( int|WP_Post $attachment ): array|void
get_attached_media()
Gets media attachments for a post.
get_attached_media( string $type, int|WP_Post $post = 0 ): WP_Post[]
Example
$images = get_attached_media( 'image', $post_id );
$videos = get_attached_media( 'video', $post_id );
get_post_galleries()
Extracts galleries from post content.
get_post_galleries( int|WP_Post $post, bool $html = true ): array
wp_max_upload_size()
Returns the maximum upload size allowed.
wp_max_upload_size(): int
Returns the smaller of upload_max_filesize and post_max_size from php.ini.
wp_getimagesize()
Wrapper for getimagesize() with extended format support.
wp_getimagesize( string $filename, array &$image_info = null ): array|false
Adds support for WebP, AVIF, and HEIC when PHP doesn’t natively support them.
wp_get_webp_info()
Extracts dimensions and type from a WebP file.
wp_get_webp_info( string $filename ): array
Returns
array(
'width' => 800,
'height' => 600,
'type' => 'lossy', // 'lossy', 'lossless', or 'animated-alpha'
)
wp_get_avif_info()
Extracts information from an AVIF file.
wp_get_avif_info( string $filename ): array
Returns
array(
'width' => 800,
'height' => 600,
'bit_depth' => 8,
'num_channels' => 3,
)