[wp-trac] [WordPress Trac] #38098: Use common naming for context switching functions / classes

[WordPress Trac]

#38098: Use common naming for context switching functions / classes
--------------------------+-----------------------------
 Reporter:  swissspidy    |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:
 Severity:  normal        |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 I'm creating this ticket after discussions in #26511 and #25293. A quick
 overview:

 As we all know, there are `switch_to_blog()` and `restore_current_blog()`
 to switch between different sites by adding the sites to the global
 `$_wp_switched_stack` and doing a bunch of other stuff.

 Now, #26511 aims to introduce `switch_to_locale()` to do the same for the
 site's locale. To avoid using (too many) global variables, a
 `WP_Locale_Switcher` class was suggested. The locale names are stored in a
 stack as well

 #25293 is about improving `switch_to_blog()` and introducing
 `switch_to_site()` as well as `switch_to_network()`. #37958 suggests using
 `Network_Sate` objects for the stack instead of simply the blog IDs.

 #19572 is somewhat related as well, though I don't think a
 `switch_to_post()` function makes sense. Fun fact: `WP_Query` was once
 named `WP_Query_State`, see [1449].

 ----

 Now, I want to suggest using some kind of naming convention for new
 `WP_Locale_State` and `WP_Site_State` / `WP_Network_State` classes to make
 things easier for developers. Those essentially do the same thing:

 * Switch to a new state
 * Add this state to a stack
 * Pop an item off the stack
 * Pop all items off the stack (#37958)

 Solid naming is very important to avoid confusion. As mentioned, there are
 `switch_to_blog()` and `restore_current_blog()`. #26511 suggests adding
 `switch_to_locale()` & `restore_previous_locale()`. #19572 suggests
 `switch_to_post()` and `restore_post()`. Ugh.

 The simplest solution for that is to introduce an interface that these new
 classes would need to implement. Basically something along the lines of
 this:

 {{{#!php
 <?php

 interface WP_State {
         /**
          * Switch to new context.
          */
         public function switch_to();

         /**
          * Restore previous context.
          */
         public function restore();

         /**
          * Restore the original context.
          */
         public function clear();

         /**
          * Is context switched?
          */
         public function is_switched();
 }
 }}}

 After that, the functions would need to be called similarly
 `switch_to_*()` and `restore_previous_*()`. IMHO `restore_previous_*()`
 makes more sense than`restore_current_*()`, but well…

 I know that adding an interface or maybe an abstract class for these seems
 like over-engineering, but it's a good way to communicate the idea.

 The least thing we should do is use common naming when introducing such
 new classes. An interface could always follow later.

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