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. // The html. 
  5. $html = ''; 
  6.  
  7. // The id. 
  8. $id = null; 
  9.  
  10. // image caption 
  11. $caption = ''; 
  12.  
  13. // image title attribute 
  14. $title = ''; 
  15.  
  16. // image css alignment property 
  17. $align = ''; 
  18.  
  19. // image src url 
  20. $url = ''; 
  21.  
  22. // image size (thumbnail, medium, large, full or added with add_image_size() ) 
  23. $size = ''; 
  24.  
  25. // image alt attribute 
  26. $alt = ''; 
  27.  
  28. // NOTICE! Understand what this does before running. 
  29. $result = image_add_caption($html, $id, $caption, $title, $align, $url, $size, $alt); 
  30.  

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