Allow filtering of `$header` object in `get_header_image_tag()` function (for custom header image override)

[webmandesign]

Currently, when trying to override custom header image, it is only possible to filter header image URL (via theme_mod_header_image ​filter hook) or the actual image ​output HTML in ​get_header_image_tag() function.

It would be beneficial to allow filtering also the $header object of get_header_image_tag() function: in case of override via theme code we can set not only an image URL, but an image attachment ID too. That way the get_header_image_tag() function can do better job with image overrides (such as setting correct image srcset and sizes attributes and also the image alt text).

[webmandesign]

After applying the filter hook in the above patch I realize, it would be better to filter actual ​get_custom_header() function output.

But, there is a caveats doing so: the object's url parameter is overridden in ​get_header_image_tag() function with $header->url = get_header_image(); code and we will need to filter that one too...

I'm not really sure whether this would be possible, but if the url parameter in ​get_custom_header() is set directly to get_header_image() value, we could simply apply the new filter hook on the get_custom_header() output object. In that case my patch would be unnecessary as well as the $header->url = get_header_image(); in get_header_image_tag()).

Anybody can provide some insight on this, whether such solution would be more preferable, and most of all, whether it could work without issues? Thanks!

[webmandesign]

Also, I've named the filter in my patch as header_image_tag_object. That name doesn't really feel correct to me, but I'm not sure what naming convention WordPress uses in these cases, when we are filtering a variable of a function. Any suggestions on hook name improvements are welcome!

[joemcgill]

Thanks for the report, and patch @webmandesign.

It does seem strange that the $header object would be directly overridden in get_header_image_tag() to supply the URL from get_header_image(). It's be worth looking at the change history to see what's happening here. Generally, I would prefer to see a filter in get_custom_header() in order to override any properties of the header object, but that would require figuring out if we could drop the call to get_header_image() from inside get_header_image_tag().

[sabernhardt]

Related/duplicate: #38942

[strarsis]

+1, the custom header image markup currently doesn't contain srcset or sizes - which is usually important for header images that are can be quite large.

[sabernhardt]

replacing $header->url with $header_url variable

[sabernhardt]

replacing $header->url with $header_url variable

[sabernhardt]

Let's keep discussion about the filter on #38942 instead of here.

The URL argument was intentionally changed in #38633. However, if the original URL is valuable in the filter (or another way), we might be able to use a $header_url variable instead of redefining the argument.

[sabernhardt]

update: the get_header_image_tag_attributes filter was added in r51978