Add an action for wp_media_attach_action events

[jonoaldersonwp]

When a user attaches or detaches media to/from a post, wp_media_attach_action() is called.

See ​https://github.com/WordPress/WordPress/blob/master/wp-admin/includes/media.php#L3694

This function sets or removes a post_parent value on an attachment post by updating $wpdb->posts.

At the moment, there's no way for plugins or integrations to take action based on these events; making it incredibly difficult to alter or add to the behaviour or outcomes of these processes.

To address this, we should add an action hook following the successful execution of the query (i.e., if $results returns true), using either of the following approaches:

• do_action('wp_media_attach_action', $attach, $attachment_id, $parent_id) (where $attach is true for 'attach' actions, and false for 'detach' actions); OR
• Conditionally either do_action('wp_media_attach_action_attach', $attachment_id, $parent_id) or do_action('wp_media_attach_action_detach', $attachment_id, $parent_id).

This will allow plugins and integrations to take arbitrary action based on attaching/detaching media, with the option to consider the type of action, the parent, and the attachment itself.

Note that I considered that clean_attachment_cache() is hookable (and executed in the wp_media_attach_action() function), but only passes the post_id; lacking the critical context of the parent, and the attachment/detachment status. This also appears to fire before any validation that the query was successful, which strikes me as strange.

[antpb]

This would be a really great one to have added for 5.5. Going to move it into the milestone so we can keep track of it. :)

[rebasaurus]

I've moved the clean_attachment_cache() after the $result check as well.

[donmhico]

Add param docs.

[whyisjake]

In 47909:

Media: Add an action for wp_media_attach_action.

This action fires when media is attached/detached from a post.

Fixes: #49614.
Props: jonoaldersonwp, antpb, rebasaurus, donmhico.

[SergeyBiryukov]

In 47913:

Docs: Update the DocBlock for the wp_media_attach_action hook per the documentation standards.

Rename the $att_id variable to $attachment_id for clarity.

Follow-up to [47909].

See #49614.