[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

/wp-includes/ -> media.php (summary)

WordPress API for media display.

File Size: 4184 lines (144 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 4 files
 wp-includes/media-template.php
 wp-includes/class-wp-image-editor-imagick.php
 wp-includes/class-wp-image-editor-gd.php
 wp-includes/class-wp-image-editor.php

Defines 60 functions

  wp_get_additional_image_sizes()
  image_constrain_size_for_editor()
  image_hwstring()
  image_downsize()
  add_image_size()
  has_image_size()
  remove_image_size()
  set_post_thumbnail_size()
  get_image_tag()
  wp_constrain_dimensions()
  image_resize_dimensions()
  image_make_intermediate_size()
  wp_image_matches_ratio()
  image_get_intermediate_size()
  get_intermediate_image_sizes()
  wp_get_attachment_image_src()
  wp_get_attachment_image()
  wp_get_attachment_image_url()
  _wp_get_attachment_relative_path()
  _wp_get_image_size_from_meta()
  wp_get_attachment_image_srcset()
  wp_calculate_image_srcset()
  wp_get_attachment_image_sizes()
  wp_calculate_image_sizes()
  wp_make_content_images_responsive()
  wp_image_add_srcset_and_sizes()
  _wp_post_thumbnail_class_filter()
  _wp_post_thumbnail_class_filter_add()
  _wp_post_thumbnail_class_filter_remove()
  img_caption_shortcode()
  gallery_shortcode()
  wp_underscore_playlist_templates()
  wp_playlist_scripts()
  wp_get_video_extensions()
  wp_video_shortcode()
  previous_image_link()
  next_image_link()
  adjacent_image_link()
  get_attachment_taxonomies()
  get_taxonomies_for_attachments()
  wp_imagecreatetruecolor()
  wp_expand_dimensions()
  wp_max_upload_size()
  wp_get_image_editor()
  wp_image_editor_supports()
  _wp_image_editor_choose()
  wp_plupload_default_settings()
  wp_prepare_attachment_for_js()
  wp_enqueue_media()
  get_attached_media()
  get_media_embedded_in_content()
  get_post_galleries()
  get_post_gallery()
  get_post_galleries_images()
  get_post_gallery_images()
  wp_maybe_generate_attachment_metadata()
  attachment_url_to_postid()
  wpview_media_sandbox_styles()
  wp_register_media_personal_data_exporter()
  wp_media_personal_data_exporter()

Functions
Functions that are not part of a class:

wp_get_additional_image_sizes()   X-Ref
Retrieve additional image sizes.

return: array Additional images size data.

image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null )   X-Ref
Scale down the default size of an image.

This is so that the image is a better fit for the editor and theme.

The `$size` parameter accepts either an array or a string. The supported string
values are 'thumb' or 'thumbnail' for the given thumbnail size or defaults at
128 width and 96 height in pixels. Also supported for the string value is
'medium', 'medium_large' and 'full'. The 'full' isn't actually supported, but any value other
than the supported will result in the content_width size or 500 if that is
not set.

Finally, there is a filter named {@see 'editor_max_image_size'}, that will be
called on the calculated array for width and height, respectively. The second
parameter will be the value that was in the $size parameter. The returned
type for the hook is an array with the width as the first element and the
height as the second element.

param: int          $width   Width of the image in pixels.
param: int          $height  Height of the image in pixels.
param: string|array $size    Optional. Image size. Accepts any valid image size, or an array
param: string       $context Optional. Could be 'display' (like in a theme) or 'edit'
return: array Width and height of what the result image should resize to.

image_hwstring( $width, $height )   X-Ref
Retrieve width and height attributes using given width and height values.

Both attributes are required in the sense that both parameters must have a
value, but are optional in that if you set them to false or null, then they
will not be added to the returned string.

You can set the value using a string, but it will only take numeric values.
If you wish to put 'px' after the numbers, then it will be stripped out of
the return.

param: int|string $width  Image width in pixels.
param: int|string $height Image height in pixels.
return: string HTML attributes for width and, or height.

image_downsize( $id, $size = 'medium' )   X-Ref
Scale an image to fit a particular size (such as 'thumb' or 'medium').

Array with image url, width, height, and whether is intermediate size, in
that order is returned on success is returned. $is_intermediate is true if
$url is a resized image, false if it is the original.

The URL might be the original image, or it might be a resized version. This
function won't create a new resized copy, it will just return an already
resized one if it exists.

A plugin may use the {@see 'image_downsize'} filter to hook into and offer image
resizing services for images. The hook must return an array with the same
elements that are returned in the function. The first element being the URL
to the new image that was resized.

param: int          $id   Attachment ID for image.
param: array|string $size Optional. Image size to scale to. Accepts any valid image size,
return: false|array Array containing the image URL, width, height, and boolean for whether

add_image_size( $name, $width = 0, $height = 0, $crop = false )   X-Ref
Register a new image size.

Cropping behavior for the image size is dependent on the value of $crop:
1. If false (default), images will be scaled, not cropped.
2. If an array in the form of array( x_crop_position, y_crop_position ):
- x_crop_position accepts 'left' 'center', or 'right'.
- y_crop_position accepts 'top', 'center', or 'bottom'.
Images will be cropped to the specified dimensions within the defined crop area.
3. If true, images will be cropped to the specified dimensions using center positions.

param: string     $name   Image size identifier.
param: int        $width  Image width in pixels.
param: int        $height Image height in pixels.
param: bool|array $crop   Optional. Whether to crop images to specified width and height or resize.

has_image_size( $name )   X-Ref
Check if an image size exists.

param: string $name The image size to check.
return: bool True if the image size exists, false if not.

remove_image_size( $name )   X-Ref
Remove a new image size.

param: string $name The image size to remove.
return: bool True if the image size was successfully removed, false on failure.

set_post_thumbnail_size( $width = 0, $height = 0, $crop = false )   X-Ref
Registers an image size for the post thumbnail.

param: int        $width  Image width in pixels.
param: int        $height Image height in pixels.
param: bool|array $crop   Optional. Whether to crop images to specified width and height or resize.

get_image_tag( $id, $alt, $title, $align, $size = 'medium' )   X-Ref
Gets an img tag for an image attachment, scaling it down if requested.

The {@see 'get_image_tag_class'} filter allows for changing the class name for the
image without having to use regular expressions on the HTML content. The
parameters are: what WordPress will use for the class, the Attachment ID,
image align value, and the size the image should be.

The second filter, {@see 'get_image_tag'}, has the HTML content, which can then be
further manipulated by a plugin to change all attribute values and even HTML
content.

param: int          $id    Attachment ID.
param: string       $alt   Image Description for the alt attribute.
param: string       $title Image Description for the title attribute.
param: string       $align Part of the class name for aligning the image.
param: string|array $size  Optional. Registered image size to retrieve a tag for. Accepts any
return: string HTML IMG element for given image attachment

wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 )   X-Ref
Calculates the new dimensions for a down-sampled image.

