WordPress 4.7のregister_setting()はREST APIへ出す設定と管理画面の設定を分ける

WordPress 4.7でregister_setting()を使うなら、管理画面で変更できる設定とREST APIへ出す設定を同じものとして扱いません。show_in_restを指定したsettingだけがREST APIへ含まれます。外部のappやJavaScriptから読む必要がある値だけを選び、管理者だけが判断する設定、接続に関わる設定、公開して意味がない設定はREST APIへ出さない方が安全です。

settingは、site全体に関わる値を保存する仕組みです。営業時間の表示方法、トップpageの案内文、問い合わせの受付状態のように、管理画面で変更してthemeやpluginが読む値を登録できます。WordPress 4.7では、三番目の引数にargumentsの配列を渡し、値のtype、説明、入力を整えるcallback、default値、REST APIで扱うかどうかを登録できます。設定を登録することと、外部から読み取れるdataにすることは別です。

設定を作る目的と外部へ出す理由を別にする

show_in_restは、REST APIへsettingを含めるかを決める項目です。指定しないsettingは、登録していてもREST APIへは出ません。ここで先に決めるのは、技術的に取得できるかではなく、どの画面やappがその値を必要とするかです。

たとえば、siteのheaderに表示する短い告知を、管理画面のsettingで変更できるようにしたとします。別に作ったJavaScriptの画面も同じ告知を表示するなら、そのsettingをREST APIから読む理由があります。一方、告知を管理する担当者の内部メモ、更新する手順、外部サービスへ接続するための値は、告知を表示する画面には必要ありません。同じsetting画面で変更できても、利用する人と利用する場所が違います。

説明用の仮例として、休業日の案内を管理画面で変更し、siteのheaderと予約用の画面で読む場合を考えます。headerだけが読むなら、themeがget_option()で取得すれば足ります。予約用の別画面も同じ案内を読むなら、REST APIで共有する設計を検討します。このとき、休業案内の本文だけを出すのか、表示開始日と終了日も出すのか、下書き中の案内を含めないのかを分けます。値を一つ返せるようにすることと、表示の判断を正しく共有することは別です。

外部の制作会社へ依頼するときも、「設定をAPI対応にする」だけでは足りません。どのsetting名を使うか、誰が変更するか、どの画面が読むか、公開してよい値は何か、変更後にどのURLで確かめるかを渡します。実装する側はREST APIへ値を出せますが、その値を公開してよいか、どの案内を正式なものにするかまでは決められません。作る責任と、内容を承認する責任を分けます。

typeとdefaultを値の説明として使う

WordPress 4.7のregister_setting()では、typeにnumber、string、booleanを指定できます。REST APIで扱うsettingでは、文字列なのか、数値なのか、真偽値なのかをWordPressへ伝える必要があります。見た目が似ている値でも、意味が違えばtypeを混ぜません。

「受付中」という表示を考えると、画面に出す文章はstringです。受付を開くか閉じるかの切り替えはbooleanです。受付終了までの日数を計算するならnumberです。この三つを一つの自由入力欄へ詰め込むと、themeや外部appはどこまでを表示し、どこで判断するかを毎回解釈しなければなりません。文章、状態、数値を分ければ、管理画面の入力も、REST APIで受け取る側の処理も読みやすくなります。

defaultを登録すれば、get_option()で個別のdefault値を何度も書かなくて済みます。ただし、defaultを決めても公開する案内そのものは決まりません。仮に「受付中」をdefaultにしても、実際に対応できる担当者がいなければ、表示だけが先に進みます。settingの初期値は画面の不具合を減らすためのものであり、運用の判断を代わりにするものではありません。

入力を整えるcallbackも同じです。文字数や値の形式を確認するcallbackは、入力の誤りを防げます。しかし、文面が現在の案内として正しいか、休業日が関係者と共有されているかまでは判定しません。値の形を確認する仕事と、内容を決める仕事を混ぜないことが必要です。

許可する値を狭くして表示側の判断を減らす

show_in_restには真偽値だけでなく、REST API向けのoptionsを配列で渡せます。公開するsettingの値がprivateかpublicのどちらかであるように、許可する値をschemaで示すこともできます。外部画面がsettingを読むなら、返ってくる値の範囲を狭くしておく方が、表示側の条件分岐を増やさずに済みます。

ここで大切なのは、選択肢を少なくすることではありません。実際に必要な状態を、似た言葉で重複させないことです。たとえば「受付中」「営業中」「対応可能」が同じ意味で使われると、外部画面は三つの文字列を同じ状態として扱う必要があります。運用する人も、どれを選ぶべきか迷います。状態を分けるなら、各状態で何を表示し、誰が対応し、次に何をするのかを決めます。

説明用の仮例として、公開範囲をpublicとprivateの二つで管理するsettingを考えます。publicを選んだときだけ外部画面へ案内を出し、privateなら管理画面だけで確認する設計です。この場合、REST APIへ出す値は二択で足ります。ところが「確認中」「仮公開」「担当者待ち」のような内部の作業状態まで同じ値へ含めると、公開範囲と作業状態が混ざります。公開するかどうかと、作業がどこまで進んだかは別のsettingか、別の管理方法で扱います。

変更した設定は管理画面とAPIの両方で確かめる

settingを追加したら、保存できたことだけで終えません。管理画面で値を変更し、保存後にthemeの表示を確認します。REST APIへ出すsettingなら、認証の有無による表示範囲と、外部画面の表示も確認します。公開する値を替えたとき、すべての画面が同じ内容になるかを見ます。

確認する順序は、次のように決められます。

1. settingの目的、type、default値、REST APIへ出す理由を一行ずつ書く。
2. 管理画面で値を保存し、意図した値がthemeへ反映されるかを見る。
3. REST APIへ出すsettingだけを取得し、返る値と許可した範囲を確認する。
4. その値を読む外部画面を開き、表示文と表示条件を確認する。
5. 元の値へ戻す手順と、変更した人、確認した画面を残す。

公開siteで初めて試すと、値の型が違ったのか、外部画面の条件が違ったのか、案内文の承認が済んでいなかったのかを分けにくくなります。できればstaging環境で、空の初期状態、通常の値、許可しない値を試します。全てのsettingをREST APIへ出す必要はありません。必要な値だけを、説明できるtypeと範囲で出すことが、あとから直す仕事を減らします。

最初の一手は、現在のsettingを一覧にし、外部画面が読む値へ印を付けることです。その印が付かないsettingはREST APIへ出しません。印が付くsettingは、type、default、許可する値、変更する人、確認する画面を決めてから登録します。