[작성자:] changwoo

커스텀 포스트 레이블은 꽤 많은 경우 사소한 문제로 넘어가게 된다. 보통 커스텀 포스트를 워드프레스 기본 포스트 타입인 ‘포스트’와 유사하게 별도의 작성자가 꾸준히 어떤 콘텐츠를 작성(주로 수동으로)해 발행하기 위한 용도로는 잘 사용해 본 적이 없기 때문이다.

그러다 보니 레이블에 대한 인식은 많이 낮았다. 또 레이블에 별로 신경 쓰지 않아도 코어가 ‘post’나 ‘page’ 타입에 의거해 기본적인 레이블을 만들어 주니 신경 쓸 것이 거의 없었기도 했고.

register_post_type 레퍼런스를 보면 꽤나 많은 입력 인자가 있는데, 이 중에서도 상당수를 차지하는 것이 레이블이다. 사소하기는 하나 이 레이블들이 어디에서 어떻게 쓰이고 있는지 꼭 한번은 체크해 보고 싶었다. 물론 이것은 로직과는 별개로 그저 ‘텍스트’의 취향일 뿐이라고 할 수도 있다. 그리고 대략의 문서를 보면 어떤 텍스트를 넣어야 하는 건지도 바로 이해할 수도 있다.

그러나, 궁금했다. 이렇게 열심히 세부 옵션을 넣어 텍스트를 지정해 주면 도대체 UI 어디에서 이 레이블을 활용하고 있는 건지, 이 레이블이 실제로 어디서 어떻게 쓰이는지 조목조목 따져 보고 싶었다. 그렇게 알게 되면 각 레이블에 대한 이해도도 높아지지 않을까?

원래 커스텀 포스트에 대해 포스팅을 하면서 한꺼번에 처리하려고 했지만, 의외로 레이블의 세부 옵션이 많아서 이것만 따로 포스팅하는 것이 낫겠다 싶어 별도로 작성한다.

자, 그럼 지루하기는 하지만 커스텀 포스트의 레이블이 어떤 식으로 사용되나 보도록 하자.

레이블과 관련된 옵션

여기서 레이블(label)이란 것은 UI 상에 표시되는 텍스트를 말한다. 다들 알다시피 워드프레스는 다국어 설정이 가능하다. 그러므로 각 언어 설정에 따라 표시되는 텍스트는 달라질 수 있다. 그래서 어떤 UI 상에 어떤 텍스트를 표시하려면 두 가지 조건이 필요하다. 바로 언어 도메인과 문맥이다. 언어 도메인은 워드프레스가 어떤 언어로 표시될 지를 지시하고 문맥은 어떤 상황의 텍스트를 출력해야 하는지를 지시한다.

레이블과 관련된 커스텀 포스트의 옵션은 크게 두 가지가 있다. label과, labels이다. 사실 두 옵션을 다 사용할 필요는 없고, 커스텀 포스트를 만들 때 둘 중 하나만 써도 된다. label은 아주 심플하게 레이블을 만들고 싶을 때 (다시 말해 레이블에 그다지 신경을 쓰지 않아도 좋을 때), 반면 labels는 각 레이블에 대해 세부적인 문맥에 맞춰 텍스트를 지정해 줄 수 있다.

label 옵션

가장 기본으로 사용할 수 있는 것이 label 옵션이다. 아주 간단한 용도의 커스텀 포스트라면 이 옵션만 사용해도 큰 문제는 없다. 나머지 세세한 레이블 텍스트는 기본 타입인 ‘post’를 기준으로 적절히 메꿔지기 때문이다. 왠만큼 까다로운 사람이 아니라면 이 것 때문에 불편을 호소할 일은 거의 없을 것이다.

이 옵션만을 주고 ‘wphack’ 타입의 커스텀 포스트를 만들었다. 레이블 이름은 ‘HackPosts’로 정했다. 보통 복수로 레이블 이름을 주는 것이 관례이다. 메뉴는 ‘post’ 타입에 준해 적절히 보간되고 번역되었다.

코드 내부에서 labels를 발견하지 못하고 label만 있다면 label에 의거해 모든 labels 세부 텍스트 항목을 만들어 내서 커스텀 포스트를 등록한다. 그러니까 커스텀 포스트를 만들면서 label과 labels를 동시에 쓸 필요는 없다.

labels 옵션

커스텀 포스트의 각 레이블을 보다 세심하게 신경 써 주어야 할 경우도 있을 수 있을 것이다. 이 경우를 위해 워드프레스는 labels라는 옵션을 추가로 제공한다. 이 옵션에서는 커스텀 포스트를 생성하면 생각할 수 있는 모든 경우에 대해 상세하게 텍스트를 지정해 줄 수 있다. 사실 본 포스팅의 주 목적.

