[워드프레스] 24. 관리자 : Settings API로 설정 페이지 만드는 법

(워드프레스 해부 ㉔) 관리자

플러그인을 만들면 “설정 페이지”가 필요하다. 워드프레스는 이걸 위한 Settings API를 제공한다. 직접 폼을 만들고 저장 처리를 짜는 대신, 정해진 함수로 등록하면 저장·검증·보안(nonce)을 워드프레스가 알아서 해준다.

세 가지를 등록한다. register_setting()(저장할 옵션), add_settings_section()(섹션), add_settings_field()(입력 필드). 그리고 add_menu_page()로 메뉴에 페이지를 건다. 저장된 값은 wp_options 테이블에 들어간다.

직접 해보기

add_action( 'admin_init', function() {
    register_setting( 'my_group', 'my_site_motto' );
    add_settings_section( 'my_sec', '내 설정', '__return_null', 'my_page' );
    add_settings_field( 'my_motto', '사이트 모토', function() {
        $v = esc_attr( get_option( 'my_site_motto', '' ) );
        echo "<input name='my_site_motto' value='$v'>";
    }, 'my_page', 'my_sec' );
} );
add_action( 'admin_menu', function() {
    add_menu_page( '내 설정', '내 설정', 'manage_options', 'my_page', function() {
        echo '<form action="options.php" method="post">';
        settings_fields( 'my_group' );        // nonce 포함
        do_settings_sections( 'my_page' );
        submit_button();
        echo '</form>';
    } );
} );

✅ 확인 — 관리자 메뉴에 “내 설정”이 생기고, 값을 저장한 뒤 wp option get my_site_motto로 저장된 값이 나오면 성공. settings_fields()가 nonce를 자동으로 넣어줘서 19편의 보안이 기본 적용된다.

설정 페이지 한 벌

세 등록 함수를 admin_init에서 부르고, 메뉴는 admin_menu에서 add_options_page로 단다. 뼈대는 이렇다.

// 1) 메뉴에 설정 페이지 추가
add_action( 'admin_menu', function () {
    add_options_page( 'Cozlab 설정', 'Cozlab', 'manage_options',
        'cozlab', 'cozlab_render_page' );
} );

// 2) 옵션·섹션·필드 등록
add_action( 'admin_init', function () {
    register_setting( 'cozlab_group', 'cozlab_api_key',
        array( 'sanitize_callback' => 'sanitize_text_field' ) );
    add_settings_section( 'main', '기본', '__return_false', 'cozlab' );
    add_settings_field( 'api', 'API 키', 'cozlab_field_api', 'cozlab', 'main' );
} );

폼을 그리는 건 정해진 함수들

설정 페이지 화면은 직접 <form>을 짜지 않는다. settings_fields()와 do_settings_sections()를 부르면 워드프레스가 nonce·필드·섹션을 알아서 렌더하고 저장까지 처리한다. 개별 입력칸을 그리는 필드 콜백만 내가 짠다.

function cozlab_render_page() { ?>
  <div class="wrap"><h1>Cozlab 설정</h1>
    <form method="post" action="options.php">
      <?php settings_fields( 'cozlab_group' );
            do_settings_sections( 'cozlab' );
            submit_button(); ?>
    </form>
  </div>
<?php }

function cozlab_field_api() {
    $v = esc_attr( get_option( 'cozlab_api_key', '' ) );
    echo '<input name="cozlab_api_key" value="' . $v . '" class="regular-text">';
}

입력 검증은 sanitize_callback으로

register_setting의 sanitize_callback이 저장 직전에 값을 정제한다. 이걸 지정하지 않으면 사용자 입력이 그대로 DB에 들어가니, 문자열엔 sanitize_text_field, 숫자엔 absint처럼 타입에 맞는 걸 꼭 걸어둔다. 19편의 sanitize가 여기서도 그대로다.

검증 실패를 사용자에게 알리기 — add_settings_error

sanitize_callback에서 조용히 값을 고치기만 하면, 사용자는 ‘저장했는데 왜 내 값이 아니지?’가 된다. 왜 거부됐는지를 화면에 띄우는 짝이 add_settings_error다.

function cozlab_sanitize_api_key( $value ) {
    $value = sanitize_text_field( $value );
    if ( ! preg_match( '/^ck_[a-z0-9]{32}$/', $value ) ) {
        add_settings_error( 'cozlab_api_key', 'bad_format',
            'API 키 형식이 아닙니다 (ck_로 시작하는 32자).' );
        return get_option( 'cozlab_api_key' );   // 기존 값 유지
    }
    return $value;
}

실패 시 기존 값을 반환하는 게 요령이다 — 빈 값을 돌려주면 멀쩡하던 설정이 지워진다. 설정 페이지 상단에 settings_errors()를 불러두면 이 메시지가 표준 알림 상자로 뜬다.

텍스트만 있는 게 아니다 — 체크박스 필드

필드 콜백은 입력 타입마다 모양이 다르다. 제일 자주 틀리는 체크박스만 하나 보자 — 포인트는 checked() 헬퍼와, 꺼졌을 때 값이 아예 전송되지 않는다는 것.

add_settings_field( 'dark_mode', '다크 모드', function () {
    $v = get_option( 'cozlab_dark_mode', 0 );
    echo '<input type="checkbox" name="cozlab_dark_mode" value="1" '
        . checked( 1, $v, false ) . '>';
}, 'cozlab', 'cozlab_main' );
// sanitize: 체크 해제 시 POST에 키 자체가 없다 → isset으로 0 처리
register_setting( 'cozlab', 'cozlab_dark_mode',
    array( 'sanitize_callback' => fn($v) => empty($v) ? 0 : 1 ) );

저장한 값은 어디서든 get_option으로

설정은 결국 wp_options 테이블에 저장된다(10편). 그래서 플러그인 어디서든 get_option('cozlab_api_key')로 읽어 쓴다. 관리자에서 값을 바꾸면 그다음부터 이 값이 반영된다.

그냥 update_option과 뭐가 다른가

값 하나 저장하는 정도면 update_option·get_option을 직접 써도 된다. Settings API의 값어치는 설정 ‘페이지’가 필요할 때 나온다 — 폼·nonce·검증·저장을 표준 방식으로 처리해줘서, 보안 실수 없이 일관된 관리 화면을 만들 수 있다. 설정 항목이 여러 개로 늘어날수록 이 표준의 이득이 커진다.

관리 화면을 만들었으니, 다음은 외부와 통신하는 REST API 커스텀 엔드포인트다.

자주 묻는 질문 (FAQ)

Settings API는 왜 쓰나요?

설정 페이지를 표준 방식으로 만들어 저장·검증·보안(nonce)을 워드프레스가 처리하게 하려고요.

옵션은 어디에 저장되나요?

register_setting으로 등록하면 대개 wp_options 테이블에 저장됩니다.