WordPress Version: 6.5
/**
* 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'.
*
* @since 2.6.0
* @since 3.9.0 The `class` attribute was added.
* @since 5.1.0 The `caption_id` attribute was added.
* @since 5.9.0 The `$content` parameter default value changed from `null` to `''`.
*
* @param array $attr {
* Attributes of the caption shortcode.
*
* @type string $id ID of the image and caption container element, i.e. `<figure>` or `<div>`.
* @type string $caption_id ID of the caption element, i.e. `<figcaption>` or `<p>`.
* @type string $align Class name that aligns the caption. Default 'alignnone'. Accepts 'alignleft',
* 'aligncenter', alignright', 'alignnone'.
* @type int $width The width of the caption, in pixels.
* @type string $caption The caption text.
* @type string $class Additional class name(s) added to the caption container.
* }
* @param string $content Optional. Shortcode content. Default empty string.
* @return string HTML content to display the caption.
*/
function img_caption_shortcode($attr, $content = '')
{
// New-style shortcode with the caption inside the shortcode with the link and image tags.
if (!isset($attr['caption'])) {
if (preg_match('#((?:<a [^>]+>\s*)?<img [^>]+>(?:\s*</a>)?)(.*)#is', $content, $matches)) {
$content = $matches[1];
$attr['caption'] = trim($matches[2]);
}
} elseif (str_contains($attr['caption'], '<')) {
$attr['caption'] = wp_kses($attr['caption'], 'post');
}
/**
* Filters the default caption shortcode output.
*
* If the filtered output isn't empty, it will be used instead of generating
* the default caption template.
*
* @since 2.6.0
*
* @see img_caption_shortcode()
*
* @param string $output The caption output. Default empty.
* @param array $attr Attributes of the caption shortcode.
* @param string $content The image element, possibly wrapped in a hyperlink.
*/
$output = apply_filters('img_caption_shortcode', '', $attr, $content);
if (!empty($output)) {
return $output;
}
$atts = shortcode_atts(array('id' => '', 'caption_id' => '', 'align' => 'alignnone', 'width' => '', 'caption' => '', 'class' => ''), $attr, 'caption');
$atts['width'] = (int) $atts['width'];
if ($atts['width'] < 1 || empty($atts['caption'])) {
return $content;
}
$id = '';
$caption_id = '';
$describedby = '';
if ($atts['id']) {
$atts['id'] = sanitize_html_class($atts['id']);
$id = 'id="' . esc_attr($atts['id']) . '" ';
}
if ($atts['caption_id']) {
$atts['caption_id'] = sanitize_html_class($atts['caption_id']);
} elseif ($atts['id']) {
$atts['caption_id'] = 'caption-' . str_replace('_', '-', $atts['id']);
}
if ($atts['caption_id']) {
$caption_id = 'id="' . esc_attr($atts['caption_id']) . '" ';
$describedby = 'aria-describedby="' . esc_attr($atts['caption_id']) . '" ';
}
$class = trim('wp-caption ' . $atts['align'] . ' ' . $atts['class']);
$html5 = current_theme_supports('html5', 'caption');
// HTML5 captions never added the extra 10px to the image width.
$width = $html5 ? $atts['width'] : (10 + $atts['width']);
/**
* Filters the width of an image's caption.
*
* By default, the caption is 10 pixels greater than the width of the image,
* to prevent post content from running up against a floated image.
*
* @since 3.7.0
*
* @see img_caption_shortcode()
*
* @param int $width Width of the caption in pixels. To remove this inline style,
* return zero.
* @param array $atts Attributes of the caption shortcode.
* @param string $content The image element, possibly wrapped in a hyperlink.
*/
$caption_width = apply_filters('img_caption_shortcode_width', $width, $atts, $content);
$style = '';
if ($caption_width) {
$style = 'style="width: ' . (int) $caption_width . 'px" ';
}
if ($html5) {
$html = sprintf('<figure %s%s%sclass="%s">%s%s</figure>', $id, $describedby, $style, esc_attr($class), do_shortcode($content), sprintf('<figcaption %sclass="wp-caption-text">%s</figcaption>', $caption_id, $atts['caption']));
} else {
$html = sprintf('<div %s%sclass="%s">%s%s</div>', $id, $style, esc_attr($class), str_replace('<img ', '<img ' . $describedby, do_shortcode($content)), sprintf('<p %sclass="wp-caption-text">%s</p>', $caption_id, $atts['caption']));
}
return $html;
}