Changing WordPress Post Image Tags Using wp_content_img_tag

Content:

With the release of WordPress 6.0, a new hook has been created to make it easier to control your post image tags.

Prior to WordPress 6.0, tweaking the display of your image posts involved setting up a filter on the_content(). With no built-in way of targeting img tags, you’d need to manually parse the content to find the image tags.

This could be done using the libxml DOMDocument parser, through regex, or through the more simple string replace functions.

While this could work, it’s not an elegant solution.

The new hook, named wp_content_img_tag, makes img tags much easier to target.

Using the Hook

wp_content_img_tag provides up to 3 parameters:

• image url (string): URL of the image
• context (string): The context from which the hook was called – probably the_content()
• id (int): Attachment ID of the image

A filter using the hook must accept the image url parameter. The other two parameters are optional.

function qb_test_content_img_tag($image)
{
    // Do stuff with $image
}

The $image parameter is a string, containing the entire HTML used to display an image. By default, this begins with <figure> tags, with the <img> tag inside.

You can get and set attributes on this tag by loading it into a DOMDocument element.

function qb_test_content_img_tag($image)
{
    $dom = new DOMDocument();
    $dom->loadHTML($image);

    $img = $dom->getElementsByTagName('img')[0];
    $src = $img->getAttribute('src');
    $alt = $img->getAttribute('alt');
    $img->setAttribute('height', 1000);
}

To use this function with the hook, add a call to add_filter().

add_filter('wp_content_img_tag', qb_test_content_img_tag);

For basic usage, this is enough. If you want to use the two additional parameters, however, there’s a couple of extra things to add. You’ll need to add a priority, and parameter count to this call.

add_filter('wp_content_img_tag', qb_test_content_img_tag, 10, 3);

The priority becomes important when using this alongside other filters. If you’re making changes here which are later used by another filter, it’s important for this one to have a higher priority.

A parameter count of 3 will provide all three fields – be sure to add variables for them into your constructor.

function qb_test_content_img_tag($image, $context, $id) {...}

Using the additional parameters opens up even more possibilities.

What Can I Do With It?

With specific access to each <img> tag in your content, you can add pretty much any transformation you can think of. It will specifically target each <img> tag in your page content.

This site uses the wp_content_img_tag hook, to provide a link to full-sized copies of our images.

Want to get the full sized version of the provided image?

function qb_add_full_size_link($image, $context, $id)
{
    if (!$full_src = wp_get_attachment_image_src($id, 'full')) {
        return $image;
    }

    $doc = new DOMDocument();
    $doc->loadHTML($image);
    $image = $doc->getElementsByTagName('img')[0];
    $figure = $image->parentNode;

    $a = $doc->createElement('a');
    $a->setAttribute('href', $full_src[0]);

    $a->appendChild($image);
    $figure->appendChild($a);

    return $doc->saveHTML();
}

add_filter('wp_content_img_tag', qb_add_full_size_link, 10, 3);

This uses the DOMDocument parser to create a new <a> element, move the <img> from the <figure> to the new <a> element, and add the <a> to the <figure> element.

<figure>
    <img>
</figure>

Becomes…

<figure>
    <a>
        <img>
    </a>
</figure>

This is just one example of what’s possible.

If you’ve ever wanted to alter the way <img> tags display on your WordPress site, be sure to check out wp_content_img_tag.