우선 세부 옵션부터 나열해 보자.

• name
• singular_name
• add_new
• add_new_item
• edit_item
• new_item
• view_item
• search_items
• not_found
• not_found_in_trash
• parent_item_colon
• all_items
• archives
• insert_into_item
• uploaded_to_this_item
• featured_image
• set_featured_image
• remove_featured_image
• use_featured_image
• menu_name
• filter_items_list
• items_list_navigation
• items_list
• name_admin_bar

각 세부 옵션의 이름으로 이 텍스트가 무엇인지 추측을 할 수 있다. 그래서 적절하게 번역 텍스트를 주면 어차피 텍스트니 프로그램이 돌아가는 데는 큰 지장은 없다. 그렇지만 나는 확실히 이 텍스트가 어디서 어떻게 나오는지를 알아보고 싶었다.

name 레이블 옵션

포스트 타입에 대한 일반적 이름이다. 워드프레스 UI 전반에서 이 포스트 타입 단위를 지칭할 때 쓰인다. 위 설명된 label 옵션과 동일하게 복수형으로 지으면 된다. label 옵션을 쓰는 것과 labels 옵션에서 이 세부 옵션 하나만 쓰는 것은 사실 같다고 볼 수 있다.

singular_name 레이블 옵션

이 포스트 타입 하나의 개체를 지칭할 때 쓰이는 이름이다. 사실 UI 상에서는 이 텍스트가 보이는 일은 그리 흔치 않다. 하나 예를 들자면 아래 그림처럼 어드민 바에서 새로운 개체를 작성할 때의 레이블로 사용된다. (정확히 설명하자면 name_admin_bar 세부 옵션의 기본값이 singular_name 옵션값이기 때문이다)

만일 name만 있다면 singular_name은 name을 따라 간다. 복수, 단수 구분 없이 무조건. 그리고 name 마저도 없다면 이보다 한 단계 위의 label 옵션에서 name을 가져 온다. 그럼 label 옵션 마저 없다면? label의 기본값은 Posts, 혹은 Pages이다. 구조적인 타입이라면 Pages고 비구조적이라면 Posts로 이름이 만들어질 것이다.

한국어에서는 단수/복수 개념이 뚜렷하지 않긴 하지만, 어쨌든 옵션 이름이 의미하는 것처럼 단수로 지정해 주어야 한다.

참고로 Piklist라는 빠른 개발용 플러그인이 있다. 여기서 별도의 훅을 지정해 커스텀 포스트를 생성할 수 있도록 하는 기능을 제공한다. register_post_type 함수를 래핑하여 보다 편하게 쓸 수 있게 만든 것인데, 여기서는 name 인자를 하나만 넣어 줘도 영어 단수/복수 규칙을 추측해 singular_name, plural name을 지정하는 기능을 갖추고 있다. 왠지 영어권 사용자에게는 나름 유용해 보인다.

add_new 레이블 옵션

메뉴에 나오는 ‘Add New’ 텍스트를 변경할 수 있다. 이 텍스트는 명백하게 두 곳에서 사용되고 있다.

어드민 메뉴의 메뉴 항목과 페이지 h1 문단 제목 우측의 버튼의 텍스트로 사용된다.

add_new_item, edit_item 레이블 옵션

add_new_item은 새 개체 작성 페이지의 h1 문단 제목으로 사용된다. ‘_item’ 접미의 item은 해당 단수 개체 이름이라고 생각하면 된다. 마찬가지로 edit_item은 개체 편집 페이지의 h1 문단 제목으로 사용된다. 아래 그림은 이 옵션을 지정하지 않은 것과 한 것을 비교한 것이다.

new_item 레이블 옵션

UI 전반에서 사용되는 레이블은 아닌 것으로 보인다. 코드의 완전성을 위해 넣은 듯하다.

view_item 레이블 옵션

개체 편집 화면의 어드민 바에는 프론트 화면에서 작성된 개체가 어떻게 보이는지 바로 확인하는 메뉴가 삽입된다. 이 옵션으로 그 텍스트를 변경할 수 있다.

또 참고로 이 레이블 텍스트는 댓글(Comments) 목록 화면의 ‘댓글이 달린 글(In Response To)’ 칼럼에서 사용된다. ‘글 보기(View Post)’ 링크 텍스트가 바로 그것이다. 물론 이것은 기본인 ‘post’ 타입에만 해당되겠지만.

search_items 레이블 옵션

개체 목록을 검색하기 위한 검색 버튼의 텍스트를 변경할 수 있다.

not_found, not_found_in_trash 레이블 옵션

not_found 레이블 옵션은 개체 검색 결과가 없는 경우에 이를 알리기 위한 텍스트를 위해 주어진다. 마찬가지로  not_found_trash 레이블 옵션은 휴지통에서 검색한 경우의 텍스트이다.

