WordPress.org

Make WordPress Core

Ticket #28408: 28408.2.patch

File 28408.2.patch, 35.5 KB (added by DrewAPicture, 5 years ago)
  • src/wp-includes/media.php

     
    5959                // if no width is set, default to the theme content width if available
    6060        }
    6161        elseif ( $size == 'large' ) {
    62                 // We're inserting a large size image into the editor. If it's a really
    63                 // big image we'll scale it down to fit reasonably within the editor
    64                 // itself, and within the theme's content width if it's known. The user
    65                 // can resize it in the editor if they wish.
     62                /*
     63                 * We're inserting a large size image into the editor. If it's a really
     64                 * big image we'll scale it down to fit reasonably within the editor
     65                 * itself, and within the theme's content width if it's known. The user
     66                 * can resize it in the editor if they wish.
     67                 */
    6668                $max_width = intval(get_option('large_size_w'));
    6769                $max_height = intval(get_option('large_size_h'));
    6870                if ( intval($content_width) > 0 )
     
    109111 *
    110112 * @since 2.5.0
    111113 *
    112  * @param int|string $width Optional. Width attribute value.
    113  * @param int|string $height Optional. Height attribute value.
     114 * @param int|string $width  Image width in pixels.
     115 * @param int|string $height Image height in pixels.
    114116 * @return string HTML attributes for width and, or height.
    115117 */
    116 function image_hwstring($width, $height) {
     118function image_hwstring( $width, $height ) {
    117119        $out = '';
    118120        if ($width)
    119121                $out .= 'width="'.intval($width).'" ';
     
    140142 *
    141143 * @since 2.5.0
    142144 *
    143  * @param int $id Attachment ID for image.
    144  * @param array|string $size Optional, default is 'medium'. Size of image, either array or string.
     145 * @param int          $id   Attachment ID for image.
     146 * @param array|string $size Optional. Image size to scale to. Accepts a registered image size
     147 *                           or flat array of height and width values. Default 'medium'.
    145148 * @return bool|array False on failure, array on success.
    146149 */
    147 function image_downsize($id, $size = 'medium') {
     150function image_downsize( $id, $size = 'medium' ) {
    148151
    149152        if ( !wp_attachment_is_image($id) )
    150153                return false;
     
    284287}
    285288
    286289/**
    287  * An <img src /> tag for an image attachment, scaling it down if requested.
     290 * Gets an img tag for an image attachment, scaling it down if requested.
    288291 *
    289292 * The filter 'get_image_tag_class' allows for changing the class name for the
    290293 * image without having to use regular expressions on the HTML content. The
     
    297300 *
    298301 * @since 2.5.0
    299302 *
    300  * @param int $id Attachment ID.
    301  * @param string $alt Image Description for the alt attribute.
    302  * @param string $title Image Description for the title attribute.
    303  * @param string $align Part of the class name for aligning the image.
    304  * @param string $size Optional. Default is 'medium'.
     303 * @param int          $id    Attachment ID.
     304 * @param string       $alt   Image Description for the alt attribute.
     305 * @param string       $title Image Description for the title attribute.
     306 * @param string       $align Part of the class name for aligning the image.
     307 * @param string|array $size  Optional. Registered image size to retrieve a tag for, or flat array
     308 *                            of height and width values. Default 'medium'.
    305309 * @return string HTML IMG element for given image attachment
    306310 */
    307 function get_image_tag($id, $alt, $title, $align, $size='medium') {
     311function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
    308312
    309313        list( $img_src, $width, $height ) = image_downsize($id, $size);
    310314        $hwstring = image_hwstring($width, $height);
     
    345349}
    346350
    347351/**
    348  * Calculates the new dimensions for a downsampled image.
     352 * Calculates the new dimensions for a down-sampled image.
    349353 *
    350354 * If either width or height are empty, no constraint is applied on
    351355 * that dimension.
     
    352356 *
    353357 * @since 2.5.0
    354358 *
    355  * @param int $current_width Current width of the image.
     359 * @param int $current_width  Current width of the image.
    356360 * @param int $current_height Current height of the image.
    357  * @param int $max_width Optional. Maximum wanted width.
    358  * @param int $max_height Optional. Maximum wanted height.
     361 * @param int $max_width      Optional. Max width in pixels to constrain to. Default 0.
     362 * @param int $max_height     Optional. Max height in pixels to constrain to. Defualt 0.
    359363 * @return array First item is the width, the second item is the height.
    360364 */
    361 function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) {
     365function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) {
    362366        if ( !$max_width && !$max_height )
    363367                return array( $current_width, $current_height );
    364368
     
    405409                $h = $max_height; // Round it up
    406410        }
    407411
     412        /**
     413         * Filter dimensions to constrain down-sampled images to.
     414         *
     415         * @since 4.1.0
     416         *
     417         * @param array $dimensions     The image width and height
     418         * @param int   $current_width  The current width of the image.
     419         * @param int   $current_height The current height of the image.
     420         * @param int   $max_width      The maximum width permitted.
     421         * @param int   $max_height     The maximum height permitted.
     422         */
    408423        return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );
    409424}
    410425
    411426/**
    412  * Retrieve calculated resize dimensions for use in WP_Image_Editor.
     427 * Retrieves calculated resize dimensions for use in WP_Image_Editor.
    413428 *
    414429 * Calculates dimensions and coordinates for a resized image that fits
    415430 * within a specified width and height.
     
    523538}
    524539
    525540/**
    526  * Resize an image to make a thumbnail or intermediate size.
     541 * Resizes an image to make a thumbnail or intermediate size.
    527542 *
    528543 * The returned array has the file size, the image width, and image height. The
    529544 * filter 'image_make_intermediate_size' can be used to hook in and change the
     
    531546 *
    532547 * @since 2.5.0
    533548 *
    534  * @param string $file File path.
    535  * @param int $width Image width.
    536  * @param int $height Image height.
    537  * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize.
     549 * @param string $file   File path.
     550 * @param int    $width  Image width.
     551 * @param int    $height Image height.
     552 * @param bool   $crop   Optional. Whether to crop image to specified height and width or resize.
     553 *                       Default false.
    538554 * @return bool|array False, if no image was created. Metadata array on success.
    539555 */
    540556function image_make_intermediate_size( $file, $width, $height, $crop = false ) {
     
    555571}
    556572
    557573/**
    558  * Retrieve the image's intermediate size (resized) path, width, and height.
     574 * Retrieves the image's intermediate size (resized) path, width, and height.
    559575 *
    560576 * The $size parameter can be an array with the width and height respectively.
    561577 * If the size matches the 'sizes' metadata array for width and height, then it
     
    574590 * browser scale down the image.
    575591 *
    576592 * @since 2.5.0
    577  * @see add_image_size()
    578593 *
    579  * @param int $post_id Attachment ID for image.
    580  * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string.
     594 * @param int          $post_id Attachment ID.
     595 * @param array|string $size    Optional. Registered image size to retrieve or flat array of height
     596 *                              and width dimensions. Default 'thumbnail'.
    581597 * @return bool|array False on failure or array of file path, width, and height on success.
    582598 */
    583 function image_get_intermediate_size($post_id, $size='thumbnail') {
     599function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) {
    584600        if ( !is_array( $imagedata = wp_get_attachment_metadata( $post_id ) ) )
    585601                return false;
    586602
     
    633649}
    634650
    635651/**
    636  * Get the available image sizes
     652 * Gets the available intermediate image sizes.
     653 *
    637654 * @since 3.0.0
    638  * @return array Returns a filtered array of image size strings
     655 *
     656 * @global array $_wp_additional_image_sizes
     657 *
     658 * @return array Returns a filtered array of image size strings.
    639659 */
    640660function get_intermediate_image_sizes() {
    641661        global $_wp_additional_image_sizes;
     
    661681 *
    662682 * @since 2.5.0
    663683 *
    664  * @param int $attachment_id Image attachment ID.
    665  * @param string $size Optional, default is 'thumbnail'.
    666  * @param bool $icon Optional, default is false. Whether it is an icon.
     684 * @param int          $attachment_id Image attachment ID.
     685 * @param string|array $size          Optional. Registered image size to retrieve the source for or a flat
     686 *                                    array of height and width dimensions. Default 'thumbnail'.
     687 * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
    667688 * @return bool|array Returns an array (url, width, height), or false, if no image is available.
    668689 */
    669 function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) {
     690function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) {
    670691
    671692        // get a thumbnail or intermediate image if there is one
    672693        if ( $image = image_downsize($attachment_id, $size) )
     
    677698        if ( $icon && $src = wp_mime_type_icon($attachment_id) ) {
    678699                /** This filter is documented in wp-includes/post.php */
    679700                $icon_dir = apply_filters( 'icon_dir', ABSPATH . WPINC . '/images/media' );
     701
    680702                $src_file = $icon_dir . '/' . wp_basename($src);
    681703                @list($width, $height) = getimagesize($src_file);
    682704        }
     
    688710/**
    689711 * Get an HTML img element representing an image attachment
    690712 *
    691  * While $size will accept an array, it is better to register a size with
     713 * While `$size` will accept an array, it is better to register a size with
    692714 * add_image_size() so that a cropped version is generated. It's much more
    693715 * efficient than having to find the closest-sized image and then having the
    694716 * browser scale down the image.
     
    695717 *
    696718 * @since 2.5.0
    697719 *
    698  * @see add_image_size()
    699  *
    700720 * @param int          $attachment_id Image attachment ID.
    701  * @param string|array $size          Optional. Default 'thumbnail'.
    702  * @param bool         $icon          Optional. Whether it is an icon. Default false.
    703  * @param string|array $attr          Optional. Attributes for the image markup. Default empty string.
     721 * @param string|array $size          Optional. Registered image size or flat array of height and width
     722 *                                    dimensions. Default 'thumbnail'.
     723 * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
     724 * @param string|array $attr          Optional. Attributes for the image markup. Default empty.
    704725 * @return string HTML img element or empty string on failure.
    705726 */
    706727function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false, $attr = '') {
     
    749770}
    750771
    751772/**
    752  * Adds a 'wp-post-image' class to post thumbnails
     773 * Adds a 'wp-post-image' class to post thumbnails. Internal use only.
     774 *
    753775 * Uses the begin_fetch_post_thumbnail_html and end_fetch_post_thumbnail_html action hooks to
    754  * dynamically add/remove itself so as to only filter post thumbnails
     776 * dynamically add/remove itself so as to only filter post thumbnails.
    755777 *
     778 * @ignore
    756779 * @since 2.9.0
    757  * @param array $attr Attributes including src, class, alt, title
    758  * @return array
     780 *
     781 * @param array $attr Thumbnail attributes including src, class, alt, title.
     782 * @return array Modified array of attributes including the new 'wp-post-image' class.
    759783 */
    760784function _wp_post_thumbnail_class_filter( $attr ) {
    761785        $attr['class'] .= ' wp-post-image';
     
    763787}
    764788
    765789/**
    766  * Adds _wp_post_thumbnail_class_filter to the wp_get_attachment_image_attributes filter
     790 * Adds '_wp_post_thumbnail_class_filter' callback to the 'wp_get_attachment_image_attributes'
     791 * filter hook. Internal use only.
    767792 *
     793 * @ignore
    768794 * @since 2.9.0
     795 *
     796 * @param array $attr Thumbnail attributes including src, class, alt, title.
    769797 */
    770798function _wp_post_thumbnail_class_filter_add( $attr ) {
    771799        add_filter( 'wp_get_attachment_image_attributes', '_wp_post_thumbnail_class_filter' );
     
    772800}
    773801
    774802/**
    775  * Removes _wp_post_thumbnail_class_filter from the wp_get_attachment_image_attributes filter
     803 * Removes the '_wp_post_thumbnail_class_filter' callback from the 'wp_get_attachment_image_attributes'
     804 * filter hook. Internal use only.
    776805 *
     806 * @ignore
    777807 * @since 2.9.0
     808 *
     809 * @param array $attr Thumbnail attributes including src, class, alt, title.
    778810 */
    779811function _wp_post_thumbnail_class_filter_remove( $attr ) {
    780812        remove_filter( 'wp_get_attachment_image_attributes', '_wp_post_thumbnail_class_filter' );
     
    784816add_shortcode('caption', 'img_caption_shortcode');
    785817
    786818/**
    787  * The Caption shortcode.
     819 * Builds the Caption shortcode output.
    788820 *
    789821 * Allows a plugin to replace the content that would otherwise be returned. The
    790822 * filter is 'img_caption_shortcode' and passes an empty string, the attr
     
    795827 *
    796828 * @since 2.6.0
    797829 *
    798  * @param array $attr {
     830 * @param array  $attr {
    799831 *     Attributes of the caption shortcode.
    800832 *
    801833 *     @type string $id      ID of the div element for the caption.
     
    805837 *     @type string $caption The caption text.
    806838 *     @type string $class   Additional class name(s) added to the caption container.
    807839 * }
    808  * @param string $content Optional. Shortcode content.
     840 * @param string $content Shortcode content.
    809841 * @return string HTML content to display the caption.
    810842 */
    811843function img_caption_shortcode( $attr, $content = null ) {
     
    887919add_shortcode('gallery', 'gallery_shortcode');
    888920
    889921/**
    890  * The Gallery shortcode.
     922 * Builds the Gallery shortcode output.
    891923 *
    892924 * This implements the functionality of the Gallery Shortcode for displaying
    893925 * WordPress images on a post.
     
    11051137}
    11061138
    11071139/**
    1108  * Output the templates used by playlists.
     1140 * Outputs the templates used by playlists.
    11091141 *
    11101142 * @since 3.9.0
    11111143 */
     
    11431175}
    11441176
    11451177/**
    1146  * Output and enqueue default scripts and styles for playlists.
     1178 * Outputs and enqueue default scripts and styles for playlists.
    11471179 *
    11481180 * @since 3.9.0
    11491181 *
     
    11601192}
    11611193
    11621194/**
    1163  * The playlist shortcode.
     1195 * Builds the Playlist shortcode output.
    11641196 *
    11651197 * This implements the functionality of the playlist shortcode for displaying
    11661198 * a collection of WordPress audio or video files in a post.
     
    14061438add_shortcode( 'playlist', 'wp_playlist_shortcode' );
    14071439
    14081440/**
    1409  * Provide a No-JS Flash fallback as a last resort for audio / video
     1441 * Provides a No-JS Flash fallback as a last resort for audio / video.
    14101442 *
    14111443 * @since 3.6.0
    14121444 *
    1413  * @param string $url
    1414  * @return string Fallback HTML
     1445 * @param string $url The media element URL.
     1446 * @return string Fallback HTML.
    14151447 */
    14161448function wp_mediaelement_fallback( $url ) {
    14171449        /**
     
    14261458}
    14271459
    14281460/**
    1429  * Return a filtered list of WP-supported audio formats.
     1461 * Returns a filtered list of WP-supported audio formats.
    14301462 *
    14311463 * @since 3.6.0
    1432  * @return array
     1464 *
     1465 * @return array Supported audio formats.
    14331466 */
    14341467function wp_get_audio_extensions() {
    14351468        /**
     
    14441477}
    14451478
    14461479/**
    1447  * Return useful keys to use to lookup data from an attachment's stored metadata.
     1480 * Returns useful keys to use to lookup data from an attachment's stored metadata.
    14481481 *
    14491482 * @since 3.9.0
    14501483 *
    14511484 * @param WP_Post $attachment The current attachment, provided for context.
    1452  * @param string  $context    The context. Accepts 'edit', 'display'. Default 'display'.
     1485 * @param string  $context    Optional. The context. Accepts 'edit', 'display'. Default 'display'.
    14531486 * @return array Key/value pairs of field keys to labels.
    14541487 */
    14551488function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) {
     
    14791512        return apply_filters( 'wp_get_attachment_id3_keys', $fields, $attachment, $context );
    14801513}
    14811514/**
    1482  * The Audio shortcode.
     1515 * Builds the Audio shortcode output.
    14831516 *
    14841517 * This implements the functionality of the Audio Shortcode for displaying
    14851518 * WordPress mp3s in a post.
     
    14861519 *
    14871520 * @since 3.6.0
    14881521 *
    1489  * @param array $attr {
     1522 * @param array  $attr {
    14901523 *     Attributes of the audio shortcode.
    14911524 *
    14921525 *     @type string $src      URL to the source of the audio file. Default empty.
     
    14971530 *     @type string $id       The 'id' attribute for the `<audio>` element. Default 'audio-{$post_id}-{$instance}'.
    14981531 *     @type string $style    The 'style' attribute for the `<audio>` element. Default 'width: 100%'.
    14991532 * }
    1500  * @param string $content Optional. Shortcode content.
     1533 * @param string $content Shortcode content.
    15011534 * @return string HTML content to display audio.
    15021535 */
    15031536function wp_audio_shortcode( $attr, $content = '' ) {
     
    16531686add_shortcode( 'audio', 'wp_audio_shortcode' );
    16541687
    16551688/**
    1656  * Return a filtered list of WP-supported video formats
     1689 * Returns a filtered list of WP-supported video formats.
    16571690 *
    16581691 * @since 3.6.0
    1659  * @return array
     1692 *
     1693 * @return array List of supported video formats.
    16601694 */
    16611695function wp_get_video_extensions() {
    16621696        /**
     
    16711705}
    16721706
    16731707/**
    1674  * The Video shortcode.
     1708 * Builds the Video shortcode output.
    16751709 *
    16761710 * This implements the functionality of the Video Shortcode for displaying
    16771711 * WordPress mp4s in a post.
     
    16781712 *
    16791713 * @since 3.6.0
    16801714 *
    1681  * @param array $attr {
     1715 * @param array  $attr {
    16821716 *     Attributes of the shortcode.
    16831717 *
    16841718 *     @type string $src      URL to the source of the video file. Default empty.
     
    16941728 *     @type string $id       The 'id' attribute for the `<video>` element.
    16951729 *                            Default 'video-{$post_id}-{$instance}'.
    16961730 * }
    1697  * @param string $content Optional. Shortcode content.
     1731 * @param string $content Shortcode content.
    16981732 * @return string HTML content to display video.
    16991733 */
    17001734function wp_video_shortcode( $attr, $content = '' ) {
     
    19061940add_shortcode( 'video', 'wp_video_shortcode' );
    19071941
    19081942/**
    1909  * Display previous image link that has the same post parent.
     1943 * Displays previous image link that has the same post parent.
    19101944 *
    19111945 * @since 2.5.0
    1912  * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string. 0 or 'none' will default to post_title or $text;
    1913  * @param string $text Optional, default is false. If included, link will reflect $text variable.
    1914  * @return string HTML content.
     1946 *
     1947 * @see adjacent_image_link()
     1948 *
     1949 * @param string|array $size Optional. Registered image size or flat array of height and width dimensions.
     1950 *                           0 or 'none' will default to 'post_title' or `$text`. Default 'thumbnail'.
     1951 * @param string $text Optional. Link text. Default false.
     1952 * @return string HTML output for the previous image link.
    19151953 */
    1916 function previous_image_link($size = 'thumbnail', $text = false) {
     1954function previous_image_link( $size = 'thumbnail', $text = false ) {
    19171955        adjacent_image_link(true, $size, $text);
    19181956}
    19191957
    19201958/**
    1921  * Display next image link that has the same post parent.
     1959 * Displays next image link that has the same post parent.
    19221960 *
    19231961 * @since 2.5.0
    1924  * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string. 0 or 'none' will default to post_title or $text;
    1925  * @param string $text Optional, default is false. If included, link will reflect $text variable.
    1926  * @return string HTML content.
     1962 *
     1963 * @see adjacent_image_link()
     1964 *
     1965 * @param string|array $size Optional. Registered image size or flat array of height and width dimensions.
     1966 *                           0 or 'none' will default to 'post_title' or `$text`. Default 'thumbnail'.
     1967 * @param string $text Optional. Link text. Default false.
     1968 * @return string HTML output for the next image link.
    19271969 */
    19281970function next_image_link($size = 'thumbnail', $text = false) {
    19291971        adjacent_image_link(false, $size, $text);
     
    19301972}
    19311973
    19321974/**
    1933  * Display next or previous image link that has the same post parent.
     1975 * Displays next or previous image link that has the same post parent.
    19341976 *
    19351977 * Retrieves the current attachment object from the $post global.
    19361978 *
    19371979 * @since 2.5.0
    19381980 *
    1939  * @param bool $prev Optional. Default is true to display previous link, false for next.
     1981 * @param bool         $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
     1982 * @param string|array $size Optional. Registered image size or flat array of height and width dimensions.
     1983 *                                     Default 'thumbnail'.
     1984 * @param bool         $text Optional. Link text. Default false.
     1985 * @return string The adjacent image link.
    19401986 */
    1941 function adjacent_image_link($prev = true, $size = 'thumbnail', $text = false) {
     1987function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
    19421988        $post = get_post();
    19431989        $attachments = array_values( get_children( array( 'post_parent' => $post->post_parent, 'post_status' => 'inherit', 'post_type' => 'attachment', 'post_mime_type' => 'image', 'order' => 'ASC', 'orderby' => 'menu_order ID' ) ) );
    19441990
     
    19792025}
    19802026
    19812027/**
    1982  * Retrieve taxonomies attached to the attachment.
     2028 * Retrieves taxonomies attached to given the attachment.
    19832029 *
    19842030 * @since 2.5.0
    19852031 *
    1986  * @param int|array|object $attachment Attachment ID, Attachment data array, or Attachment data object.
     2032 * @param int|array|object $attachment Attachment ID, data array, or data object.
    19872033 * @return array Empty array on failure. List of taxonomies on success.
    19882034 */
    1989 function get_attachment_taxonomies($attachment) {
     2035function get_attachment_taxonomies( $attachment ) {
    19902036        if ( is_int( $attachment ) ) {
    19912037                $attachment = get_post( $attachment );
    19922038        } elseif ( is_array( $attachment ) ) {
     
    20182064}
    20192065
    20202066/**
    2021  * Return all of the taxonomy names that are registered for attachments.
     2067 * Retrieves all of the taxonomy names that are registered for attachments.
    20222068 *
    20232069 * Handles mime-type-specific taxonomies such as attachment:image and attachment:video.
    20242070 *
    20252071 * @since 3.5.0
    2026  * @see get_attachment_taxonomies()
    20272072 *
    2028  * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
     2073 * @see get_taxonomies()
     2074 *
     2075 * @param string $output Optional. The type of taxonomy output to return. Accepts 'names' or 'objects'.
     2076 *                       Default 'names'.
    20292077 * @return array The names of all taxonomy of $object_type.
    20302078 */
    20312079function get_taxonomies_for_attachments( $output = 'names' ) {
     
    20472095
    20482096/**
    20492097 * Create new GD image resource with transparency support
    2050  * @TODO: Deprecate if possible.
    20512098 *
     2099 * @todo: Deprecate if possible.
     2100 *
    20522101 * @since 2.9.0
    20532102 *
    2054  * @param int $width Image width
    2055  * @param int $height Image height
    2056  * @return resource resource
     2103 * @param int $width  Image width in pixels.
     2104 * @param int $height Image height in pixels..
     2105 * @return resource The GD image resource.
    20572106 */
    20582107function wp_imagecreatetruecolor($width, $height) {
    20592108        $img = imagecreatetruecolor($width, $height);
     
    20652114}
    20662115
    20672116/**
    2068  * Register an embed handler. This function should probably only be used for sites that do not support oEmbed.
     2117 * Registers an embed handler.
    20692118 *
     2119 * Should probably only be used for sites that do not support oEmbed.
     2120 *
    20702121 * @since 2.9.0
     2122 *
    20712123 * @see WP_Embed::register_handler()
    20722124 *
    2073  * @global WP_Embed $wp_embed
    2074  * @param string   $id
    2075  * @param string   $regex
    2076  * @param callable $callback
    2077  * @param int      $priority
     2125 * @param string   $id       An internal ID/name for the handler. Needs to be unique.
     2126 * @param string   $regex    The regex that will be used to see if this handler should be used for a URL.
     2127 * @param callback $callback The callback function that will be called if the regex is matched.
     2128 * @param int      $priority Optional. Used to specify the order in which the registered handlers will
     2129 *                           be tested. Default 10.
    20782130 */
    20792131function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
    20802132        global $wp_embed;
     
    20822134}
    20832135
    20842136/**
    2085  * Unregister a previously registered embed handler.
     2137 * Unregisters a previously-registered embed handler.
    20862138 *
    20872139 * @since 2.9.0
     2140 *
    20882141 * @see WP_Embed::unregister_handler()
    20892142 *
    2090  * @global WP_Embed $wp_embed
    2091  * @param string $id
    2092  * @param int    $priority
     2143 * @param string $id       The handler ID that should be removed.
     2144 * @param int    $priority Optional. The priority of the handler to be removed. Default 10.
    20932145 */
    20942146function wp_embed_unregister_handler( $id, $priority = 10 ) {
    20952147        global $wp_embed;
     
    21382190 *
    21392191 * @since 2.9.0
    21402192 *
    2141  * @param int $example_width The width of an example embed.
     2193 * @see wp_constrain_dimensions()
     2194 *
     2195 * @param int $example_width  The width of an example embed.
    21422196 * @param int $example_height The height of an example embed.
    2143  * @param int $max_width The maximum allowed width.
    2144  * @param int $max_height The maximum allowed height.
     2197 * @param int $max_width      The maximum allowed width.
     2198 * @param int $max_height     The maximum allowed height.
    21452199 * @return array The maximum possible width and height based on the example ratio.
    21462200 */
    21472201function wp_expand_dimensions( $example_width, $example_height, $max_width, $max_height ) {
     
    21572211 * Attempts to fetch the embed HTML for a provided URL using oEmbed.
    21582212 *
    21592213 * @since 2.9.0
     2214 *
    21602215 * @see WP_oEmbed
    21612216 *
    2162  * @param string $url The URL that should be embedded.
    2163  * @param array $args Additional arguments and parameters.
     2217 * @param string $url  The URL that should be embedded.
     2218 * @param array  $args Optional. Additional arguments and parameters for retrieving embed HTML.
     2219 *                     Default empty.
    21642220 * @return false|string False on failure or the embed HTML on success.
    21652221 */
    21662222function wp_oembed_get( $url, $args = '' ) {
     
    21732229 * Adds a URL format and oEmbed provider URL pair.
    21742230 *
    21752231 * @since 2.9.0
     2232 *
    21762233 * @see WP_oEmbed
    21772234 *
    2178  * @param string $format The format of URL that this provider can handle. You can use asterisks as wildcards.
    2179  * @param string $provider The URL to the oEmbed provider.
    2180  * @param boolean $regex Whether the $format parameter is in a regex format.
     2235 * @param string  $format   The format of URL that this provider can handle. You can use asterisks
     2236 *                          as wildcards.
     2237 * @param string  $provider The URL to the oEmbed provider.
     2238 * @param boolean $regex    Optional. Whether the `$format` parameter is in a RegEx format. Default false.
    21812239 */
    21822240function wp_oembed_add_provider( $format, $provider, $regex = false ) {
    21832241        require_once( ABSPATH . WPINC . '/class-oembed.php' );
     
    21942252 * Removes an oEmbed provider.
    21952253 *
    21962254 * @since 3.5.0
     2255 *
    21972256 * @see WP_oEmbed
    21982257 *
    21992258 * @param string $format The URL format for the oEmbed provider to remove.
     2259 * @return bool Was the provider removed successfully?
    22002260 */
    22012261function wp_oembed_remove_provider( $format ) {
    22022262        require_once( ABSPATH . WPINC . '/class-oembed.php' );
     
    22222282 * it hasn't, then it will load the embeds library.
    22232283 *
    22242284 * @since 2.9.0
     2285 *
     2286 * @see wp_embed_register_handler()
    22252287 */
    22262288function wp_maybe_load_embeds() {
    22272289        /**
     
    22612323}
    22622324
    22632325/**
    2264  * The Google Video embed handler callback. Google Video does not support oEmbed.
     2326 * The Google Video embed handler callback.
    22652327 *
     2328 * Google Video does not support oEmbed.
     2329 *
    22662330 * @see WP_Embed::register_handler()
    22672331 * @see WP_Embed::shortcode()
    22682332 *
    2269  * @param array $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
    2270  * @param array $attr Embed attributes.
    2271  * @param string $url The original URL that was matched by the regex.
    2272  * @param array $rawattr The original unmodified attributes.
     2333 * @param array  $matches The regex matches from the provided regex when calling wp_embed_register_handler().
     2334 * @param array  $attr    Embed attributes.
     2335 * @param string $url     The original URL that was matched by the regex.
     2336 * @param array  $rawattr The original unmodified attributes.
    22732337 * @return string The embed HTML.
    22742338 */
    22752339function wp_embed_handler_googlevideo( $matches, $attr, $url, $rawattr ) {
     
    23032367 * @since 4.0.0
    23042368 *
    23052369 * @param array  $matches The regex matches from the provided regex when calling
    2306  *                        {@see wp_embed_register_handler()}.
     2370 *                        wp_embed_register_handler().
    23072371 * @param array  $attr    Embed attributes.
    23082372 * @param string $url     The original URL that was matched by the regex.
    23092373 * @param array  $rawattr The original unmodified attributes.
     
    23122376function wp_embed_handler_youtube( $matches, $attr, $url, $rawattr ) {
    23132377        global $wp_embed;
    23142378        $embed = $wp_embed->autoembed( "https://youtube.com/watch?v={$matches[2]}" );
     2379
    23152380        /**
    23162381         * Filter the YoutTube embed output.
    23172382         *
     
    23322397 *
    23332398 * @since 3.6.0
    23342399 *
    2335  * @param array $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
     2400 * @param array $matches The regex matches from the provided regex when calling wp_embed_register_handler().
    23362401 * @param array $attr Embed attributes.
    23372402 * @param string $url The original URL that was matched by the regex.
    23382403 * @param array $rawattr The original unmodified attributes.
     
    23592424 *
    23602425 * @since 3.6.0
    23612426 *
    2362  * @param array $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
    2363  * @param array $attr Embed attributes.
    2364  * @param string $url The original URL that was matched by the regex.
    2365  * @param array $rawattr The original unmodified attributes.
     2427 * @param array  $matches The regex matches from the provided regex when calling wp_embed_register_handler().
     2428 * @param array  $attr    Embed attributes.
     2429 * @param string $url     The original URL that was matched by the regex.
     2430 * @param array  $rawattr The original unmodified attributes.
    23662431 * @return string The embed HTML.
    23672432 */
    23682433function wp_embed_handler_video( $matches, $attr, $url, $rawattr ) {
     
    24072472}
    24082473
    24092474/**
    2410  * Determine the maximum upload size allowed in php.ini.
     2475 * Determines the maximum upload size allowed in php.ini.
    24112476 *
    24122477 * @since 2.5.0
    24132478 *
     
    24332498 * Returns a WP_Image_Editor instance and loads file into it.
    24342499 *
    24352500 * @since 3.5.0
    2436  * @access public
    24372501 *
    2438  * @param string $path Path to file to load
    2439  * @param array $args Additional data. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }
    2440  * @return WP_Image_Editor|WP_Error
     2502 * @param string $path Path to the file to load.
     2503 * @param array  $args Optional. Additional arguments for retrieving the image editor.
     2504 *                     Default empty array.
     2505 * @return WP_Image_Editor|WP_Error The WP_Image_Editor object if successful, an WP_Error
     2506 *                                  object otherwise.
    24412507 */
    24422508function wp_get_image_editor( $path, $args = array() ) {
    24432509        $args['path'] = $path;
     
    24702536 * Tests whether there is an editor that supports a given mime type or methods.
    24712537 *
    24722538 * @since 3.5.0
    2473  * @access public
    24742539 *
    2475  * @param string|array $args Array of requirements. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }
    2476  * @return boolean true if an eligible editor is found; false otherwise
     2540 * @param string|array $args Optional. Array of arguments to retrieve the image editor supports.
     2541 *                           Default empty array.
     2542 * @return bool True if an eligible editor is found; false otherwise.
    24772543 */
    24782544function wp_image_editor_supports( $args = array() ) {
    24792545        return (bool) _wp_image_editor_choose( $args );
     
    24822548/**
    24832549 * Tests which editors are capable of supporting the request.
    24842550 *
     2551 * @ignore
    24852552 * @since 3.5.0
    2486  * @access private
    24872553 *
    2488  * @param array $args Additional data. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }
    2489  * @return string|bool Class name for the first editor that claims to support the request. False if no editor claims to support the request.
     2554 * @param array $args Optional. Array of arguments for choosing a capable editor. Default empty array.
     2555 * @return string|bool Class name for the first editor that claims to support the request. False if no
     2556 *                     editor claims to support the request.
    24902557 */
    24912558function _wp_image_editor_choose( $args = array() ) {
    24922559        require_once ABSPATH . WPINC . '/class-wp-image-editor.php';
     
    27982865 * all media JS APIs.
    27992866 *
    28002867 * @since 3.5.0
     2868 *
     2869 * @param array $args {
     2870 *     Arguments for enqueuing media scripts.
     2871 *
     2872 *     @type int|WP_Post A post object or ID.
     2873 * }
     2874 * @return array List of media view settings.
    28012875 */
    28022876function wp_enqueue_media( $args = array() ) {
    28032877
     
    30893163}
    30903164
    30913165/**
    3092  * Retrieve media attached to the passed post.
     3166 * Retrieves media attached to the passed post.
    30933167 *
    30943168 * @since 3.6.0
    30953169 *
     
    31413215 * @since 3.6.0
    31423216 *
    31433217 * @param string $content A string which might contain media data.
    3144  * @param array $types array of media types: 'audio', 'video', 'object', 'embed', or 'iframe'
    3145  * @return array A list of found HTML media embeds
     3218 * @param array  $types   An array of media types: 'audio', 'video', 'object', 'embed', or 'iframe'.
     3219 * @return array A list of found HTML media embeds.
    31463220 */
    31473221function get_media_embedded_in_content( $content, $types = null ) {
    31483222        $html = array();
     
    31633237}
    31643238
    31653239/**
    3166  * Retrieve galleries from the passed post's content.
     3240 * Retrieves galleries from the passed post's content.
    31673241 *
    31683242 * @since 3.6.0
    31693243 *
    3170  * @param int|WP_Post $post Optional. Post ID or object.
    3171  * @param bool        $html Whether to return HTML or data in the array.
     3244 * @param int|WP_Post $post Post ID or object.
     3245 * @param bool        $html Optional. Whether to return HTML or data in the array. Default true.
    31723246 * @return array A list of arrays, each containing gallery data and srcs parsed
    3173  *                       from the expanded shortcode.
     3247 *               from the expanded shortcode.
    31743248 */
    31753249function get_post_galleries( $post, $html = true ) {
    31763250        if ( ! $post = get_post( $post ) )
     
    32203294 * @since 3.6.0
    32213295 *
    32223296 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
    3223  * @param bool        $html Whether to return HTML or data.
     3297 * @param bool        $html Optional. Whether to return HTML or data. Default is true.
    32243298 * @return string|array Gallery data and srcs parsed from the expanded shortcode.
    32253299 */
    32263300function get_post_gallery( $post = 0, $html = true ) {
     
    32443318 *
    32453319 * @since 3.6.0
    32463320 *
    3247  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
     3321 * @see get_post_galleries()
     3322 *
     3323 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
    32483324 * @return array A list of lists, each containing image srcs parsed.
    3249  *              from an expanded shortcode
     3325 *               from an expanded shortcode
    32503326 */
    32513327function get_post_galleries_images( $post = 0 ) {
    32523328        $galleries = get_post_galleries( $post, false );
     
    32543330}
    32553331
    32563332/**
    3257  * Check a post's content for galleries and return the image srcs for the first found gallery
     3333 * Checks a post's content for galleries and return the image srcs for the first found gallery
    32583334 *
    32593335 * @since 3.6.0
    32603336 *
    3261  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
     3337 * @see get_post_gallery()
     3338 *
     3339 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
    32623340 * @return array A list of a gallery's image srcs in order.
    32633341 */
    32643342function get_post_gallery_images( $post = 0 ) {
     
    32673345}
    32683346
    32693347/**
    3270  * Maybe attempt to generate attachment metadata, if missing.
     3348 * Maybe attempts to generate attachment metadata, if missing.
    32713349 *
    32723350 * @since 3.9.0
    32733351 *
     
    32923370}
    32933371
    32943372/**
    3295  * Try to convert an attachment URL into a post ID.
     3373 * Tries to convert an attachment URL into a post ID.
    32963374 *
    32973375 * @since 4.0.0
    32983376 *
     
    33213399}
    33223400
    33233401/**
    3324  * Return the URLs for CSS files used in an iframe-sandbox'd TinyMCE media view.
     3402 * Returns the URLs for CSS files used in an iframe-sandbox'd TinyMCE media view.
    33253403 *
    33263404 * @since 4.0.0
    33273405 *