If either width or height are empty, no constraint is applied on
that dimension.

param: int $current_width  Current width of the image.
param: int $current_height Current height of the image.
param: int $max_width      Optional. Max width in pixels to constrain to. Default 0.
param: int $max_height     Optional. Max height in pixels to constrain to. Default 0.
return: array First item is the width, the second item is the height.

image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = false )   X-Ref
Retrieves calculated resize dimensions for use in WP_Image_Editor.

Calculates dimensions and coordinates for a resized image that fits
within a specified width and height.

Cropping behavior is dependent on the value of $crop:
1. If false (default), images will not be cropped.
2. If an array in the form of array( x_crop_position, y_crop_position ):
- x_crop_position accepts 'left' 'center', or 'right'.
- y_crop_position accepts 'top', 'center', or 'bottom'.
Images will be cropped to the specified dimensions within the defined crop area.
3. If true, images will be cropped to the specified dimensions using center positions.

param: int        $orig_w Original width in pixels.
param: int        $orig_h Original height in pixels.
param: int        $dest_w New width in pixels.
param: int        $dest_h New height in pixels.
param: bool|array $crop   Optional. Whether to crop image to specified width and height or resize.
return: false|array False on failure. Returned array matches parameters for `imagecopyresampled()`.

image_make_intermediate_size( $file, $width, $height, $crop = false )   X-Ref
Resizes an image to make a thumbnail or intermediate size.

The returned array has the file size, the image width, and image height. The
{@see 'image_make_intermediate_size'} filter can be used to hook in and change the
values of the returned array. The only parameter is the resized file path.

param: string $file   File path.
param: int    $width  Image width.
param: int    $height Image height.
param: bool   $crop   Optional. Whether to crop image to specified width and height or resize.
return: false|array False, if no image was created. Metadata array on success.

wp_image_matches_ratio( $source_width, $source_height, $target_width, $target_height )   X-Ref
Helper function to test if aspect ratios for two images match.

param: int $source_width  Width of the first image in pixels.
param: int $source_height Height of the first image in pixels.
param: int $target_width  Width of the second image in pixels.
param: int $target_height Height of the second image in pixels.
return: bool True if aspect ratios match within 1px. False if not.

