Register some custom settings in WordPress

#wordpress #wpgraphql

Lately I played a lot with WPGraphQL a plugin that enables a GraphQL API for WordPress.
And I needed to retrieve links to social networks in my app.

Historically I would have done that with the Customizer API, but WPGraphQL doesn't expose for the moment this data.

So, thanks to the WPGraphQL doc, an another idea came to me: used the Settings API. WPGraphQL exposes all core settings in the WPGraphQL Schema.

So I thought that documented could be useful to anyone, even outside WPGraphQL ecosystem.

Settings API

Three functions are essential to accomplish what you want:

add_settings_section, used to define new settings sections for an admin page ;
add_settings_field, used to define a settings field ;
register_setting, to register settings and data.

Settings class

We are going to write a PHP class named Settings:

class Settings {
    /**
     * The theme name
     */
    protected $theme_name;

    /**
     * The theme version
     */
    protected $theme_version;

    /**
     * The constructor
     */
    public function __construct( $theme_name, $theme_version ) {
        $this->theme_name    = $theme_name;
        $this->theme_version = $theme_version;
    }
}

This class will be instantiated in the functions.php of our theme (or plugin).

Settings API init method

So we are going to write a method for our Settings class to add settings:

public function settings_api_init() {
    add_settings_section(
        'socials',
        'Socials',
        // In class context pass an array with $this and the method name
        // to retrieve callback function.
        array( $this, 'socials_callback_function' ),
        // Our Socials setting will be set under the General tab.
        'general'
    );

    add_settings_field(
        'twitter',
        'Twitter',
        array( $this, 'setting_callback_function' ),
        'general',
        // Display this setting under our newly declared section right
        // above.
        'socials',
        // Extra arguments used in callback function.
        array(
            'name'  => 'twitter',
            'label' => 'Twitter',
        )
    );
}

Callback method

add_settings_section and add_settings_field take a callback function, socials_callback_function and setting_callback_function respectively, add them to our class:

public function socials_callback_function() {
    echo '<p>Socials urls</p>';
}

public function setting_callback_function( $args ) {
    // Ugly, I know 😔.
    echo '<input name="' . esc_attr( $args['name'] ) . '" type="text" value="' . esc_attr( get_option( $args['name'] ) ) . '" class="regular-text code" placeholder="' . esc_attr( $args['label'] ) . ' URL" />'; 
    echo ' ' . esc_attr( $args['label'] ) . ' URL';
}

Register settings method

Next, we are going to register this settings, so WordPress can handle this:

public function register_settings() {
    $args = array(
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_text_field',
        'default'           => null,
        // Extra argument for WPGraphQL.
        'show_in_graphql'   => true,
        'show_in_rest'      => true,
     );

     register_setting( 'general', 'twitter', $args );
}

Constructor

Finally in our constructor, we can attach this methods to the class in appropriate hook:


public function __construct( $theme_name, $theme_version ) {
    $this->theme_name    = $theme_name;
    $this->theme_version = $theme_version;

    add_action( 'admin_init', array( $this, 'settings_api_init' ) );
    // We hook into init and not admin_init to make front aware of this
    // settings.
    add_action( 'init', array( $this, 'register_settings' ) );
}