before_delete_post More Information: unclear, inaccurate

[TonyGravagno]

Issue Description

Developer note for action before_delete_post is not clear, slightly incorrect, and can be misleading. I think it's just time to refresh that text.

It’s important to note the hook runs only when the WordPress user empties the Trash. If you’re using this hook note that it will not fire if the user is deleting an Attachment, since attachments are force deleted, i.e., not sent to the Trash. Instead use the delete_post() hook.

URL of the Page with the Issue

https://developer.wordpress.org/reference/hooks/before_delete_post/

Section of Page with the issue

More Information

Why is this a problem?

The first statement "the hook runs only when the WordPress user empties the Trash" does not account for forced deletion. The action is run when trash is disabled and an item is deleted, unrelated to emptying trash, ref 5.8.1 source.

Further, trash is not just deleted by a WordPress user - items can be removed automatically as well based on scheduling.

The phrase 'force deleted' is used but it's not clear what this means.

The suggestion to use the delete_post hook is incorrect. Yes, that hook is executed in the cycle of removing an attachment, but not in the same place in the cycle as before_delete_post. For this equivalent we have delete_attachment, and for trash it's wp_trash_post.

I believe it would help a developer to get a brief insight into the trash mechanism while looking at these relevant comments.

Suggested Fix

Replace the paragraph with the following:

• This hook is run just before other data associated with the post is deleted - like meta data. After the other data is deleted, the delete_post action executes, the primary post is removed, and then the deleted_post action is executed.
• This hook is run when items marked for trash are going through final (forced) deletion.
• This hook is not run for posts that are being marked as trash (unforced). The wp_trash_post hook is the functional equivalent, executed just before items are marked as trash.
• This hook is not run for attachments. The delete_attachment hook is the functional equivalent, executed just before posts of type attachment are processed. With attachments, exactly as with other post types, meta data is then removed, then the delete_post action is run, then the attachment is removed from the database, then the deleted_post action is run.

Ref do_action in wp_trash_post() and function wp_delete_attachment().

[zzap]

Thank you @TonyGravagno. I'd suggest just one thing to enhance readability - let's split the list into when the is running and when not.

This hook runs:
- Just before other data associated with the post is deleted - like meta data. After the other data is deleted, the delete_post action executes, the primary post is removed, and then the deleted_post action is executed.
- When items marked for trash are going through final (forced) deletion.

This hook does not run:
- For posts that are being marked as trash (unforced). The wp_trash_post hook is the functional equivalent, executed just before items are marked as trash.
- For attachments. The delete_attachment hook is the functional equivalent, executed just before posts of type attachment are processed. With attachments, exactly as with other post types, meta data is then removed, then the delete_post action is run, then the attachment is removed from the database, then the deleted_post action is run.

I'll leave this to self-assigned @stevenlin-x 🙌

[stevenlinx]

I've revised the Explanation section.

[zzap]

Thank you @TonyGravagno and @stevenlin-x ❤️

@TonyGravagno can you please give me your WordPress.org username. I can't find you there and really want to give you a "contributor" badge :)

[TonyGravagno]

I am WP @starbuck. Thank you @zzap and @stevenlin-x .

[zzap]

@TonyGravagno since you're not on WordPress slack I have to ask you here. Can you please go to this URL while logged in and request membership? Sorry there's no more elegant way to give you recognition for your contributions. Thank you ❤️

[TonyGravagno]

Done. Thanks!

[zzap]

Take a look at your profile 🙌

[TonyGravagno]

I am SOOOOOOOOOO honored. TYVM ... and now on to actually earning those creds...