image_get_intermediate_size( $post_id, $size = 'thumbnail' )   X-Ref
Retrieves the image's intermediate size (resized) path, width, and height.

The $size parameter can be an array with the width and height respectively.
If the size matches the 'sizes' metadata array for width and height, then it
will be used. If there is no direct match, then the nearest image size larger
than the specified size will be used. If nothing is found, then the function
will break out and return false.

The metadata 'sizes' is used for compatible sizes that can be used for the
parameter $size value.

The url path will be given, when the $size parameter is a string.

If you are passing an array for the $size, you should consider using
add_image_size() so that a cropped version is generated. It's much more
efficient than having to find the closest-sized image and then having the
browser scale down the image.

param: int          $post_id Attachment ID.
param: array|string $size    Optional. Image size. Accepts any valid image size, or an array
return: false|array $data {

get_intermediate_image_sizes()   X-Ref
Gets the available intermediate image sizes.

return: array Returns a filtered array of image size strings.

wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false )   X-Ref
Retrieve an image to represent an attachment.

A mime icon for files, thumbnail or intermediate size for images.

The returned array contains four values: the URL of the attachment image src,
the width of the image file, the height of the image file, and a boolean
representing whether the returned array describes an intermediate (generated)
image size or the original, full-sized upload.

param: int          $attachment_id Image attachment ID.
param: string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
param: bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
return: false|array Returns an array (url, width, height, is_intermediate), or false, if no image is available.

wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' )   X-Ref
Get an HTML img element representing an image attachment

While `$size` will accept an array, it is better to register a size with
add_image_size() so that a cropped version is generated. It's much more
efficient than having to find the closest-sized image and then having the
browser scale down the image.

param: int          $attachment_id Image attachment ID.
param: string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
param: bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
param: string|array $attr          Optional. Attributes for the image markup. Default empty.
return: string HTML img element or empty string on failure.

wp_get_attachment_image_url( $attachment_id, $size = 'thumbnail', $icon = false )   X-Ref
Get the URL of an image attachment.

param: int          $attachment_id Image attachment ID.
param: string|array $size          Optional. Image size to retrieve. Accepts any valid image size, or an array
param: bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
return: string|false Attachment URL or false if no image is available.

_wp_get_attachment_relative_path( $file )   X-Ref
Get the attachment path relative to the upload directory.

param: string $file Attachment file name.
return: string Attachment path relative to the upload directory.

_wp_get_image_size_from_meta( $size_name, $image_meta )   X-Ref
Get the image size as array from its meta data.

Used for responsive images.

param: string $size_name  Image size. Accepts any valid image size name ('thumbnail', 'medium', etc.).
param: array  $image_meta The image meta data.
return: array|bool Array of width and height values in pixels (in that order)

wp_get_attachment_image_srcset( $attachment_id, $size = 'medium', $image_meta = null )   X-Ref
Retrieves the value for an image attachment's 'srcset' attribute.

param: int          $attachment_id Image attachment ID.
param: array|string $size          Optional. Image size. Accepts any valid image size, or an array of
param: array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
return: string|bool A 'srcset' value string or false.

wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attachment_id = 0 )   X-Ref
A helper function to calculate the image sources to include in a 'srcset' attribute.

param: array  $size_array    Array of width and height values in pixels (in that order).
param: string $image_src     The 'src' of the image.
param: array  $image_meta    The image meta data as returned by 'wp_get_attachment_metadata()'.
param: int    $attachment_id Optional. The image attachment ID to pass to the filter. Default 0.
return: string|bool          The 'srcset' attribute value. False on error or when only one source exists.

wp_get_attachment_image_sizes( $attachment_id, $size = 'medium', $image_meta = null )   X-Ref
Retrieves the value for an image attachment's 'sizes' attribute.

param: int          $attachment_id Image attachment ID.
param: array|string $size          Optional. Image size. Accepts any valid image size, or an array of width
param: array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
return: string|bool A valid source size value for use in a 'sizes' attribute or false.

wp_calculate_image_sizes( $size, $image_src = null, $image_meta = null, $attachment_id = 0 )   X-Ref
Creates a 'sizes' attribute value for an image.

param: array|string $size          Image size to retrieve. Accepts any valid image size, or an array
param: string       $image_src     Optional. The URL to the image file. Default null.
param: array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
param: int          $attachment_id Optional. Image attachment ID. Either `$image_meta` or `$attachment_id`
return: string|bool A valid source size value for use in a 'sizes' attribute or false.

