그누보드5의 Hook

그누보드5(이하 그누보드)에는 기능을 확장하는 방법으로 Hook을 지원한다. 워드프레스의 Hook과 유사하다. 그누보드에서는 워드프레스의 Action은 Event로, Filter는 Replace라고 부른다.

그누보드의 Hook 자세히 알아보기

Event와 Replace의 차이점

Event와 Replace의 차이점은 단 하나.

Replace는 리스너에 값을 전달하고 그것을 반환받아 이후의 동작에 사용한다.

리스너 등록

Hook이 동작할 때 실행될 함수(콜백, Listener)를 등록해두면 해당 이벤트가 발생할 때 등록한 함수를 호출하여 실행한다.

Hook 유형에 따라 add_event()와 add_replace() 두 가지 함수를 사용하고, add_replace()는 반환하는 값이 결과에 반영된다는 것 외에는 같다.

/**
 * 리스너 등록
 *
 * @param string $tag Hook 이름
 * @param callable $callback 실행될 함수, 메소드, 클래스
 * @param int $priority 실행 우선 순위
 *            기본 값인 G5_HOOK_DEFAULT_PRIORITY는 int(8)이다
 * @param int $args 콜백에 전달될 인자의 갯수
 * @return void;
 */
add_event($tag, $callback, $priority = G5_HOOK_DEFAULT_PRIORITY, $args = 0);
add_replace($tag, $callback, $priority = G5_HOOK_DEFAULT_PRIORITY, $args = 0);

함수를 리스너로 등록

현재는 그누보드 Hook에 클로저는 리스너로 등록할 수 없으며, 오류를 발생시키므로 주의해야 한다. 해결되지 않은 이슈

# 두 번째 인자에 실행할 함수명을 문자열로 지정
add_event('common_header', 'listenerCommonHeader');
function listenerCommonHeader()
{
    // ... 실행할 코드
    // Event Hook은 결과를 반환하지 않아도 된다
}

메소드를 리스너로 등록

메소드를 리스너로 등록할 때는 해당 메소드가 포함된 Class가 getInstance() 정적 메소드(static)를 포함해야한다. Hook은 getInstance()를 실행하여 객체를 반환받아 지정한 메소드를 실행한다.

# 리스너 등록
add_replace(
    'board_content_head',
    ['MyHookListenerClass', 'listenerBoardContentHead'],
    G5_HOOK_DEFAULT_PRIORITY,
    1
);

class MyHookListenerClass
{
    private static self $instance;

    public static function getInstance(): self
    {
        if (!self::$instance) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    # 실행될 메소드
    public function listenerBoardContentHead($arg1)
    {
        // ... 실행할 코드
        return $arg1;
    }
}

$arg1 = 'content';
$arg1 = run_replace('board_content_head', $arg1);

Hook이 실행될 때 마다 리스너로 등록한 메소드가 포함된 클래스의 getInstance()를 호출한다.

getInstance() 메소드가 없다면 Hook이 실행되면서 매번 새로운 인스턴스를 만든다. 2개 이상의 인스턴스가 생성될 수 있으며 다중 인스턴스로 인한 사이드 이펙트에 주의해야한다. Hook 리스너를 모아둔 개별 클래스를 따로 두는 것도 좋다.

Hook 실행

/**
 * Event Hook을 실행
 *
 * @param string $tag Hook 이름
 * @param ?mixed $args 리스너에 전달될 데이터
 * @return ?mixed
 */
run_event($tag [, ...$args]);

/**
 * Replace Hook을 실행
 *
 * @param string $tag Hook 이름
 * @param mixed $args 리스너에 전달될 데이터
 * @param ?mixed ...$args 리스너에 추가로 전달될 데이터
 *                        리스너에서 참고할 수 있는 부가 데이터를 전달할 수 있다
 * @return mixed
 */
run_replace($tag, $arg [, ...$args]);

run_replace()는 두번째 인자에 리스너가 가공할 수 있는 값을 전달해야한다. 이 전달된 값이 리스너를 거쳐 가공되거나 가공없이 그대로 반환될 수도 있다.

마치며

그누보드의 Hook 자세히 알아보기