한눈에 보기: 워드프레스의 강력한 확장 비밀은 바로 Hook 시스템입니다. Action은 “언제 실행할지”, Filter는 “무엇을 바꿀지”를 정의합니다. 이 글에서는 훅의 타이밍 이해, 필터 체인의 흐름, 충돌을 예방하는 실전 패턴까지 정리했습니다. 테마 커스터마이징부터 플러그인 제작까지, 안정적인 워드프레스 개발의 핵심 토대를 잡아봅니다.

목차
1. 타이밍 이해
2. 필터 체인
3. 충돌 예방
FAQ
출처
👉 다음 단계 학습 가이드
관련글 추천

1. 타이밍 이해

워드프레스는 수많은 이벤트 흐름으로 이루어져 있습니다. 테마가 로드되기 전, 플러그인이 불러와질 때, 본문이 출력되기 직전 등 각 시점마다 Hook이 존재합니다. 이때 Action은 “시점에 맞춰 실행할 코드”를 등록하는 도구입니다.

예를 들어, init은 워드프레스가 초기화될 때 실행됩니다. 커스텀 포스트 타입 등록은 보통 이 타이밍을 활용하죠. 반면, CSS/JS 로드는 wp_enqueue_scripts라는 별도 타이밍을 사용해야 합니다. 만약 잘못된 타이밍에 코드를 넣으면 기능이 작동하지 않거나 관리자 화면이 깨질 수 있습니다.

// 커스텀 포스트 타입 등록
add_action('init', function () {
  register_post_type('book', [
    'label' => 'Books',
    'public' => true,
    'supports' => ['title','editor','thumbnail']
  ]);
});

즉, Action Hook은 단순히 코드 삽입이 아니라, 워드프레스의 “시간표”를 이해하고 맞춰 넣는 과정입니다. 타이밍을 의식하는 습관이 곧 안정성을 보장합니다.

핵심 요약: Action Hook은 “언제”를 제어하는 도구. 타이밍을 잘못 잡으면 에러가 발생한다.

2. 필터 체인

Filter Hook은 값이 화면에 출력되거나 저장되기 전에 중간에서 가공할 수 있게 해줍니다. Action과 달리 반드시 어떤 값을 “반환(return)”해야 한다는 점이 다릅니다.

대표적인 예시는 the_content 필터입니다. 글 본문을 출력하기 전에 HTML을 수정할 수 있습니다. 광고 삽입, 안내 문구 추가, 마크업 교정 등에 활용됩니다.

// 본문 끝에 안내 문구 추가
add_filter('the_content', function ($content) {
  if (is_singular('post')) {
    $content .= '<p class="note">감사합니다. 즐거운 독서 되세요!</p>';
  }
  return $content;
});

여러 플러그인이 동일한 필터에 연결되면, 등록 순서대로 체인처럼 실행됩니다. 우선순위(priority) 숫자를 조절해 원하는 순서에介입할 수 있습니다.

// 우선순위 변경 (기본 10, 낮을수록 먼저 실행)
add_filter('the_content', 'my_filter', 5);

이 구조를 이해하면 필터 충돌을 진단하기 쉬워집니다. 예를 들어, 다른 플러그인이 본문을 치환해버렸다면, 우선순위를 변경하거나 조건문을 통해 안전하게 공존시킬 수 있습니다.

핵심 요약: Filter Hook은 “값을 바꾼다”. 여러 필터가 연결될 때는 체인 구조와 우선순위를 반드시 고려해야 한다.

3. 충돌 예방

Hook 시스템은 강력하지만, 충돌의 원인이 되기도 합니다. 초보 개발자들이 흔히 겪는 문제는 같은 훅에 함수 이름이 겹치거나, 반환값을 제대로 처리하지 않아 다른 플러그인 동작을 망가뜨리는 경우입니다.

이를 예방하는 첫 번째 습관은 함수 이름에 접두사(prefix)를 붙이는 것입니다. 예를 들어 mytheme_modify_content()처럼 네임스페이스를 의식해야 충돌을 막을 수 있습니다.

두 번째는 “반환값 필수” 원칙입니다. 필터에서 return을 누락하면, 이후 체인 전체가 잘못 동작할 수 있습니다.

// 잘못된 예시: return 없음
add_filter('the_content', function ($content) {
  $content .= '추가 문구';
});

// 올바른 예시
add_filter('the_content', function ($content) {
  $content .= '추가 문구';
  return $content;
});

마지막으로, 우선순위를 남용하지 않는 것도 중요합니다. 지나치게 낮거나 높은 숫자를 사용하면 다른 플러그인의 흐름을 무시하게 됩니다. 기본값 10을 기준으로, 꼭 필요한 경우에만 조정하는 게 안전합니다.

핵심 요약: 충돌을 예방하려면 접두사 습관, return 필수, 우선순위 최소 조정이 3대 원칙이다.

FAQ

  • Q. Action과 Filter의 차이가 뭔가요? Action은 “시점에 실행”이고, Filter는 “값을 가공 후 반환”입니다.
  • Q. 여러 개의 필터가 같은 훅에 연결되면 어떻게 되나요? 등록된 순서대로 실행되고, 각 필터가 반환한 값이 다음 필터로 전달됩니다.
  • Q. 우선순위를 조절하는 기준은 뭔가요? 기본은 10이고, 더 빨리 실행하고 싶으면 낮게, 더 나중에 실행하고 싶으면 크게 설정합니다.
  • Q. functions.php와 플러그인 중 어디에 Hook을 넣어야 하나요? 테마에 종속적인 경우 functions.php, 사이트 전체 기능은 플러그인에 두는 게 맞습니다.
  • Q. Hook 충돌이 발생하면 어떻게 디버깅하나요? 플러그인을 비활성화하며 재현 → 우선순위 확인 → 에러 로그 체크 순서로 접근하세요.
  • Q. Hook에서 DB 쿼리를 실행해도 되나요? 가능합니다. 다만 성능을 위해 캐싱이나 조건문으로 최소화하는 게 좋습니다.

출처

👉 다음 단계 학습 가이드