wp_make_content_images_responsive( $content )   X-Ref
Filters 'img' elements in post content to add 'srcset' and 'sizes' attributes.

param: string $content The raw post content to be filtered.
return: string Converted content with 'srcset' and 'sizes' attributes added to images.

wp_image_add_srcset_and_sizes( $image, $image_meta, $attachment_id )   X-Ref
Adds 'srcset' and 'sizes' attributes to an existing 'img' element.

param: string $image         An HTML 'img' element to be filtered.
param: array  $image_meta    The image meta data as returned by 'wp_get_attachment_metadata()'.
param: int    $attachment_id Image attachment ID.
return: string Converted 'img' element with 'srcset' and 'sizes' attributes added.

_wp_post_thumbnail_class_filter( $attr )   X-Ref
Adds a 'wp-post-image' class to post thumbnails. Internal use only.

Uses the {@see 'begin_fetch_post_thumbnail_html'} and {@see 'end_fetch_post_thumbnail_html'}
action hooks to dynamically add/remove itself so as to only filter post thumbnails.

param: array $attr Thumbnail attributes including src, class, alt, title.
return: array Modified array of attributes including the new 'wp-post-image' class.

_wp_post_thumbnail_class_filter_add( $attr )   X-Ref
Adds '_wp_post_thumbnail_class_filter' callback to the 'wp_get_attachment_image_attributes'
filter hook. Internal use only.

param: array $attr Thumbnail attributes including src, class, alt, title.

_wp_post_thumbnail_class_filter_remove( $attr )   X-Ref
Removes the '_wp_post_thumbnail_class_filter' callback from the 'wp_get_attachment_image_attributes'
filter hook. Internal use only.

param: array $attr Thumbnail attributes including src, class, alt, title.

img_caption_shortcode( $attr, $content = null )   X-Ref
Builds the Caption shortcode output.

Allows a plugin to replace the content that would otherwise be returned. The
filter is {@see 'img_caption_shortcode'} and passes an empty string, the attr
parameter and the content parameter values.

The supported attributes for the shortcode are 'id', 'caption_id', 'align',
'width', 'caption', and 'class'.

