image_add_caption

Adds image shortcode with caption to editor.

Description

(string) image_add_caption( (string) $html, (integer) $id, (string) $caption, (string) $title, (string) $align, (string) $url, (string) $size, (string) $alt = '' ); 

Returns (string)

Parameters (8)

0. $html (string)
The html.
1. $id (integer)
The id.
2. $caption (string)
Image caption
3. $title (string)
Image title attribute
4. $align (string)
Image css alignment property
5. $url (string)
Image src url
6. $size (string)
Image size (thumbnail, medium, large, full or added with add_image_size(…) )
7. $alt — Optional. (string) => ''
Image alt attribute

Usage

  1. if ( !function_exists( 'image_add_caption' ) ) { 
  2.     require_once ABSPATH . '/wp-admin/includes/media.php'; 
  3. } 
  4.   
  5. // The html. 
  6. $html = ''; 
  7.   
  8. // The id. 
  9. $id = null; 
  10.   
  11. // image caption 
  12. $caption = ''; 
  13.   
  14. // image title attribute 
  15. $title = ''; 
  16.   
  17. // image css alignment property 
  18. $align = ''; 
  19.   
  20. // image src url 
  21. $url = ''; 
  22.   
  23. // image size (thumbnail, medium, large, full or added with add_image_size() ) 
  24. $size = ''; 
  25.   
  26. // image alt attribute 
  27. $alt = ''; 
  28.   
  29. // NOTICE! Understand what this does before running. 
  30. $result = image_add_caption($html, $id, $caption, $title, $align, $url, $size, $alt); 
  31.     

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/media.php  
  1. function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $alt = '' ) { 
  2.  
  3.     /** 
  4.      * Filters the caption text. 
  5.      * 
  6.      * Note: If the caption text is empty, the caption shortcode will not be appended 
  7.      * to the image HTML when inserted into the editor. 
  8.      * 
  9.      * Passing an empty value also prevents the {@see 'image_add_caption_shortcode'} 
  10.      * Filters from being evaluated at the end of image_add_caption(). 
  11.      * 
  12.      * @since 4.1.0 
  13.      * 
  14.      * @param string $caption The original caption text. 
  15.      * @param int    $id      The attachment ID. 
  16.      */ 
  17.     $caption = apply_filters( 'image_add_caption_text', $caption, $id ); 
  18.  
  19.     /** 
  20.      * Filters whether to disable captions. 
  21.      * 
  22.      * Prevents image captions from being appended to image HTML when inserted into the editor. 
  23.      * 
  24.      * @since 2.6.0 
  25.      * 
  26.      * @param bool $bool Whether to disable appending captions. Returning true to the filter 
  27.      *                   will disable captions. Default empty string. 
  28.      */ 
  29.     if ( empty($caption) || apply_filters( 'disable_captions', '' ) ) 
  30.         return $html; 
  31.  
  32.     $id = ( 0 < (int) $id ) ? 'attachment_' . $id : ''; 
  33.  
  34.     if ( ! preg_match( '/width=["\']([0-9]+)/', $html, $matches ) ) 
  35.         return $html; 
  36.  
  37.     $width = $matches[1]; 
  38.  
  39.     $caption = str_replace( array("\r\n", "\r"), "\n", $caption); 
  40.     $caption = preg_replace_callback( '/<[a-zA-Z0-9]+(?: [^<>]+>)*/', '_cleanup_image_add_caption', $caption ); 
  41.  
  42.     // Convert any remaining line breaks to <br>. 
  43.     $caption = preg_replace( '/[ \n\t]*\n[ \t]*/', '<br />', $caption ); 
  44.  
  45.     $html = preg_replace( '/(class=["\'][^\'"]*)align(none|left|right|center)\s?/', '$1', $html ); 
  46.     if ( empty($align) ) 
  47.         $align = 'none'; 
  48.  
  49.     $shcode = '[caption id="' . $id . '" align="align' . $align    . '" width="' . $width . '"]' . $html . ' ' . $caption . '[/caption]'; 
  50.  
  51.     /** 
  52.      * Filters the image HTML markup including the caption shortcode. 
  53.      * 
  54.      * @since 2.6.0 
  55.      * 
  56.      * @param string $shcode The image HTML markup with caption shortcode. 
  57.      * @param string $html   The image HTML markup. 
  58.      */ 
  59.     return apply_filters( 'image_add_caption_shortcode', $shcode, $html ); 
  60. }