parent_item_colon 레이블 옵션

포스트 타입을 계층적(hierarchical)으로 설정한 경우 개체의 부모 개체를 설정해 줄 수 있다.

사실 이 레이블은 UI 상에서 찾아 보기가 어렵다. 이 텍스트가 명시적으로 보이는 한 예는 이렇다. 포스트 목록에서 부모 포스트가 삭제되거나 휴지통으로 이동하여 부모-자식 위계에 영향을 주는 사안이 발생한 경우 자식 포스트에서 부모 포스트가 어떤 것인지 표시해 줄 때 사용된다.

아래 그림처럼 부모 – 자식 관계가 있는 페이지 목록이 있다고 보자.

그리고 부모 페이지인 ‘Parent Page’를 휴지통으로 보내고 난 다음 목록을 다시 불러오면 아래처럼 화면이 변경된다.

텍스트 구조는 이렇다: | parent_item_colon <부모 개체의 이름>

한편 포스트 타입 구조가 아닌 카테고리에 해당하는 케이스지만 비슷한 사례라 기록을 남겨 본다. 아래 그림은 ‘post’ 편집 화면에서 카테고리 설정을 위한 메타박스 UI이다.

워드프레스에는 시각적으로 표시되지는 않는 여러 텍스트들이 HTML 코드 상에 존재한다. 시각장애인을 위해 존재하는 들리는 텍스트들이다. 그림의 붉은 상자로 표시된 쪽의 입력 상자를 위한 들리는 레이블이 존재한다. 이 레이블의 텍스트로 카테고리의 parent_item_colon 속성이 사용된다.

HTML 보면 아래 코드와 같이 출력된다.

<label class="screen-reader-text" for="newcategory">Add New Category</label>
<input type="text" name="newcategory" id="newcategory" class="form-required form-input-tip" value="New Category Name" aria-required="true"/>
<label class="screen-reader-text" for="newcategory_parent">
  Parent Category:
</label>

label for=”newcategory_parent” 태그를 보면 Parent Catecory: 라는 텍스트를 확인할 수 있다. 포스트 레이블이 아닌 카테고리 레이블의 용례이지만, 둘 다 엇비슷하므로 같이 남겨 본다.

all_items 레이블 옵션

‘모든 개체들’의 의미를 지닌 텍스트를 출력하기 위해 지정할 수 있다.

커스텀 포스트를 생성하면 나오는 하위 메뉴로 ‘모든 글’, ‘모든 페이지’ 같은 ‘모든 개체’ 항목이 자동으로 생성된다. 이 때 이 레이블이 사용된다.

한편 커스텀 포스트의 ‘show_in_menu’ 옵션은 불리언 혹은 문자열을 넣을 수 있다. 불리언의 경우는 메뉴에 보일 것인지 숨길 것인지 정하기 위해 사용한다. 그런데 인수로 문자열로도 입력할 수도 있는데, 이렇게 되면 해당 메뉴의 하위 메뉴에 커스텀 포스트 UI가 삽입된다.

예를 들어 ‘show_in_menu’의 값으로 ‘tools.php’ 문자열을 입력하면 HackPosts UI는 도구(Tools) 메뉴의 하위 메뉴로 이동하게 된다. 이 때에도 레이블의 텍스트로 all_items 레이블 옵션이 사용된다.

다른 예로 두 유저간에 개체 편집 충돌이 일어나는 경우에 출력된다. 가령 사용자 A가 편집 중인 개체를 사용자 B도 편집하기 위해 해당 URL로 접근한다고 생각해 보자. 그러면 사용자 B는 다음과 같은 메시지를 받음으로써 사용자 A가 편집 과정에 있음을 통지받는다.

이 때 사용자 B가 Take Over 단추를 눌려 편집권을 이양받게 되면, 편집 중이었던 사용자 A는 이런 메시지를 실시간으로 전달받게 된다. 이 때 all_items 레이블이 사용된다. (설명은 장황한데, 정말 너무 사소한 부분이다…)

archives 레이블 옵션

메뉴 편집 화면에서 해당 타입의 아카이브를 위한 레이블이다. 아래 그림을 보자.

‘All HackPosts Items’라고 나온 것은 archives 레이블 옵션이 정해지지 않았을 때이다. 이 값이 없다면 all_items레이블 옵션에서 가져오기 때문에 all_items 레이블이 출력된다.

archives 레이블을 적절히 조절하면 위 그림처럼 별도의 레이블을 가지게 된다.

insert_into_item 레이블 옵션

미디어 삽입 화면에서 개체에 미디어를 삽입시키는 버튼 텍스트로 사용된다.