param: array  $attr {
param: string $content Shortcode content.
return: string HTML content to display the caption.

gallery_shortcode( $attr )   X-Ref
Builds the Gallery shortcode output.

This implements the functionality of the Gallery Shortcode for displaying
WordPress images on a post.

param: array $attr {
return: string HTML content to display gallery.

wp_underscore_playlist_templates()   X-Ref
Outputs the templates used by playlists.


wp_playlist_scripts( $type )   X-Ref
Outputs and enqueue default scripts and styles for playlists.

param: string $type Type of playlist. Accepts 'audio' or 'video'.

wp_get_video_extensions()   X-Ref
Returns a filtered list of WP-supported video formats.

return: array List of supported video formats.

wp_video_shortcode( $attr, $content = '' )   X-Ref
Builds the Video shortcode output.

This implements the functionality of the Video Shortcode for displaying
WordPress mp4s in a post.

param: array  $attr {
param: string $content Shortcode content.
return: string|void HTML content to display video.

previous_image_link( $size = 'thumbnail', $text = false )   X-Ref
Displays previous image link that has the same post parent.

param: string|array $size Optional. Image size. Accepts any valid image size, an array of width and
param: string       $text Optional. Link text. Default false.

next_image_link( $size = 'thumbnail', $text = false )   X-Ref
Displays next image link that has the same post parent.

param: string|array $size Optional. Image size. Accepts any valid image size, an array of width and
param: string       $text Optional. Link text. Default false.

adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false )   X-Ref
Displays next or previous image link that has the same post parent.

Retrieves the current attachment object from the $post global.

param: bool         $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
param: string|array $size Optional. Image size. Accepts any valid image size, or an array of width and height
param: bool         $text Optional. Link text. Default false.

get_attachment_taxonomies( $attachment, $output = 'names' )   X-Ref
Retrieves taxonomies attached to given the attachment.

param: int|array|object $attachment Attachment ID, data array, or data object.
param: string           $output     Output type. 'names' to return an array of taxonomy names,
return: array Empty array on failure. List of taxonomies on success.

get_taxonomies_for_attachments( $output = 'names' )   X-Ref
Retrieves all of the taxonomies that are registered for attachments.

Handles mime-type-specific taxonomies such as attachment:image and attachment:video.

param: string $output Optional. The type of taxonomy output to return. Accepts 'names' or 'objects'.
return: string[]|WP_Taxonomy[] Array of names or objects of registered taxonomies for attachments.

wp_imagecreatetruecolor( $width, $height )   X-Ref
Create new GD image resource with transparency support

param: int $width  Image width in pixels.
param: int $height Image height in pixels..
return: resource The GD image resource.

wp_expand_dimensions( $example_width, $example_height, $max_width, $max_height )   X-Ref
Based on a supplied width/height example, return the biggest possible dimensions based on the max width/height.

param: int $example_width  The width of an example embed.
param: int $example_height The height of an example embed.
param: int $max_width      The maximum allowed width.
param: int $max_height     The maximum allowed height.
return: array The maximum possible width and height based on the example ratio.

wp_max_upload_size()   X-Ref
Determines the maximum upload size allowed in php.ini.

return: int Allowed upload size.

wp_get_image_editor( $path, $args = array()   X-Ref
Returns a WP_Image_Editor instance and loads file into it.

param: string $path Path to the file to load.
param: array  $args Optional. Additional arguments for retrieving the image editor.
return: WP_Image_Editor|WP_Error The WP_Image_Editor object if successful, an WP_Error

wp_image_editor_supports( $args = array()   X-Ref
Tests whether there is an editor that supports a given mime type or methods.

param: string|array $args Optional. Array of arguments to retrieve the image editor supports.
return: bool True if an eligible editor is found; false otherwise.

_wp_image_editor_choose( $args = array()   X-Ref
Tests which editors are capable of supporting the request.

param: array $args Optional. Array of arguments for choosing a capable editor. Default empty array.
return: string|false Class name for the first editor that claims to support the request. False if no

wp_plupload_default_settings()   X-Ref
Prints default Plupload arguments.


wp_prepare_attachment_for_js( $attachment )   X-Ref
Prepares an attachment post object for JS, where it is expected
to be JSON-encoded and fit into an Attachment model.

param: int|WP_Post $attachment Attachment ID or object.
return: array|void Array of attachment details.

wp_enqueue_media( $args = array()   X-Ref
Enqueues all scripts, styles, settings, and templates necessary to use
all media JS APIs.

param: array $args {

get_attached_media( $type, $post = 0 )   X-Ref
Retrieves media attached to the passed post.

param: string      $type Mime type.
param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
return: array Found attachments.

get_media_embedded_in_content( $content, $types = null )   X-Ref
Check the content blob for an audio, video, object, embed, or iframe tags.

param: string $content A string which might contain media data.
param: array  $types   An array of media types: 'audio', 'video', 'object', 'embed', or 'iframe'.
return: array A list of found HTML media embeds.

get_post_galleries( $post, $html = true )   X-Ref
Retrieves galleries from the passed post's content.

param: int|WP_Post $post Post ID or object.
param: bool        $html Optional. Whether to return HTML or data in the array. Default true.
return: array A list of arrays, each containing gallery data and srcs parsed

get_post_gallery( $post = 0, $html = true )   X-Ref
Check a specified post's content for gallery and, if present, return the first

param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
param: bool        $html Optional. Whether to return HTML or data. Default is true.
return: string|array Gallery data and srcs parsed from the expanded shortcode.

get_post_galleries_images( $post = 0 )   X-Ref
Retrieve the image srcs from galleries from a post's content, if present

param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
return: array A list of lists, each containing image srcs parsed.

get_post_gallery_images( $post = 0 )   X-Ref
Checks a post's content for galleries and return the image srcs for the first found gallery

param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
return: array A list of a gallery's image srcs in order.

wp_maybe_generate_attachment_metadata( $attachment )   X-Ref
Maybe attempts to generate attachment metadata, if missing.

param: WP_Post $attachment Attachment object.

attachment_url_to_postid( $url )   X-Ref
Tries to convert an attachment URL into a post ID.

param: string $url The URL to resolve.
return: int The found post ID, or 0 on failure.

wpview_media_sandbox_styles()   X-Ref
Returns the URLs for CSS files used in an iframe-sandbox'd TinyMCE media view.

return: array The relevant CSS file URLs.

wp_register_media_personal_data_exporter( $exporters )   X-Ref
Registers the personal data exporter for media

param: array   $exporters   An array of personal data exporters.
return: array  An array of personal data exporters.

wp_media_personal_data_exporter( $email_address, $page = 1 )   X-Ref
Finds and exports attachments associated with an email address.

param: string $email_address The attachment owner email address.
param: int    $page          Attachment page.
return: array  $return        An array of personal data.



Generated: Mon Dec 10 08:20:01 2018 Cross-referenced by PHPXref 0.7