wp_create_file_in_uploads Called as Action Hook

[Howdy_McGee]

The ​wp_create_file_in_uploads hook is labeled as an Action Hook in the docs but is actually called multiple times as a Filter Hook.

As an Action Hook: ​class-custom-image-header.php

As a Filter Hook: ​ajax-actions.php, ​class-custom-image-header.php (and more)

To keep the docs accurate, this do_action should be switched to an apply_filters even though, in this case, nothing will be done with the returned value.

[Howdy_McGee]

Action Hook switched to Filter Hook.

[johnbillion]

Notes:

• This hook is called as a filter five times and an action twice.
• ​Its developer reference page documents it as an action.
• ​There are very few plugins that actually hook into this filter/action, although quite a few that call the hook either as an action or a filter (having mostly copied and pasted from core by the looks of things).
• I also think this should be converted to always be a filter. Converting it to always be an action will break existing filters. I'd like a second opinion though.
• The patch needs to be updated to account for both places in core where this is called as an action:
  • ​https://github.com/WordPress/wordpress-develop/blob/f71140438beeae7c251464dbd65946fdab037c84/src/wp-admin/includes/class-custom-background.php#L568
  • ​https://github.com/WordPress/wordpress-develop/blob/f71140438beeae7c251464dbd65946fdab037c84/src/wp-admin/includes/class-custom-image-header.php#L885

[SergeyBiryukov]

Replying to johnbillion:

I also think this should be converted to always be a filter. Converting it to always be an action will break existing filters. I'd like a second opinion though.

That makes sense to me too.

Introduced in [6551] / #5418, setting the version accordingly.

[mhshujon]

If we change the existing action hook to a filter hook as like this https://core.trac.wordpress.org/attachment/ticket/57775/57775.diff , then what's the point of using filter hooks if we don't use the modified $file variable?

Changes instances of wp_create_file_in_uploads from action hooks to filter hooks.

Trac ticket: https://core.trac.wordpress.org/ticket/57775

[nicolefurlan]

I just added a PR that changes both instances of wp_create_file_in_uploads from action hooks to filter hooks.

I also created a docs issue (​https://github.com/WordPress/Documentation-Issue-Tracker/issues/1139) so that ​https://developer.wordpress.org/reference/hooks/wp_create_file_in_uploads/ can get updated to match this change. Please do let me know if that was the incorrect thing to do. I'd love to know how we can coordinate with the docs team on timing to make sure the code and documentation changes happen at the same time.

[nicolefurlan]

Testing Instructions

These steps define how to test the feature or enhancement, and indicates the expected behavior or results.

Steps to Test

1. Install and activate theme Twenty Fifteen or older.
2. Upload a custom header image on Appearance > Header.
   • To ensure we're encountering the code we changed, the uploaded image should be the exact dimensions (954x1300) e.g. ​https://i0.wp.com/www.ciderschool.com/wp-content/uploads/2015/01/cropped-apple_closeup-1024x683.jpg?fit=954%2C1300&ssl=1
3. Upload an custom background image on Appearance > Background.

Expected Results

Lists each expected result or behavior, i.e. what should happen when running the test(s):

• ✅ Uploading a custom header image on Appearance > Header continues to work as expected (the selected image is uploaded to the Media Library and displays properly on the frontend)
• ✅ Uploading a custom background image on Appearance > Background continues to work as expected (the selected image is uploaded to the Media Library and displays properly on the frontend)

Supplemental Artifacts

• ​https://codex.wordpress.org/Appearance_Header_Screen
• ​https://codex.wordpress.org/Appearance_Background_Screen

[nicolefurlan]

Removing 2nd-opinion since @SergeyBiryukov weighed in an provided an opinion.

This PR just needs testing. It would be great to get this wrapped up in 6.4.

[SergeyBiryukov]

In 56929:

Media: Consistently call the wp_create_file_in_uploads hook as a filter.

The filter was initially introduced for file replication purposes. Since the returned value is not always used directly, some instances were later converted to an action as part of removing unused variables, and the hook was documented as an action while still being called as a filter in other instances.

This commit aims to correct the discrepancy between the code and the documentation.

Follow-up to [4673], [4817], [4818], [6363], [6551], [13041], [25821], [33154], [33280].

Props Howdy_McGee, nicolefurlan, johnbillion, mhshujon, SergeyBiryukov.
Fixes #57775.

Thanks for the PR! Merged in r56929.

[SergeyBiryukov]

Replying to nicolefurlan:

I also created a docs issue (​https://github.com/WordPress/Documentation-Issue-Tracker/issues/1139) so that ​https://developer.wordpress.org/reference/hooks/wp_create_file_in_uploads/ can get updated to match this change. Please do let me know if that was the incorrect thing to do. I'd love to know how we can coordinate with the docs team on timing to make sure the code and documentation changes happen at the same time.

Thanks! As far as I can tell, the docs issue is not necessary here, the documentation will be updated automatically as soon as 6.4 is released and the DevHub code reference parser is run as part of the ​post-release tasks.

[nicolefurlan]

Oh that's good to know! Thank you @SergeyBiryukov – I'll close that docs ticket.