워드프레스 아스트라 테마 검색 위젯 에러

티스토리에서 오라클 클라우드의 평생 무료 가상머신에 설치한 워드프레스로 이사한지 1년이 다 되어간다. 모든 관리를 스스로 해야만 하다 보니 스팸댓글의 차단부터 검색엔진 외 봇의 접근을 차단은 물론 백업까지 신경 쓸 일이 한 두 가지가 아니다. 그 와중에 블로그 메인 화면에 설치한 검색 위젯이 오작동 한다는 사실을 한참 뒤에야 알게 되었다.

아스트라 테마의 검색 위젯 에러

검색 위젯은 블로그 내 글을 검색하고 그 결과를 출력하는 역할을 한다. 다음 화면에서 오른쪽 사이드바의 맨 위에 있는 검색창이 바로 검색위젯이다. (붉은색 박스)

이 검색 위젯에 키워드를 입력하고 검색 버튼을 누르면 해당 키워드가 제목이나 본문에 포함된 글의 목록이 출력되어야 하지만 다음과 같이 에러가 발생한다. 이 에러는 고질적인 듯 몇 번의 아스트라 테마 업데이트에도 불구하고 고쳐지지를 않는다. 다음과 같이 “이 웹사이트에 치명적인 오류가 있습니다.” 라는 에러메시지만 출력된다.

이 오류를 발견한지 몇 달이 지났지만 이런 저런 핑계로 디버깅을 미루고 있었다. 그리고 어제 드디어 작심을 하고 디버깅을 했다.

워드프레스 디버그 모드 설정

물론 이런 에러는 단순한 HTML이나 CSS 수정으로 해결이 되지는 않을 가능성이 높다. 워드프레스가 코딩된 PHP 언어를 조금은 이해하고 있어야 디버깅이 가능하다. 하지만 도전은 항상 옳다. 꼭 PHP가 아니더라도 Java나 C, Python 언어의 기본적인 내용만 알고 있어도 웬만한 디버깅은 가능할 수도 있다.

먼저 워드프레스의 디버그 모드를 설정해줘야 한다. 어떤 언어든 에러가 발생하면 비교적 상세한 에러메시지를 출력해준다. 하지만 너무 상세한 에러메시지의 출력은 취약점의 노출로 이어져 해킹 공격의 빌미가 될 수 있기 때문에 기본적으로는 상세한 에러 출력은 하지 않도록 설정되어 있다. 하지만 위와 같은 오류는 상세한 에러 출력이 필요하다. 따라서 워드프레스의 설정을 변경하여 에러가 발생할 경우 상세한 에러 메시지를 출력하도록 DEBUG 모드를 활성화시켜야 한다.

먼저 워드프레스가 설치된 디렉토리에서 wp-config.php 파일을 열어 다음과 같이 WP_DEBUG 상수 선언문을 찾아 간다.

defind (‘WP_DEBUG’, false ); 문장을 찾아 다음과 같이 수정한다.

사실 WP_DEBUG 상수만 true로 변경해도 된다. 이렇게 변경하면 브라우저 화면에 에러메시지가 출력된다. 만약 WP_DEBUG_LOG 상수까지 true로 변경하면 wp-content 디렉토리에 debug.log 파일에 에러메시지를 저장해준다.

아스트라테마 검색 위젯 에러 메시지

디버그 모드를 설정한 다음 확실하게 하기 위해 다음의 명령어로 Apache 웹서버 또는 EnginX 웹서버를 재구동 한다.

$ sudo systemctl restart apache2

그런 다음 워드프레스 블로그의 첫 화면에서 검색 위젯에 키워드를 넣고 검색해본다. 정상적으로 Debug 모드가 동작한다면 에러 메시지가 화면에 표시될 것이다.

이 에러메시지에 검색 위젯이 오작동하는 중요한 단서가 되는 메시지가 출력되어 있었다.

