image_add_caption() returns immediately if caption empty, preventing filter from firing

[paulschreiber]

In wp-admin/includes/media.php, the function image_add_caption returns immediately if the caption is empty.

Our caption filter adds a credit even if the image has no caption. However, because the filter is only fired at the end of image_add_caption:
apply_filters( 'image_add_caption_shortcode', $shcode, $html );

our filter never gets a chance to run when the caption is blank, so we can't add the credit.

[collinsinternet]

Creation of image_add_caption filter.

[collinsinternet]

I've added a filter to the image_add_caption() function that filters the caption text.

[SergeyBiryukov]

The filter needs to be documented as per the ​documentation standards.

Also, please take a look at ​WordPress coding standards, specifically the Space Usage section.

[collinsinternet]

Documented and up to coding standards.

[collinsinternet]

Ha SergeyBiryukov, that's what I get for working late. Latest patch includes documentation block and code formatting (not sure why my IDE didn't format the first time).

[DrewAPicture]

Rewording

[DrewAPicture]

At first I was concerned about effectively running two filters in a row here, but after further consideration, the new filter really does provide something not currently available -- the ability to directly filter the pre-parse caption text before output to the editor.

In 29607.3.patch​, I've reworded the long description a bit to clarify expected behavior in passing an empty value. I also changed the hook name to 'image_add_caption_text'.

[SergeyBiryukov]

In 29753:

Add 'image_add_caption_text' filter for changing the pre-parse caption text before output to the editor.

props collinsinternet, DrewAPicture.
fixes #29607.

[SergeyBiryukov]

Should we pass the attachment ID to the filter as well?

[SergeyBiryukov]

In 29754:

Pass the attachment ID to the 'image_add_caption_text' filter.

fixes #29607.

[paulschreiber]

This doesn't solve my problem. We want to be able to call image_add_caption_shortcode() even when caption is blank.

The isempty() check is still present:

    if ( empty($caption) || apply_filters( 'disable_captions', '' ) )
        return $html;

Which means the function still returns before we get to call the filter.

[collinsinternet]

@paulschreiber Why can't you add a filter that verifies that the caption is present and appends it if it is blank?

[paulschreiber]

We have some images that do not (and should not) have captions. But they should have photo credits, which are added by our caption filter. However, the caption filter does not get a chance to run when $caption is empty().

[MikeHansenMe]

looking at the code in image_add_caption, if you add something to $caption on line 175 via the filter it should not be empty on line 187 when checked. Then the only way line 188
"return $html" would run is if disable_caption is true(which seems to be expected).

[DrewAPicture]

@MikeHansenMe is correct in comment:13. We need to preserve the existing behavior of the disable_caption filter so the new filter added in [29753] should give you enough rope to manage that. Even passing something like a non-breaking space would bypass the empty/disable_caption check.