uploaded_to_this_item 레이블 옵션

‘미디어 추가(Add Media)’ 버튼을 클릭하면 나오는 미디어 관리 창에 속한 미디어 필터의 한 레이블 텍스트. 아래 그림과 같은 위치에 있다.

이 아이템으로 업로드된 미디어란 의미는 로 연결되었다는 의미이다. 현재 편집 중인 화면에서 미디어 추가를 눌러 파일을 업로드하면, 해당 업로드 파일은 편집 중인 개체에 특정지어 업로드 되었다고 간주된다. DB에서는 attachment 포스트의 post_parent 필드가 현재 편집 중인 post ID로 대입된다는 의미로 볼 수 있다.

featured_image, set_featured_image, remove_featured_image 레이블 옵션

support 옵션에 ‘thumbnail’을 추가하면 커스텀 포스트도 특성 이미지를 지정할 수 있다. 특성 이미지라는 이름을 다른 것으로 변경하기 위해 featured_image를 사용한다. 이름으로 추측 가능하다. 다들 특성 이미지 관련 UI에서 레이블로 사용된다.

use_featured_image 레이블 옵션

이 레이블이 직접적으로 사용된 UI를 찾기가 쉽지 않다. 왜냐하면 이 레이블이 코어에서 직접적으로 쓰이는 곳은 단 한 곳, wp-admin/includes/media.php 파일의 get_media_item() 이라는 함수 뿐이다.

get_media_item 함수는 이미지 첨부 메타데이터를 수정할 수 있는 HTML 폼을 출력하는데, 워드프레스 관리 UI 상에서 일반적인 방법으로는 이 주소가 명시적으로 나타난 곳이 없다. 최근 버전의 워드프레스는 미디어 파일의 조회와 수정은 post.php에서 모두 처리하도록 되어 있다.

그렇지만 이 화면을 완전히 볼 수 없는 것은 아니다. 직접 주소를 쳐서 들어가면 된다. 다음과 같은 경로로 접근하면 된다.

<site_url>/wp-admin/media.php?action=edit&attachment_id=<attachment_id>&post_id=<post_id>

action, attachment_id 두 파라미터는 정상적으로 화면이 출력되기 위해 필수적으로 있어야 하며, 특성 이미지 속성까지 출력시키려면 post_id 파라미터가 별도로 필요하다. 이 때 attachment_id는 attachement 포스트의 ID, post_id는 특성 이미지를 집어 넣고 싶은 포스트의 ID이다. 올바르게 입력하면 아래 그림과 같은 화면이 출력된다. 목록 마지막에 use_featured_image 레이블 옵션이 나오는 것을 확인할 수 있다.

menu_name 레이블 옵션

기본값이 name 옵션과 같은 이것은 관리자 메뉴의 레이블을 별도로 지정하고 싶을 때 사용된다.

filter_items_list, items_list_navigation, items_list 레이블 옵션

이 레이블들은 숨겨져 있고 스크린 리더를 위한 텍스트로 입력된다. 개체 목록 UI 화면에서 <h2 class=’screen-reader-text’>를 검색하면 해당 레이블 값이 나오는 것을 확인할 수 있다.

filter_items_list는 필터 버튼을 위한 스크린 리더 텍스트이다.

<h1>HackPosts
    <a href="http://wphack.vagrant:8080/wp-admin/post-new.php?post_type=wphack" class="page-title-action">
        Add New HackPost
    </a>
</h1>
<h2 class='screen-reader-text'>
    Filter HackPosts List
</h2>
<ul class='subsubsub'>
...

items_list_navigation은 개체의 수가 많아 몇 개의 페이지로 나뉘어 질 때 페이지네이션을 위한 스크린 리더 텍스트로 사용된다.

<h2 class='screen-reader-text'>
    HackPosts List Navigation
</h2>
<div class='tablenav-pages'>
    <span class="displaying-num">6 items</span>
    <span class='pagination-links'>
    ...

items_list는 테이블 목록 바로 위에 있다.

<h2 class='screen-reader-text'>HackPosts List</h2>
<table class="wp-list-table widefat fixed striped pages">

name_admin_bar 레이블 옵션

어드민 바의 ‘+ 새로 추가 (+ New)’ 메뉴에 새 개체를 삽입하는 명령을 추가할 수 있다. 이 때의 레이블 옵션을 별도로 지정할 수 있다. 이 옵션이 없다면 singular_name 레이블 옵션을 가져와 사용한다.

마치며