[Thu Aug 15 21:36:31.866349 2024] [proxy_fcgi:error] [pid 19949:tid 135597863716416] [client 125.180.122.223:63435] AH01071: Got error 'PHP message: PHP Fatal error: Uncaught ArgumentCountError: 3 arguments are required, 2 given in /var/www/html/wp-content/themes/astra/inc/core/common-functions.php:966\nStack trace:\n#0 /var/www/html/wp-content/themes/astra/inc/core/common-functions.php(966): sprintf()\n#1 /var/www/html/wp-content/themes/astra/inc/core/common-functions.php(1043): astra_get_taxonomy_banner_legacy_layout()\n#2 /var/www/html/wp-includes/class-wp-hook.php(324): astra_archive_page_info()\n#3 /var/www/html/wp-includes/class-wp-hook.php(348): WP_Hook->apply_filters()\n#4 /var/www/html/wp-includes/plugin.php(517): WP_Hook->do_action()\n#5 /var/www/html/wp-content/themes/astra/inc/core/theme-hooks.php(429): do_action()\n#6 /var/www/html/wp-content/themes/astra/search.php(27): astra_archive_header()\n#7 /var/www/html/wp-includes/template-loader.php(106): include('…')\n#8 /var/www/html/wp-blog-header.php(19): require_once('…')\n#9 /var/www/html/index.php(17): require('…')\n#10 {main}\n thrown in /var/www/html/wp-content/themes/as…', referer: https://blogger.pe.kr/

먼저 이 에러는 ArgmentCountError 다. 즉 함수의 실행을 위해 전달되는 아규먼트가 3개가 필요한데 2개만 전달되어 발생하는 에러다. 그리고 에러가 발생한 코드는 common-functions.php 파일의 966 번째 라인이며 그 라인에 위치하는 sprintf() 함수에서 발생하는 에러다.

즉 sprintf() 함수로 출력해야 하는 3개의 아규먼트가 있는데 2개만 전달되어 발생하는 에러라는 의미다.

에러가 발생한 common-function.php의 966 번째 라인 분석과 코드 수정

먼저 comon-function.php 파일을 찾아보니 여러개가 나온다. 그 중에서 현재 적용되어 있는 astra 테마에 위치한 common-function.php 파일을 열어 코드를 확인했다. 966번째 라인이다.

이 코드에서 주석문 /* ~ */ 를 제거하고 보면 다음과 같다.

$title = apply_filters( 'astra_the_search_page_title', sprintf( astra_get_option( 'section-search-page-title-custom-title' ) . ' %s', '' . get_search_query() . '' ) );

에러가 발생한 것으로 확인 된 코드에서 sprint() 함수는 astra_get_option() 함수의 결과로 전달되는 문자열과 그 다음의 %s 그리고 %s에 전달될 값인 get_search_query() 로 구성되어 코드만 봤을 때는 문제가 없다.

그런데 에러 메시지에서는 sprintf() 함수에서 3개의 아규먼트가 필요한데 2개만 전달된다고 했다. 그 이야기는 첫 번째 아규먼트에 %s가 2개 있다는 이야기다. 그리고 뒤에 두 개의 아규먼트에 두 개의 %s에 대치될 아규먼트 2개가 있어야 한다. 그래야 아규먼트가 3개가 된다. 그런데 코드에 맨 앞 아규먼트에 %s는 1개 뿐이다.

그에 기반해 생각하면 sprintf()의 첫 번째 아규먼트 위치에 있는 함수 즉 astra_get_option()의 결과 값에 %s가 하나 더 포함되어 있다는 이야기다. 그렇다면 촉이 온다. 코드에 있는 %s를 지워서 sprintf() 함수에 전달되는 아규먼트를 2개로 맞춰주면 어떨까?

그래서 이 코드를 다음과 같이 %s 를 삭제하여 수정했다.

$title = apply_filters( 'astra_the_search_page_title', sprintf( /* translators: 1: search string */ astra_get_option( 'section-search-page-title-custom-title' ) , '' . get_search_query() . '' ) );

그냥 %s 부분만 삭제했다. 그리고 소스코드를 저장했다.

코드 수정 결과

수정한 코드를 저장하고 다시 검색 위젯에서 검색해봤다. 검색 위젯에 “ssl 인증서”를 입력하고 검색을 했다.

운이 좋게도 수정한 내용이 잘 반영되어 문제 없이 블로그 내 컨텐츠의 검색이 되고 에러가 발생하지 않는다. 결국 검색 결과를 출력하는 sprintf() 함수에 불필요한 %s가 하나 더 작성되어 발생한 에러였다.

다행히 쉽게 원인을 찾아 간단하게 수정할 수 있었다.

고쳐지지 않는 버그였다.

워드프레스는 꽤 유명한 공개용 CMS다. 그렇다 보니 가끔은 고쳐지지 않는 고질적인 버그가 존재하기도 한다. 이 검색 위젯 검색결과 표시 오류가 그랬다. 워드프레스를 버전업 하면… 이 버그는 다시 나타난다. 그 때마다 수정을 해줘야 한다.

이 버그를 수정하도록 제보를 할 지 고민중이다.