Deprecate *_blog_option()

[ryan]

Deprecate get_blog_option(), add_blog_option(), update_blog_option(), and delete_blog_option(). The regular *_option() functions wrapped with switch_to_blog() and restore_current_blog() should be used instead.

Previous discussion:

http://core.trac.wordpress.org/ticket/21270#comment:11

Incomplete and untested

In [21414]:

Deprecate get_blog_option(), add_blog_option(), update_blog_option(), and delete_blog_option().

Use the regular option functions wrapped in switch_to_blog() and restore_current_blog() instead.

Group multiple operations within a single switch where possible.

fixes #21432

Might be an idea to pass the phrase "the regular option functions wrapped in switch_to_blog() and restore_current_blog()" to the $replacement parameter of _deprecated_function().

While this change makes sense to me, I don't see any need to stop using *_blog_option and/or deprecating them.

As they stand, these functions perform a very specific task, Grab another site's option without extra code required by the calling functions.

Although it may be more efficient to use switch_to_blog() when multiple options are being requested, it doesn't seem like enough of a reason to deprecate the functions, especially when it seemingly doesn't provide anything extra to the calling function, let alone changing the semantics of the actual operation ("Get blog xyz's option blah" vs "Switch to the other blog, grab the option, then come home again") - that's low-level stuff that the calling function shouldn't care about:

foreach ( $blogs as $blog_id )
   $sites[ $blog_id ] = get_blog_option( $blog_id, 'some_option' );

vs

foreach ( $blogs as $blog_id ) {
   switch_to_blog( $blog_id );
   $sites[ $blog_id ] = get_option( 'some_option' );
   restore_current_blog();
}

In [21480]:

Undeprecate *_blog_option() by popular demand. Put them back in ms-blogs.php since direct inclusion of ms-blogs.php/ms-functions.php is unforntunately common.

see #21432

PHP Fatal error:  Call to undefined function get_current_blog_id() in /.../wp-includes/ms-blogs.php on line 340

Looks like the blog option functions are being called before general-template.php is loaded. Alternatives are to go back to using the blog_id global or perhaps moving get_current_blog_id() to load.php.

In [21484]:

Move get_current_blog_id() to load.php so it is available during multisite bootstrap. fixes #21432

ryan and I would still lean toward deprecating _blog_option(). We'd just have to leave them in ms-blogs.php, which is fine with me.

Deprecating them emphasizes that they are not more performant than switch_to_blog() (which they were, hypothetically, under earlier versions, albeit with caching issues), and that switch_to_blog() should be used if you have more than one operation.

I'm willing to suggest a deprecation of current_user_can_for_blog() as well, for the same reasons.

I, for one, agree with the deprecation; having two ways of doing essentially the same thing is confusing.

We still need to figure out whether options filters should be skipped (or alternative ones should run) when we are switched. I guess we'll find out soon what kind of breakage we might be looking at.

We should also re-deprecate _blog_option(). See also #21459 where I mention current_user_can_for_blog() should go too.