스마트플렉스

functions.php에 임시 훅으로 디버

31.08.2025 DevKim

?debug=true 방식이 작동하지 않는 가장 유력한 원인은 훅(Hook)의 실행 시점 때문입니다. 이 문제를 해결하고, 왜 그런 현상이 발생하는지 근본적인 원인과 함께 더 나은 해결책을 제시해 드리겠습니다.

근본 원인: admin_init 훅은 너무 이르다

제가 이전에 제안했던 admin_init 훅은 관리자 페이지의 초기화가 시작되는 매우 이른 시점에 실행됩니다. 이 시점에는 다음과 같은 문제가 있습니다.

  • $menu와 $submenu 변수가 아직 완전히 채워지지 않았습니다.
    워드프레스 코어와 다른 플러그인, 그리고 우리 테마가 메뉴를 추가하는 작업(add_action('admin_menu', ...) )은 admin_init 훅이 실행된 이후에 일어납니다.

따라서 admin_init 시점에서 $menu 변수를 출력하면, 비어있거나 일부 기본 메뉴만 들어있는 불완전한 상태의 배열만 보이게 됩니다. 우리가 원하는 것은 모든 메뉴 추가 작업이 끝난 후의 최종 상태입니다.

해결책: admin_menu 훅과 높은 우선순위 사용하기

이 문제를 해결하는 가장 정확한 방법은, 우리가 메뉴를 수정/제거할 때 사용했던 것과 동일한 admin_menu 훅을 사용하되, 우선순위(priority)를 매우 높게 설정하는 것입니다. 이렇게 하면 다른 모든 테마와 플러그인이 메뉴를 추가하는 작업을 마친 직후, 최종적으로 완성된 $menu와 $submenu 배열의 내용을 확인할 수 있습니다.

수정된 코드 (더 정확한 방법)

테마의 functions.php 파일에 아래 코드를 대신 추가해 보세요.

// functions.php 에 임시로 추가할 디버깅 코드

add_action( 'admin_menu', function() {
    // 최고 관리자이고, URL에 ?debug=true 파라미터가 있을 때만 실행
    if ( current_user_can('manage_options') && isset($_GET['debug']) && $_GET['debug'] === 'true' ) {
        
        // 전역 변수를 함수 내로 가져옵니다.
        global $menu, $submenu;
        
        // 보기 좋게 스타일을 적용하여 출력합니다.
        echo '<pre style="background-color: #fff; color: #000; padding: 20px; border: 1px solid #ccc; margin: 20px; position: relative; z-index: 9999;">';
        
        echo '<h1>$menu (최상위 메뉴 최종 상태)</h1>';
        print_r($menu);
        
        echo '<hr>';
        
        echo '<h1>$submenu (서브 메뉴 최종 상태)</h1>';
        print_r($submenu);
        
        echo '</pre>';
        
        // 다른 내용이 출력되지 않도록 여기서 실행을 중단합니다.
        die(); 
    }
}, 9999 ); // [핵심] 우선순위를 매우 높게 설정하여 가장 마지막에 실행되도록 합니다.

만약 위 코드로도 작동하지 않을 경우: 체크리스트

위 코드로 변경했음에도 여전히 작동하지 않는다면, 아래의 사항들을 순서대로 점검해 보시기 바랍니다.

1. URL을 정확하게 입력했는지 확인
관리자 페이지의 아무 곳이나 접속한 뒤, 주소창의 URL 끝에 ?debug=true 또는 &debug=true를 붙여야 합니다.

  • 올바른 예시:
    • https://your-domain.com/wp-admin/index.php?debug=true
    • https://your-domain.com/wp-admin/edit.php?post_type=page&debug=true (기존 파라미터가 있을 경우 & 사용)
  • 잘못된 예시:
    • https://your-domain.com/wp-login.php?debug=true (로그인 페이지는 관리자 페이지가 아닙니다)
    • https://your-domain.com/wp-admin/ (파일 이름 없이 디렉터리로만 끝나면 작동하지 않을 수 있습니다)

2. 코드 위치 확인
코드가 반드시 활성화된 테마의 functions.php 파일 안에 있는지 다시 한번 확인해 주세요.

3. 캐시 문제
만약의 경우를 대비해, 브라우저 캐시를 비우는 강력 새로고침 (Ctrl+Shift+R 또는 Cmd+Shift+R)을 실행해 보세요.

더 나은 디버깅 방법: admin_notices 활용하기

die() 함수는 페이지 전체를 중단시키기 때문에 때로는 불편할 수 있습니다. 관리자 페이지의 레이아웃을 유지하면서 상단에 알림 형태로 변수 내용을 출력하는 더 세련된 방법도 있습니다.

// functions.php 에 추가할 수 있는 또 다른 디버깅 방법

add_action( 'admin_notices', function() {
    if ( current_user_can('manage_options') && isset($_GET['debug']) && $_GET['debug'] === 'true' ) {
        global $menu;
        
        echo '<div class="notice notice-info is-dismissible"><p><strong>디버깅 정보:</strong></p><pre>';
        print_r($menu);
        echo '</pre></div>';
    }
});

이 코드는 ?debug=true로 접속했을 때, 관리자 페이지 상단에 노란색 알림 박스를 만들고 그 안에 $menu 변수의 내용을 출력해 줍니다. die()를 사용하지 않아 다른 관리 기능도 함께 확인할 수 있어 편리합니다.

결론:

?debug=true 방식이 작동하지 않은 이유는 admin_init 훅의 실행 시점이 너무 빨라 $menu 변수가 채워지기 전이었기 때문일 가능성이 매우 높습니다. admin_menu 훅을 사용하고 우선순위를 9999와 같이 매우 높게 설정하는 것이 이 문제를 해결하는 가장 정확한 방법입니다.

파일 저장 후, 관리자 페이지 URL 뒤에 ?debug=true를 붙여 다시 확인해주세요.