어떤 레이블이 UI 어디에서 어떻게 쓰이는지에 대해 굉장히 궁금했었다. 물론 코덱스에 있는 대로 적당히 뉘앙스나 문맥만 파악한 후 개체에 맞게 말을 고쳐 주면 그만일 수도 있지만, 그 레이블이 나오는 정확한 문맥을 알 수 없었기에 과연 올바른 의미를 가진 레이블로 제공되는지 확실히 알 수가 없었다. 이번 기회로 각 레이블이 어떤 상황에서 어떻게 쓰이는지 명확히 파악해 보았다. 이젠 보다 자신있게 커스텀 포스트의 레이블을 다룰 수 있으리라 생각한다.

의문점.

결제 관련 정보(Billing details)에서는 결제자의 이메일과 전화번호를 적는 란이 있다. 그런데 배송 정보(Shipping details)에는 그렇지 않다. 조금 전 생짜 워드프레스에 우커머스만 올려 놓고 테스트를 해 배송 정보에는 이메일과 전화번호 필드가 포함되지 않음을 확인했다.

간혹 우커머스의 결제와 배송이 서로 다른 경우에는 어떻게 하란 말인가? 한국에서는 배송을 할 때 배송 상자에 받는 사람의 전화번호도 같이 적게 되어 있다. 그리고 택배 기사님들이 보통 수신인이 부재중일 경우 이 전화로 전화를 걸기도 하고. 결국 한국 상황에 맞춰 일괄적으로 기능 확장을 하는 수 밖에 없지 않은가?

이번 포스팅은 포스트 목록에서 커스텀 필드(메타 테이블 값)도 검색되게 하는 방법에 대해 적고자 합니다. 거두절미하고 커스텀 포스트를 만들어 보겠습니다.

커스텀 포스트 생성

포 스트 타입은 ‘my-test-post’입니다. 그냥 별다른 설정 없이 기본값으로만 만들었어요. 그리고 이 타입의 포스트에는 ‘my_test_value_1’, ‘my_test_value_2’라는 커스텀 필드를 가지도록 설정을 했습니다. 플러그인이 활성화 되면 임시로 2개의 포스트를 자동 생성하도록 했습니다. 그리고 비활성화되면 해당 포스트와 커스텀 필드는 삭제하도록 만들었습니다.

※ 스크린샷을 찍을 때는 편의를 위해 별도의 플러그인을 사용해 커스텀 필드를 생성했습니다만, 나중에 플러그인 구현에는 그냥 커스텀 포스트를 생성하는 것으로 변경했습니다. 플러그인 소스를 직접 활성화 했을 때는 위 스크린샷과는 약간 다를 수 있습니다.

기본적인 포스트 검색

이 렇게 커스텀 포스트를 생성한 후, 포스트 목록에서 몇몇 키워드를 넣고 검색을 해 봅니다. 여기 검색은 그다지 똑똑한 편이 아니라 키워드를 정확하게 넣어야만 합니다. 그런데 여기서 제가 지적하고픈 문제가 생깁니다. 검색은 포스트 제목과 내용에만 국한된다는 점입니다. 아마 기본 포스트 목록도 마찬가지일 것입니다.

보통 커스텀 포스트는 단지 포스트 제목(post_title), 포스트 내용(post_content), 혹은 발췌(post_excerpt) 같은 포스트 테이블(보통 wp_post 테이블) 기본 필드 뿐만 아니라 메타 테이블(보통 wp_postmeta)을 활용한 다양한 커스텀 필드를 활용하고 싶기 때문에 생성합니다. 또한 그런 커스텀 필드들은 별도의 조정을 해서 목록 테이블에서도 표시되도록 만들기도 하구요. 바로 아래 그림처럼 말이죠.

위 그림은 위치 정보를 기록하기 위한 다른 형태의 커스텀 포스트입니다. 위도/경도를 출력하는 ‘Position’ 칼럼, 지도의 상세 주소를 표시하는 ‘Address’ 칼럼, 그리고 그 장소에 대해 임의로 평점을 매기는 ‘Rating’ 칼럼은 워드프레스 자체에서는 정의되지 않았죠. 그러나 커스텀 포스트를 통해 저런 별도의 값도 저장하도록 확장이 가능하고, 또 이렇게 목록에 원하는 형태로 출력되록 조정도 가능합니다.

이렇게 테이블이 구성되면 당연히 사용자는 “주소”를 기반으로 검색이 될 거라 생각할 수 있습니다. 가령 “서울특별시”라는 검색어로 서울에만 있는 장소만 나타나게요. 그러나 주소는 커스텀 필드이므로 아무리 검색을 해도 나타날 수가 없답니다. 왜냐면 커스텀 필드는 기본 검색 대상이 아니니까요. 다시 말씀드리지만 기본 검색 대상에 포함되는 것은 단지 포스트 제목과 본문 내용 뿐입니다.

검색 작동 방식 분석

URL 테스트

이 렇게 커스텀 필드가 검색에서 제외될 수 밖에 없는 이유는 당연합니다. 코어가 어떤 커스텀 값을 기준으로 검색해야 할지 알 수 없기 때문이죠. 알게 모르게 하나의 포스트에는 여러 메타 키와 값들이 붙습니다. 그 중에는 사용자가 지정한 값들이 있을 수도 있고, 아니면 시스템이 관리 목적으로 붙여둔 것들도 있습니다. 그러므로 사용자가 별도의 플러그인을 작성하여 명시적으로 그 값이 검색되도록 흐름을 수정하는 수 밖에는 없습니다.

워드프레스 관리자 화면에서 검색어를 넣어 질의를 하면 URL이 변경됩니다. 예를 들어 “테스트”라는 검색어를 넣으면 다음과 같은 URL로 연결이 됩니다. 여기서 검색어와 관련된 쿼리 변수는 ‘s’임을 쉽게 눈치챌 수 있겠죠?

edit.php?s=테스트&post_status=all&post_type=my-test-post&action=-1&m=0&paged=1&mode=list&action2=-1

그렇다면 워드프레스는 어떤 작업을 통해 “s=테스트”를 실제 DB 검색까지 되도록 만들까요? 코어가 동작하는 흐름을 따라가보면 알 수 있겠죠.

워드프레스 코어의 흐름 따라가 보기

워드프레스 버전 4.2.2 기준, wp-admin/edit.php 163번째 줄에서 테이블이 표시될 아이템을 준비하는 코드가 나옵니다. 이 부분은 프로그램 코드를 따라가므로 설명이 약간 복잡할 수 있습니다.

$wp_list_table->prepare_items();

prepare_items() 메소드는 wp-admin/includes/class-wp-posts-list-table.php 소스의 ‘WP_Posts_List_Table’ 클래스에서 정의된 것입니다. 해당 부분인 105번째 줄을 살펴 보면, wp_edit_posts_query() 함수가 호출됩니다.

$avail_post_stati = wp_edit_posts_query();

이 함수는 wp-admin/includes/post.php 975번째 줄에 정의되어 있습니다. 여기서 1048번째 줄에 wp() 함수가 호출되는 것을 찾을 수 있습니다.

한 편 wp() 함수는 전역으로 선언되어 있는 WP 인스턴스의 main() 메소드를 호출합니다. WP 클래스는 wp-includes/class-wp.php 에 선언되어 있고 main() 메소드는 이 파일 607줄에서 찾을 수 있습니다. 전역으로 선언된 WP 인스턴스는 wp-settings.php 279번째 줄에서 찾을 수 있습니다.

$GLOBALS['wp'] = new WP();

URL 로 질의한 내용을 바탕으로 포스트를 가져오는 단계는 WP::query_posts() 입니다. 이 메소드 안에서 WP_Query 클래스의 query() 메소드를 호출합니다. WP_Query는 wp-includes/query.php 라인 837에 선언되어 있습니다.

WP_Query::query()는 WP_Query::get_posts()를 호출합니다(라인 2380). WP_Query::get_posts() 안에서 WP_Query::parse_search()가 호출됩니다(라인 2684).WP_Query::parse_search() 함수(라인 2055)는 SQL 쿼리의 일부분을 만들어냅니다. 아래는 WP_Query::parse_search() 결과의 한 예입니다.

AND (((wp_posts.post_title LIKE ‘%테스트%’) OR (wp_posts.post_content LIKE ‘%테스트%’)))

정리하면 이렇습니다.

• edit.php: WP_Posts_List_Table::prepare_items() 호출
• WP_Posts_List_Table::prepare_items() 에서 wp_edit_posts_query() 호출
• wp_edit_posts_query() 에서 WP::main() 호출
• WP::main(), 여기서 WP::parse_request() 호출, 다시 WP::query_posts() 호출
• WP::query_posts() 에서 WP_Query::query() 호출, WP_Query::get_posts() 호출, WP_Query::parse_search() 호출

검색 쿼리 부분 결과를 보면 포스트 제목과, 포스트 내용만 가지고 LIKE 질의를 만들고 있습니다. 이렇기 때문에 포스트들은 제목과 내용 밖에 검색되지 않는 것입니다.

커스텀 필드가 검색되도록 수정

그렇다면 커스텀 필드를 검색할 수 있도록 SQL을 수정하도록 해 보지요. 우선 쿼리를 해석하는 과정에서 메타 필드를 검색하도록 조정해야 합니다. 이 때 ‘pre_get_posts’ 액션을 사용하는 것이 적절해 보입니다. 왜냐하면 WP_Query::get_posts() 메소드의 구현을 보면, WP_Query::parse_query() 메소드 호출 이후 처음 불리는 액션이기 때문입니다. 여기서 해석된 쿼리를 일부 변경하는 것이 가능합니다.

