[wp-trac] [WordPress Trac] #15691: Network admin should have its own settings API

[WordPress Trac]

#15691: Network admin should have its own settings API
-------------------------------------+-------------------------------------
 Reporter:  joostdevalk              |       Owner:
     Type:  feature request          |      Status:  new
 Priority:  normal                   |   Milestone:  Future Release
Component:  Plugins                  |     Version:
 Severity:  normal                   |  Resolution:
 Keywords:  has-patch settings-api   |     Focuses:  administration,
  dev-feedback                       |  multisite
-------------------------------------+-------------------------------------
Changes (by flixos90):

 * keywords:  has-patch settings-api => has-patch settings-api dev-feedback


Comment:

 As discussed on Slack, [attachment:15691.2.diff] is a new take on this
 ticket, based on @boonebgorges original patch. Some notes on the
 implementation:

 * Settings are processed in a new `process_settings()` function which
 contains the code that generally overlaps between regular site vs network
 options. The function has a `$context` parameter which is set to `site` by
 default, but accepts `network` as well. This implementation is flexible to
 support possible settings-related features in the future, for example
 global options (that go for all networks) or user options.
 * The `process_settings()` function is called from `wp-admin/options.php`
 and `wp-admin/network/settings.php` respectively. I left the code parts in
 there which I considered to be too specific to go into
 `process_settings()`, but maybe we could even merge more of that into the
 function.
 * Lines 150-188 of `wp-admin/options.php` and lines 47-65 of `wp-
 admin/network/settings.php` contain actions that are specific to their
 respective type of options (see above bullet point) - these should
 probably placed elsewhere, but I left them in there for now for a better
 overview.
 * In `wp-admin/network/settings.php`, there is a global
 `$whitelist_options` array now, similar to `wp-admin/options.php`. I gave
 the one existing default settings page the slug `general`, and by default
 this is the only settings page in that array. A filter
 `whitelist_network_options` allows for new custom network settings and is
 used by `register_setting()` when called in network mode.
 * I also adjusted the related Settings API functions with the new
 `$context` parameter (for example `register_setting()` and
 `settings_errors()`, providing an easy way to distinguish between the type
 of setting to manage. Settings errors are handled on a network-wide level
 when needed.
 * I also allowed `settings_fields()` to be network-compatible and adjusted
 the related code of the network settings page to output the nonce and
 action hidden fields, so that the network settings check for these
 variables instead of simply checking whether `$_POST` contains something,
 aligning it with the regular API.
 * What I didn't include in this implementation are functions like
 `add_settings_section()` and `do_settings_sections()` which I think should
 be enhanced in the same manner as well, but they are not crucial to this
 first approach, so we could do that later.

 The following code shows an example of how to use this implementation.

 {{{#!php
 <?php
 function nst_menu() {
         add_submenu_page( 'settings.php', __( 'Network Settings Test',
 'nst' ), __( 'Network Settings Test', 'nst' ), 'manage_network_options',
 'network-settings-test', 'nst_render_page' );
 }
 add_action( 'network_admin_menu', 'nst_menu' );

 function nst_register_setting() {
         register_setting( 'network_settings_test',
 'network_settings_test', 'nst_sanitize_settings', 'network' );
 }
 add_action( 'admin_init', 'nst_register_setting' ); // consider creating a
 new action 'network_admin_init' for things like that

 function nst_sanitize_settings( $options ) {
         if ( false !== strpos( $options['test_value2'], '@example.com' ) )
 {
                 add_settings_error( 'network_settings_test',
 'some_email_error', __( 'You must not provide emails @example.com.', 'nst'
 ), 'error' );
                 $options['test_value2'] = '';
         }
         return $options;
 }

 function nst_render_page() {
         $options = get_site_option( 'network_settings_test', array() );
         ?>
         <div class="wrap">
                 <h1><?php _e( 'Network Settings Test', 'nst' ); ?></h1>
                 <form method="post" action="settings.php"
 novalidate="novalidate">
                         <?php settings_fields( 'network_settings_test',
 'network' ); ?>
                         <table class="form-table">
                                 <tr>
                                         <th scope="row"><label
 for="test_value1">Name</label></th>
                                         <td><input type="text"
 id="test_value1" name="network_settings_test[test_value1]" value="<?php
 echo isset( $options['test_value1'] ) ? $options['test_value1'] : ''; ?>"
 /></td>
                                 </tr>
                                 <tr>
                                         <th scope="row"><label
 for="test_value2">Email</label></th>
                                         <td><input type="email"
 id="test_value2" name="network_settings_test[test_value2]" value="<?php
 echo isset( $options['test_value2'] ) ? $options['test_value2'] : ''; ?>"
 /></td>
                                 </tr>
                         </table>
                         <?php submit_button(); ?>
                 </form>
         </div>
         <?php
 }
 }}}

 I'm curious for feedback, if this is something we could build upon -
 making the regular Settings API network-compatible. And regarding this
 implementation, especially about possible issues with backwards
 compatibility. One point that I'm not sure about is whether in line 46 of
 `wp-admin/network/settings.php` we might need to continue support for just
 checking on `$_POST`.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/15691#comment:23>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform