[워드프레스] 13. 훅 : 액션과 필터, 워드프레스 확장의 심장

(워드프레스 해부 ⑬) 훅

데이터를 봤으니 이제 엔진이다. 워드프레스가 그토록 유연한 이유의 8할은 훅(hook)에 있다. 코어 파일을 한 줄도 안 건드리고, 정해진 지점에 내 코드를 끼워넣는 장치다. 플러그인·테마가 전부 이걸로 동작한다.

훅은 두 종류다.

• 액션(action) — “이 시점에 내 코드를 실행해줘.” 예: 헤더가 그려질 때 스크립트 추가. add_action('훅이름', 함수).
• 필터(filter) — “이 데이터가 지나갈 때 값을 바꿔서 돌려줘.” 예: 글 제목에 뭔가 붙이기. add_filter('훅이름', 함수). 필터 함수는 반드시 값을 return해야 한다.

이 둘의 차이가 핵심이다. 액션은 실행만 하고 끝(반환값 없음), 필터는 받은 값을 가공해 돌려준다. “뭔가 하고 싶으면 액션, 뭔가 바꾸고 싶으면 필터”로 외우면 된다.

직접 해보기

// 필터 — 모든 글 제목 뒤에 표시 (값을 받아서 바꿔 return)
add_filter( 'the_title', function( $title ) {
    return $title . ' ✨';
} );

// 액션 — 푸터에 한 줄 출력 (실행만, return 없음)
add_action( 'wp_footer', function() {
    echo '<p style="text-align:center">직접 건 훅</p>';
} );

우선순위(priority)와 인자 개수도 줄 수 있다. add_filter('the_title', 함수, 20, 2)처럼. 숫자가 작을수록 먼저 실행된다. 여러 플러그인이 같은 훅에 붙을 때 순서를 이걸로 조정한다.

✅ 확인 — the_title 필터를 걸고 아무 글이나 열었을 때 제목 뒤에 ✨가 붙으면, 코어를 안 건드리고 출력에 끼어든 것이다. 워드프레스 확장의 원리를 손으로 확인한 셈이다.

액션 예제 — 실행 시점에 끼어들기

액션은 정해진 순간에 내 함수를 실행한다. 스크립트를 붙이거나 초기화 코드를 넣을 때 쓴다. 훅 이름이 곧 ‘언제’다.

// 프런트에서 스타일·스크립트를 붙일 때
add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style( 'my-style', get_stylesheet_uri() );
} );

// 워드프레스가 초기화될 때 (CPT·택소노미 등록 자리)
add_action( 'init', function () {
    // register_post_type(...) 같은 것
} );

필터 예제 — 값을 가로채 바꾸기

필터는 값을 받아 변형해 반환한다. 여기서 핵심 규칙 하나 — 반드시 return해야 한다. 빠뜨리면 그 값이 통째로 사라져 사이트가 깨진다.

add_filter( 'the_content', function ( $content ) {
    if ( is_single() ) {
        $content .= '<p class="note">이 글이 도움이 됐다면 공유해 주세요.</p>';
    }
    return $content;   // 반드시 반환!
} );

우선순위와 인자 개수

add_action·add_filter의 3번째·4번째 인자가 우선순위(작을수록 먼저 실행)와 콜백이 받을 인자 개수다. 여러 코드가 같은 지점에 걸리면 이 우선순위로 순서가 정해진다. 다른 플러그인보다 나중에 손대고 싶으면 숫자를 크게 준다.

add_filter( 'the_title', 'my_title_cb', 20, 2 );  // 우선순위 20, 인자 2개
function my_title_cb( $title, $post_id ) { /* ... */ return $title; }

내 훅을 만들어 남이 끼어들게

플러그인·테마가 확장 지점을 열 때는 do_action·apply_filters로 훅을 직접 만든다. 그러면 다른 코드가 그 지점에 끼어들 수 있다. 워드프레스 생태계 전체가 이 방식으로 서로 연결된다.

do_action( 'cozlab_after_post', $post_id );          // 액션 지점 열기
$price = apply_filters( 'cozlab_price', $price, $item ); // 필터 지점 열기

떼어내기와 흔한 실수

• 훅이 안 먹음 — 등록이 그 훅이 실행되기 전에 이뤄져야 한다. 너무 늦게 add_action하면 이미 지나간 뒤라 소용없다.
• 필터에서 return 누락 — 값이 null이 되어 제목·본문이 사라진다. 가장 흔한 실수다.
• 우선순위 충돌 — 다른 코드보다 먼저/나중에 돌리려면 priority 숫자를 조절한다.
• 떼어내기 — remove_action·remove_filter는 등록할 때와 같은 함수·우선순위를 정확히 지정해야 한다. 그래서 나중에 뗄 코드는 익명 함수보다 이름 있는 함수로 걸어두는 게 낫다.

훅만 손에 익으면 코어를 안 건드리고도 워드프레스의 거의 모든 동작을 바꿀 수 있다. 실제로 이 블로그의 커스터마이징도 대부분 엔큐와 필터 몇 개로 돌아간다.

훅으로 끼어드는 법을 알았으니, 다음 편은 “애초에 무슨 글을 가져올까”를 결정하는 WP_Query와 루프를 완전 분해한다.

자주 묻는 질문 (FAQ)

액션과 필터는 뭐가 다른가요?

액션은 특정 시점에 동작을 ‘실행’하고, 필터는 값을 받아 ‘변형해 반환’합니다. 워드프레스 확장의 핵심입니다.

내 훅을 어떻게 거나요?

add_action·add_filter로 함수를 원하는 훅 이름에 연결합니다. 우선순위(priority)로 실행 순서를 조절합니다.