[wp-trac] [WordPress Trac] #39286: Standardizing actions and filters for adding, getting, setting, updating, and deleting options and transients

[WordPress Trac]

#39286: Standardizing actions and filters for adding, getting, setting, updating,
and deleting options and transients
--------------------------------+-----------------------------
 Reporter:  NathanAtmoz         |      Owner:
     Type:  enhancement         |     Status:  new
 Priority:  normal              |  Milestone:  Awaiting Review
Component:  Options, Meta APIs  |    Version:
 Severity:  normal              |   Keywords:
  Focuses:                      |
--------------------------------+-----------------------------
 == The Problem ==
 In a nutshell, the problem is that there is no standardization of hooks
 surrounding the options and transient APIs and the hooks presently
 available are inconsistent in their terminology.

 === Issue 1: Add Option ===
 When adding an option to the database, there are presently 3 hook
 available:
 * `add_option`
 * `add_option_{$option}`
 * `added_option`

 There are two main points of confusion:
 * The first point of confusion is that `add_option` is fired before the
 option is added to the database, but `add_option_{$option}` is fired after
 the option is added.
 * The second is that prior to the option being added to the database,
 there is a hook available that will fire anytime an option is added, while
 there are two hooks fired after the option is added. There is no hook
 available prior to the option being added to the database that fires for
 the specific `$option`.

 These same two issues are present for updating and deleting options.

 === Issue 2: Get Option ===
 When getting an option from the database, there are only two hooks fired:
 * `pre_option_{$option}`
 * `option_{$option}`

 The first is fired before the option is getted from the database and the
 second after. The problems are that:
 * Unlike adding, updating, and deleting, there is no verb in this hook to
 tell what is being done
 * There are no hooks that fire for every option getted from the database

 === Issue 3: Delete Transient ===
 Transients are sort of like options. Without an external object cache,
 WordPress stores them in the options table of the database. It would make
 sense that the hooks available for transients are consistent with those
 available for options. If we look at deleting a transient, there are two
 hooks available:
 * `delete_transient_{$transient}`
 * `deleted_transient`

 ( The same issues are present with site transients. )

 Remembering issue 1 above, there are presently three hooks available when
 deleting and option.
 * `delete_option`
 * `delete_option_{$option}`
 * `deleted_option`

 There are a couple issues:
 * There is no hook present that will fire every time a transient is
 deleted, either before or after
 * The `delete_transient_{$transient}` is fired BEFORE the transient is
 deleted in contrast with the `delete_option_{$option}` hook which is fired
 AFTER the option is deleted.

 === Issue 4: Pre ===
 Prior to getting and setting transients, the hooks all start with `pre_`.
 But this prefix is used inconsistently throughout.
 * It is not used prior to deleting the transient
 * It is used prior to getting an option, but not prior to adding, updating
 or deleting

 == Proposal ==

 === Structure of hooks ===
 I would like to propose that there be four hooks for each action: two
 before and two after, one general and one specific. The general structure
 would look like so:

 {{{
 "pre_{present-tense-verb}_{noun}"
 "pre_{present-tense-verb}_{noun}_{$variable}"
 [verb noun]
 "{past-tense-verb}_{noun}_{$variable}"
 "{past-tense-verb}_{noun}"
 }}}

 So for instance, adding an option would look like:
 {{{
 "pre_add_option"
 "pre_add_option_{$variable}"
 [add option]
 "added_option_{$variable}"
 "added_option"
 }}}

 === Type of hook ===
 Prior to adding, setting, or updating options/transients, the hooks should
 be a filter to allow changing of the option/transient prior to writing to
 the database. After adding, setting, or updating the hooks should be an
 action since the write has already occurred.

 Both prior and after getting an option/transient, the hook should be a
 filter. I'm not sure the use case for filtering the option before running
 the query, but that's what's presently done.

 Before and after the option is deleted the hook should be an action as
 there's no need to change the value of the option since it's being deleted
 anyway.

 === Deprecating hooks ===
 There are several hooks no present that don't fit the proposed structure
 above. I suggest these hooks continue to work for backward compatibility,
 but that they be deprecated.

 === See also ===
 [https://docs.google.com/document/d/1Zl7SuBJTWY8oWvWP6p4QuDmOCowuuqKHtmnmmlhasBI
 Google Doc] showing all the new and deprecated hooks

 == Related Tickets ==
 * #37928
 * #37929
 * #37930

--
Ticket URL: <https://core.trac.wordpress.org/ticket/39286>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform