워드프레스 WP_Query

사용자가, 특정 콘텐츠를 사이트에 출력하고 싶다면 워드프레스에서 제공하는 쿼리 클래스를 사용하면 됩니다. 기본적이며 대표적인 것, 콘텐츠와 콘텐츠의 관련 데이터까지 모두 쉽게 접근할 수 있는 것으로 WP_Query 클래스가 있습니다.

커스텀 쿼리

사용자가 ‘쿼리를 사용’한다는 것은 기본으로 가능하지 않은 콘텐츠를 출력한다는 뜻과 같습니다. 사용하지 않는다는 것은 인위적인 작업이 없다는 뜻입니다. 따라서 워드프레스 쿼리를 말한다는 것부터가 ‘워드프레스 커스텀 쿼리’를 뜻합니다.

워드프레스 쿼리 클래스와 함수

쿼리와 관련한 워드프레스 제공 클래스나 함수는 다음의 몇 가지가 있습니다. 예제에서 사용하는 것도 있고, 그렇지 않은 것도 있습니다. 또, 일부는 하나의 클래스에 인수로 사용할 때도 있습니다.

WP_Query
pre_get_posts
get_posts
get_post
wpdb
WP_Term_Query
WP_Meta_Query
WP_User_Query
WP_Comment_Query
query_posts

WP_Query

이름처럼 ‘워드프레스 쿼리의 전부’라고 생각하면 됩니다. 특정 조건의 콘텐츠를 출력하고 싶다면 고민하지 말고 선택하여 사용하세요. 예외가 있다 해도, 워드프레스는 이 클래스로 콘텐츠를 출력하며 테마에서 워드프레스 루프(The Loop)와 함께 사용합니다. 이 클래스와 함께 워드프레스 루프에서 사용할 수 있는 많은 함수가 있어 유리하며 편리한 워드프레스의 핵심 쿼리 클래스입니다.

pre_get_posts

목록에서 pre_get_posts 함수는 예제에서 아카이브와 검색 결과 페이지 등에서 attachment 타입의 포스트만 출력하도록 정의하여 이미 사용하고 있습니다. 이 함수는 사용자가 지정한 조건으로 ‘메인 쿼리’를 변경하여 워드프레스 기본 출력을 수정하므로 ‘커스텀 쿼리’로 사용하는 것입니다.

WP_Term_Query

목록에서 WP_Term_Query 클래스는 워드프레스 4.6 버전에 추가된 것으로 나중의 예제 과정에서 사용합니다. 이 클래스는 분류의 term 데이터 관련 쿼리 클래스로 비슷한 get_terms 함수와 달리 쿼리 캐싱으로 성능 이점이 있습니다.

wpdb

쿼리는 결국, 데이터베이스의 데이터를 조회하므로 어떤 것이든 SQL 구문을 최종 생성(trigger)하여 데이터를 검색합니다. 따라서, 다른 과정을 생략하고 데이터베이스에 바로 접근하려면 wpdb 클래스를 사용하면 됩니다. 이 클래스는 장점과 단점이 존재하지만, 특정 데이터 출력에 유리한 때가 있습니다.

설명하지 않은 항목도 워드프레스는 기본 및 내부적으로 사용하여 콘텐츠 출력을 결정하여 제공합니다.

WP_Query 클래스

워드프레스 WP_Query 클래스는 여러 인수(파라미터) 배열로 출력 조건을 지정할 수 있으며, 클래스 내부의 함수(method)와 함께 사용하여 쉬운 동적 데이터 출력이 가능합니다. 내부 함수나 인수 등의 정보는 실 예시나 예제를 반복하여 경험하는 것이 좋습니다. 필요할 땐 코덱스에서 함수나 인수 정보를 찾아서 사용하면 됩니다.

메인 쿼리 전역 변수 $wp_query

다음은 워드프레스 테마에서 쉽게 볼 수 있는, 기본적인 워드프레스 루프 패턴입니다. 조건과 함께 나열하였습니다.

if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        //
    endwhile;
else :
    //
endif;

위의 코드는 다음과 같습니다.

if ( $wp_query->have_posts() ) :
    while ( $wp_query->have_posts() ) : $wp_query->the_post();
        //
    endwhile;
else :
    //
endif;

다음의 조건 태그(함수)도 마찬가지입니다. 일부만 나열하였습니다.

$wp_query->is_home();
$wp_query->is_archive();
$wp_query->is_singular();
$wp_query->is_post_type_archive();
$wp_query->is_search();

워드프레스는 $wp_query 전역 변수(또는 오브젝트)에 쿼리에 의한 정보를 담습니다. 이 정보에 따라 조건 태그를 결정하며, 워드프레스 루프에서 데이터를 출력합니다. 루프에서 다양한 함수와 추가 조건으로 제어하여 필터할 수도 있습니다.

커스텀 쿼리 인스턴스

사용자가 워드프레스에서 쿼리를 생각한다는 것부터 ‘커스텀 쿼리’를 뜻한다고 말했으며, 워드프레스의 기본 쿼리와 루프에는 $wp_query 전역 변수가 생략되어 있다고 했습니다. 결국, $wp_query 변수의 정보를 사용자가 원하는 것으로 변경한다면 ‘커스텀 쿼리’를 정의할 수 있습니다.

그러나, $wp_query 전역 변수는 워드프레스의 ‘메인 쿼리 변수’이므로 변수명을 그대로 사용하지 않는 것이 좋습니다. 다시, 커스텀 쿼리에서 $wp_query 변수명은 사용하지 않기로 합니다.

WP_Query 클래스를 사용하여 사용자가 원하는 쿼리를 정의하는 기본 패턴은 다음과 같습니다.

// 커스텀 쿼리 인스턴스 생성
$custom_query = new WP_Query( $arg );

조건 및 워드프레스 루프와 함께 정의하면 다음과 같습니다.

$custom_query = new WP_Query( $arg );
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) : $custom_query->the_post();
        //
    endwhile;
else :
    //
endif;

다음 조건의 콘텐츠를 출력한다고 가정합니다.

포스트 타입 : attachment
공개 상태 : inherit
출력 수 : 10
첨부되지 않은 attachment 포스트
포스트 제목 출력

위의 조건을 WP_Query 클래스 인수와 루프에 출력을 정의하면 다음과 같습니다.

$arg = array(
    'post_type' => 'attachment', // 포스트 타입
    'post_status' => 'inherit', // 공개 상태
    'posts_per_page' => 10, // 한 페이지 출력 수
    'post_parent' => 0, // 첨부되지 않은 포스트 (데이터베이스 _posts 테이블 post_parent 필드의 값이 0)
);
$custom_query = new WP_Query( $arg );
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) : $custom_query->the_post();
        the_title(); // 포스트 제목
    endwhile;
else :
    //
endif;

편집기의 연습장 파일에 위의 코드를 추가하고 사이트에서 연습장 페이지를 보면 결과를 알 수 있으며, 인스턴스에 사용할 수 있는 WP_Query 클래스의 인수를 모두 제시하기 어려우므로 코덱스를 참고하세요.

wp_reset_postdata

URL 요청의 기본 쿼리에 의한 워드프레스 기본 루프는 $post 전역 변수에 데이터를 담습니다. WP_Query 클래스를 사용한 커스텀 쿼리는 사이트 페이지 어디든 추가할 수 있고, 추가 수에 제한이 없습니다. 커스텀 쿼리도 $post 전역 변수에 데이터를 저장하는데, 추가한 커스텀 쿼리가 기본 또는 추가한 또 다른 쿼리의 결과에 영향을 줄 때가 있습니다.

이때, 커스텀 쿼리의 데이터를 담고 있는 $post 변수 데이터를 커스텀 쿼리 이전의 데이터, URL 요청에 의한 기본 데이터로 복원해야 합니다. 이때 wp_reset_postdata 함수를 사용하면 됩니다. 다음 코드를 참고하세요.

$arg = array(
    'post_type' => 'attachment', // 포스트 타입
    'post_status' => 'inherit', // 공개 상태
    'posts_per_page' => 10, // 한 페이지 출력 수
    'post_parent' => 0, // 첨부되지 않은 포스트 (데이터베이스 _posts 테이블 post_parent 필드의 값이 0)
);
$custom_query = new WP_Query( $arg );
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) : $custom_query->the_post();
        the_title(); // 포스트 제목
    endwhile;
    wp_reset_postdata(); // $post 변수 데이터 복원
else :
    //
endif;

보통 워드프레스의 콘텐츠 영역 아래 또는 페이지 사이드 영역에 특정 포스트 등의 콘텐츠를 출력하는 때가 많은데, 이때 $post 변수를 복원하지 않으면 올바른 데이터가 출력되지 않을 수 있습니다. 커스텀 쿼리를 추가한 페이지에 다른 쿼리에 의한 데이터가 없어도 추가하는 것이 좋습니다.

페이지 템플릿

WP_Query 클래스의 커스텀 쿼리는 페이지 템플릿에 추가하는 때가 많습니다. 특정 콘텐츠 집합을 워드프레스 루프를 사용하여 출력하는 때가 일반적이기 때문에 생기는 보편적 흐름이며, 절대적인 것은 아닙니다. 싱글 포스트 페이지에서 싱글 포스트의 특정 메타 데이터와 관련이 있는 다른 포스트를 출력할 때는 페이지 템플릿이 필요하지 않지만, WP_Query 클래스의 커스텀 쿼리를 사용할 수 있습니다.