add_action( 'pre_get_posts', 'my_test_get_posts' );
function my_test_get_posts( $query ) {
   global $pagenow;
   global $post_type;

   $term = $query->get( 's' );

   if( !is_admin() || $post_type != 'my-test-post' || $pagenow != 'edit.php' || empty( $term ) ) {
      return;
   }

   $meta_query = $query->get( 'meta_query' );

   $search = array(
      'relation' => 'OR',
      array(
         'key'     => 'my_test_value_1',
         'value'   => $term,
         'compare' => 'LIKE'
      ),
      array(
         'key'     => 'my_test_value_2',
         'value'   => $term,
         'compare' => 'LIKE'
      )
   );

   $meta_query[] = $search;
   $query->set( 'meta_query', $meta_query );
}

그런데 아직은 문제가 있습니다. 커스텀 필드의 값으로 검색해도 값은 검색되지 않을 것입니다. 완성된 SQL 쿼리를 보면 이유를 알 수 있습니다.

SELECT SQL_CALC_FOUND_ROWS wp_posts.ID FROM wp_posts
INNER JOIN wp_postmeta ON ( wp_posts.ID = wp_postmeta.post_id )
WHERE 1=1
AND (((wp_posts.post_title LIKE ‘%다섯%’) OR (wp_posts.post_content LIKE ‘%다섯%’)))
AND ( (
( wp_postmeta.meta_key = ‘my_test_value_1’ AND CAST(wp_postmeta.meta_value AS CHAR) LIKE ‘%다섯%’ )
OR ( wp_postmeta.meta_key = ‘my_test_value_2’ AND CAST(wp_postmeta.meta_value AS CHAR) LIKE ‘%다섯%’ )
) )
AND wp_posts.post_type = ‘my-test-post’
AND (
wp_posts.post_status = ‘publish’
OR wp_posts.post_status = ‘demo’
OR wp_posts.post_status = ‘lock’
OR wp_posts.post_status = ‘pending’
OR wp_posts.post_status = ‘future’
OR wp_posts.post_status = ‘draft’
OR wp_posts.post_status = ‘demo’
OR wp_posts.post_status = ‘lock’
OR wp_posts.post_status = ‘private’
)
GROUP BY wp_posts.ID
ORDER BY wp_posts.post_title LIKE ‘%다섯%’ DESC, wp_posts.post_date DESC
LIMIT 0, 20

붉은색으로 된 글씨는, 위에서 메타키와 값을 쿼리 조건으로 주었을 때 생성되는 부분인데. 기본적으로 메타 키/값을 이용해 검색을 할 경우 무조건 ‘AND’로 시작되게 짜여 있습니다. 이렇게 메타 쪽 쿼리를 작성하는 코어 소스는 wp-includs/meta.php 부분입니다. 다행히 바로 저 붉은 색 부분만 조절할 수 있는 필터도 제공되는데, 해당 파일의 1197번째 줄 ‘get_meta_sql’ 필터입니다. 대개 포스트 메타 테이블은 항상 포스트 테이블과 조인되며, AND 조건절로 이어져 진행된다는 가정이 있는 것 같습니다. 하지만 이 경우에는 적합하지 않지요. 이 부분을 변경해야 합니다.

가장 간단한 해결책은 붉은색 부분의 AND를 바로 OR로 교체하는 것입니다. 코드 마지막 부분에 다음처럼 필터를 걸어 주면 됩니다.

