[WordPress] Hook (Action / Filter)
WordPress 코드를 읽다 보면 add_action()과 add_filter()가 매우 자주 등장합니다.
둘 다 WordPress의 Hook 시스템을 사용하는 함수이지만, 실행 시점에 어떤 작업을 추가하는지와 데이터를 어떻게 다루는지에 차이가 있습니다.
Hook
Hook은 WordPress Core, Plugin, Theme의 특정 실행 지점에 다른 코드를 연결할 수 있도록 만든 구조입니다.
WordPress 공식 문서에서는 Hook을 코드의 특정 지점에서 다른 코드가 상호작용하거나 동작을 수정할 수 있도록 하는 방식으로 설명합니다.
Hook을 사용할 때는 실행할 함수를 만들고, 해당 함수를 특정 Hook에 등록합니다.
이때 등록되는 함수를 Callback이라고 부릅니다.
function example_callback() {
// 실행할 코드.
}WordPress의 Hook은 크게 Action과 Filter 두 종류로 나뉩니다.
Action
Action은 WordPress가 특정 지점에 도달했을 때 원하는 작업을 추가로 실행하는 Hook입니다.
대표적인 형태는 다음과 같습니다.
add_action( 'init', 'example_callback' );init Hook이 실행되는 시점에 example_callback() 함수가 호출됩니다.
예를 들어 관리자 메뉴를 수정할 때는 admin_menu Action을 사용할 수 있습니다.
add_action( 'admin_menu', function () {
remove_menu_page( 'tools.php' );
} );Action의 Callback은 특정 작업을 실행하는 것이 목적이며, Filter처럼 전달받은 값을 수정해서 반드시 반환할 필요는 없습니다.
Filter
Filter는 WordPress가 사용하려는 데이터를 중간에서 받아 수정한 뒤 다시 반환하는 Hook입니다.
add_filter( 'the_title', function ( $title ) {
return '[Notice] ' . $title;
} );위 코드는 게시물 제목이 출력되기 전에 $title 값을 전달받고 문자열을 추가한 뒤 수정된 값을 반환합니다.
Filter에서는 전달받은 값을 다시 반환하는 것이 중요합니다.
add_filter( 'the_title', function ( $title ) {
$title = '[Notice] ' . $title;
return $title;
} );Callback에서 값을 반환하지 않으면 이후 WordPress 코드가 사용할 데이터가 사라지거나 예상하지 못한 결과가 발생할 수 있습니다.
WordPress 공식 문서에서도 Filter Callback은 값을 받아 수정한 뒤 반환하는 구조라고 설명합니다.
Action과 Filter의 차이
| 구분 | Action | Filter |
|---|---|---|
| 목적 | 특정 시점에 작업 실행 | 데이터 수정 |
| 대표 함수 | add_action() | add_filter() |
| Callback 반환값 | 일반적으로 필요하지 않음 | 수정된 값을 반환해야 함 |
| 예시 | 메뉴 추가, 스크립트 등록, 데이터 저장 | 제목, Query 값, 출력 데이터 수정 |
코드를 읽을 때 Action은 무언가를 실행한다, Filter는 값을 받아 수정해서 돌려준다고 생각하면 구분하기 쉽습니다.
익명 함수로 작성하기
WPCodeBox 같은 곳에서는 짧은 Hook 코드를 익명 함수로 작성하는 경우가 많습니다.
add_action( 'wp_footer', function () {
echo '<p>Example</p>';
} );별도의 함수 이름을 만들지 않고 Hook 등록과 Callback 정의를 한 번에 작성한 형태입니다.
Filter도 같은 방식으로 작성할 수 있습니다.
add_filter( 'excerpt_length', function ( $length ) {
return 30;
} );짧고 한 곳에서만 사용하는 코드에는 편리하지만, Callback을 여러 곳에서 재사용하거나 제거해야 하는 경우에는 이름이 있는 함수를 사용하는 편이 관리하기 쉽습니다.
Priority
add_action()과 add_filter()의 세 번째 인수에는 Priority를 지정할 수 있습니다.
add_action( 'admin_menu', function () {
// 실행할 코드.
}, 999 );Priority의 기본값은 10입니다.
숫자가 작은 Callback이 먼저 실행되고 숫자가 큰 Callback이 나중에 실행됩니다.
예를 들어 Plugin이 Priority 10에서 관리자 메뉴를 추가한 뒤 그 메뉴를 제거해야 한다면 더 큰 Priority를 사용해 나중에 실행되도록 구성하는 경우가 있습니다.
add_action( 'admin_menu', function () {
remove_menu_page( 'plugin-menu' );
}, 999 );무조건 큰 숫자를 사용하는 것이 좋은 것은 아니고, 다른 코드보다 먼저 또는 나중에 실행해야 하는 이유가 있을 때 조정하는 값입니다.
전달받는 인수의 개수
Hook에 따라 Callback으로 하나 이상의 값이 전달될 수 있습니다.
add_action()과 add_filter()의 네 번째 인수는 Callback이 받을 인수의 개수를 지정합니다.
add_filter( 'example_filter', function ( $value, $id ) {
return $value;
}, 10, 2 );여기서 10은 Priority이고 2는 Callback이 두 개의 인수를 받는다는 의미입니다.
add_action()과 do_action()
WordPress 코드에서는 add_action()뿐 아니라 do_action()도 볼 수 있습니다.
두 함수의 역할은 다릅니다.
add_action( 'example_hook', 'example_callback' );add_action()은 Callback을 Hook에 등록합니다.
do_action( 'example_hook' );do_action()은 해당 Action Hook을 실행합니다.
Plugin이나 Theme에서 직접 확장 지점을 만들 때 do_action()을 사용할 수 있습니다.
Filter에서는 비슷한 역할을 apply_filters()가 담당합니다.
$value = apply_filters( 'example_filter', $value );즉, 다음처럼 연결됩니다.
Action
add_action() → Callback 등록
do_action() → Hook 실행
Filter
add_filter() → Callback 등록
apply_filters() → 값을 Filter에 전달하고 결과 반환정리
WordPress Hook은 Core, Plugin, Theme의 특정 실행 지점에 사용자 코드를 연결할 수 있게 해주는 구조입니다.
Action은 특정 시점에 작업을 실행할 때 사용하고, Filter는 데이터를 전달받아 수정한 뒤 반환할 때 사용합니다.
add_action( 'hook_name', 'callback' );
add_filter( 'hook_name', 'callback' );WPCodeBox에서 WordPress 코드를 작성하거나 수정할 때 Hook은 매우 자주 사용되므로 Action과 Filter의 차이, Callback, Priority, 전달 인수 정도는 기본 개념으로 익혀 두는 것이 좋습니다.