WordPress Settings API demystified

UPDATE
I’ve made a wrapper which simplifies working with Settings API where you don’t have to deal with parameters that aren’t used outside of Settings API and are used just to connect sections and fields. You can find it among my gists on github here. Check included example and see how easy it is to work with it!

WordPress Settings API is so hard to figure it out because documentation is sadly not making it very clear for me. Now imagine you need to re-learn it every time when you are tackling it because you don’t work with it very often but say twice a year. So I decided to finally post here how things fit together in this Settings API for my future-self, which where the hardest to figure out.

I found this blogpost from Tom McFarlin really helpful, especially the last gist that shows how to create settings page with multiple sections. It can also be seen how parameters are connected between various functions.

For example 4th parameter to add_options_page(), add_settings_section() and add_settings_field() refer to the same ID, that’s option’s page ID. Also this value is used when rendering options in a form in do_settings_sections().

Parameter to register_setting() is the same as the 1st one in settings_fields(). As seen below, settings from different sections are registered to the parameter with same name.

Technically, parameters to do_settings_sections() and settings_fields() can have the same name since as noted they point to different things or are in different “namespace” but why aid to more confusion?