add_filter( 'posts_search', function ( $sql ) {
add_filter( 'get_meta_sql', function( $sql ) {
    $sql['where'] = preg_replace( '/\s*AND\s+(.+)/ms', ' OR $1', $sql['where'] );
    return $sql;
});

이 때 주의할 점이 있습니다. 연산자가 AND에서 OR로 변경되면서 잠재적인 버그의 요소가 있을 수 있습니다(OR가 연산 순위가 AND보다 낮으므로 AND 연산자가 먼저 고려된 다음 OR가 계산됩니다). 원래 쿼리는 사실상 AND 연산으로만 구성되어 있습니다. 그런데 여기서 불쑥 OR가 발생하므로,

1=1 AND (포스트 테이블 검색 조건) AND (메타 테이블 검색 조건) AND (포스트 타입 조건) AND (포스트 상태 조건)

와 같은 구조는

1=1 AND (포스트 테이블 검색 조건) OR (메타 테이블 검색 조건) AND (포스트 타입 조건) AND (포스트 상태 조건)

으로 변경됩니다.

이 때 1=1은 항상 참이고, 또 (포스트 타입 조건) 또한 이미 콜백 함수 처음에 if 문으로 검사를 하므로 여기까지 흐름이 왔다면 항상 참입니다. 그러므로

(포스트 테이블 검색 조건) OR (메타 테이블 검색 조건) AND (포스트 상태 조건)

이 경우 (메타 테이블 검색 조건) AND (포스트 상태 조건) 부분이 우선 검사됩니다. 여기서 약간의 문제가 발생할 수 있습니다. 포스트의 제목과 내용이 검색어와 일치하는 경우 포스트 상태에 관계 없이 검색될 수 있다는 점입니다. 원래 검색은 휴지통에 넣지 않은 포스트를 대상으로 해야 하는 것인데, 이렇게 쿼리가 변경될 경우에는 포스트 상태가 지워져도 검색 결과에 포함될 수 있을 것입니다. 이것은 워드프레스의 기본 동작 방식이 아닙니다. 그러므로 쿼리 구조를 대대적으로 변경하여,

1=1 AND (포스트 테이블 검색 조건 OR (메타 테이블 검색 조건)) AND (포스트 타입 조건) AND (포스트 상태 조건)

와 같이 WHERE절을 변경해야 할 것입니다. 그러므로 위 필터를 삭제하고 아래 세 개의 필터를 더해 주면 됩니다. 개인적으로 전역 변수의 사용을 꺼리지만, 설명의 편의를 위해 사용했습니다.

$my_test_search_query = '';
$my_test_meta_query = '';

// post_title, post_content 검색 쿼리 부분 기록
add_filter( 'posts_search', function ( $sql ) {
 global $my_test_search_query;
 $my_test_search_query = $sql;
 return $sql;
} );

// meta 부분 쿼리 기록 (join, where 키로 구성된 array)
add_filter( 'get_meta_sql', function ( $sql ) {
 global $my_test_meta_query;
 $my_test_meta_query = $sql;
 return $sql;
} );

// where 절을 최종 편집
add_filter( 'posts_where', function ( $sql ) {
 global $my_test_search_query, $my_test_meta_query;

 $m = NULL;
 // search_query 문자열은 보통 괄호 두 개 안에 post_title, post_content 각 필드 조건을 OR로 묶음.
 if( preg_match('/\(\((.+)\)\)/ms', $my_test_search_query, $m ) ) {

 $meta_part = $my_test_meta_query['where'];

 // WHERE 절에서 AND ... 로 시작하는 meta 검색을 삭제
 $sql = str_replace( $meta_part, '', $sql );

 $post_part = $m[1];
 $meta_altered = preg_replace( '/\s*AND\s+(.+)/ms', ' OR $1', $meta_part );
 $substitute = 'AND ((' . $post_part . $meta_altered . '))';

 // post title, post content 검색과 같이 커스텀 필드도 OR 조건으로 검색
 $sql = str_replace( $my_test_search_query, $substitute, $sql );
 }

 return $sql;
} );

이렇게 쿼리를 대대적으로 수정하면 다음처럼 쿼리가 출력됩니다.

SELECT SQL_CALC_FOUND_ROWS wp_posts.ID FROM wp_posts INNER JOIN wp_postmeta ON ( wp_posts.ID = wp_postmeta.post_id ) WHERE 1=1 AND (((wp_posts.post_title LIKE ‘%01%’) OR (wp_posts.post_content LIKE ‘%01%’) OR (
(
( wp_postmeta.meta_key = ‘my_test_value_1’ AND CAST(wp_postmeta.meta_value AS CHAR) LIKE ‘%01%’ )
OR
( wp_postmeta.meta_key = ‘my_test_value_2’ AND CAST(wp_postmeta.meta_value AS CHAR) LIKE ‘%01%’ )
)
))) AND wp_posts.post_type = ‘my-test-post’ AND (wp_posts.post_status = ‘publish’ OR wp_posts.post_status = ‘demo’ OR wp_posts.post_status = ‘lock’ OR wp_posts.post_status = ‘pending’ OR wp_posts.post_status = ‘future’ OR wp_posts.post_status = ‘draft’ OR wp_posts.post_status = ‘demo’ OR wp_posts.post_status = ‘lock’ OR wp_posts.post_status = ‘private’) GROUP BY wp_posts.ID ORDER BY wp_posts.post_title LIKE ‘%01%’ DESC, wp_posts.post_date DESC LIMIT 0, 20

 

마치며

워드프레스의 막강한 플러그인들이 워낙 많고, 또 이러한 단순 키워드 검색은 그다지 효율적이지 않을 수 있습니다. 그러나 때로는 이러한 검색이 필요한 순간이 있을 것입니다. 특히 커스텀 포스트에서 검색 확장이 용이하지 않다는 점이 아쉬워서 이렇게 글을 남겨 보았습니다. 설명한 플러그인 소스 전문은 여기에서 확인하실 수 있습니다.