WordPress 환경에서 플러그인 개발은 기능 확장을 위한 핵심 수단입니다. 그러나 초보 개발자들은 종종 두 가지 오류를 범합니다. 하나는 모든 WordPress API를 숙지해야만 시작할 수 있다고 생각하는 것이고, 다른 하나는 기존 코드를 복사해 사용하면서도 수정 방법을 모른다는 점입니다. 사실, 효과적인 플러그인은 명확한 기능 정의, 적절한 파일 구조, 그리고 몇 가지 주요 API 활용만으로도 충분히 구현 가능합니다.

이 글에서는 실제 프로젝트 사례를 바탕으로, 처음부터 완전한 플러그인 템플릿을 만들어보겠습니다. 플러그인의 기본 구조, 설정 저장 방식, 관리자 인터페이스 통합, 다국어 지원 기능까지 실습하며, 이후에 복잡한 기능을 추가할 수 있는 기반을 마련할 것입니다.

1. WordPress 플러그인의 작동 원리 이해

1.1 플러그인의 역할과 위치

WordPress 플러그인은 하나 이상의 PHP 파일로 구성된 컬렉션으로, 워드프레스 제공의 플러그인 API를 통해 핵심 시스템과 상호작용합니다. 플러그인은 워드프레스 코어 코드를 직접 수정하지 않고, "훅(하위)" 메커니즘을 통해 특정 시점에 커스텀 로직을 삽입합니다.

이 설계의 장점은 업데이트 시에도 플러그인 기능이 유지된다는 점입니다. 또한 여러 플러그인이 동시에 설치되어도 서로 간섭 없이 독립적으로 동작합니다.

1.2 액션과 필터의 차이

워드프레스는 두 가지 유형의 훅을 제공합니다: 액션과 필터.

액션 훅은 특정 이벤트 발생 시 실행되는 함수입니다. 예를 들어 게시물 등록 전, 테마 로드 후, 페이지 하단 출력 직전 등에 등록된 콜백이 실행됩니다.

// 초기화 시점에 커스텀 함수 실행
add_action('init', 'my_plugin_setup');

function my_plugin_setup() {
    // 초기화 작업 수행
}

필터 훅은 데이터를 수정하는 데 사용됩니다. 예를 들어 게시물 제목, 본문, 요약 등을 가공하고 반환합니다.

// 게시물 제목 변경
add_filter('the_title', 'modify_post_title');

function modify_post_title($title) {
    return '※ ' . $title;
}

이 두 훅의 차이는 중요합니다: 액션은 작업을 실행하고, 필터는 데이터를 변환합니다.

2. 첫 번째 플러그인 만들기: 환경 준비 및 구조 설계

2.1 개발 환경 요구사항

코드 작성 전 아래 조건을 확인하세요.

워드프레스 설치가 올바르게 되었는지 확인하는 가장 쉬운 방법은 wp-content/plugins/ 폴더가 존재하는지 확인하는 것입니다.

2.2 플러그인 파일명과 디렉터리 구조

일관성 있는 구조는 유지보수성을 높입니다. 아래와 같은 구조를 권장합니다:

wp-content/plugins/my-sample-plugin/
├── my-sample-plugin.php          # 메인 파일
├── readme.txt                    # 설명 문서
├── includes/
│   ├── admin.php                # 관리자 관련 코드
│   └── public.php               # 공개 영역 코드
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
└── languages/                    # 다국어 파일

메인 파일 이름은 고유해야 합니다. 일반적인 단어(예: `utility.php`)는 피하고, 기능 설명 + 접두사 형식으로 지정하세요. (예: `acme-features-plugin.php`)

2.3 표준 플러그인 정보 헤더 작성

모든 플러그인은 메인 파일 상단에 다음 형식의 주석을 포함해야 합니다:

<?php
/**
 * Plugin Name: 샘플 플러그인
 * Plugin URI:  https://example.com/my-sample-plugin
 * Description: 기능 예제용 플러그인, 워드프레스 플러그인 개발의 기본 원리를 보여줍니다.
 * Version:     1.0.0
 * Author:      개발자 이름
 * Author URI:  https://example.com
 * License:     GPL v2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: my-sample-plugin
 * Domain Path: /languages
 */

각 항목의 의미는 다음과 같습니다:

• Plugin Name: 필수 항목. 플러그인 관리 페이지에 표시됨
• Text Domain: 국제화용 식별자. 디렉터리명과 일치해야 함
• Domain Path: 언어 파일 경로 지정

⚠️ 주의: 정보 헤더는 반드시 /** */ 형식이어야 하며, // 형태의 단일 줄 주석은 무시됩니다.

3. 플러그인 핵심 기능 구현

3.1 플러그인 메인 클래스 정의

객체 지향 방식으로 코드를 구성하면 유지보수가 용이하고 전역 네임스페이스 오염을 방지할 수 있습니다.

// 직접 접근 방지
if (!defined('ABSPATH')) {
    exit;
}

class My_Sample_Plugin {

    private static $instance = null;

    public static function get_instance() {
        if (null === self::$instance) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {
        $this->setup_hooks();
    }

    private function setup_hooks() {
        register_activation_hook(__FILE__, array($this, 'activate'));
        register_deactivation_hook(__FILE__, array($this, 'deactivate'));

        add_action('init', array($this, 'init'));
        add_action('admin_menu', array($this, 'add_admin_menu'));
        add_action('admin_init', array($this, 'admin_init'));
    }

    public function activate() {
        $default_settings = [
            'api_key' => '',
            'feature_enabled' => true,
            'limit_count' => 10
        ];
        add_option('my_sample_plugin_settings', $default_settings);
    }

    public function deactivate() {
        // 정리 작업 (일반적으로 옵션 삭제는 피함)
    }

    public function init() {
        $this->load_translation_domain();
    }

    public function load_translation_domain() {
        load_plugin_textdomain(
            'my-sample-plugin',
            false,
            dirname(plugin_basename(__FILE__)) . '/languages'
        );
    }
}

// 인스턴스 생성
My_Sample_Plugin::get_instance();

이러한 싱글톤 패턴은 플러그인을 한 번만 초기화하도록 보장하며, 모든 기능을 클래스 내부에 캡슐화하여 깔끔한 구조를 유지합니다.

3.2 옵션 저장: WordPress 설정 시스템 활용

설정값을 안전하게 저장하기 위해 옵션 API를 사용합니다. 관련 설정은 하나의 배열로 관리하는 것이 좋습니다.

public function admin_init() {
    register_setting(
        'my_sample_plugin_settings_group',
        'my_sample_plugin_settings',
        [$this, 'sanitize_settings']
    );

    add_settings_section(
        'my_sample_plugin_main_section',
        __('주 설정', 'my-sample-plugin'),
        [$this, 'section_callback'],
        'my-sample-plugin-settings'
    );

    add_settings_field(
        'api_key',
        __('API 키', 'my-sample-plugin'),
        [$this, 'api_key_input'],
        'my-sample-plugin-settings',
        'my_sample_plugin_main_section'
    );
}

public function sanitize_settings($input) {
    $clean = [];

    if (isset($input['api_key'])) {
        $clean['api_key'] = sanitize_text_field($input['api_key']);
    }

    if (isset($input['feature_enabled'])) {
        $clean['feature_enabled'] = (bool)$input['feature_enabled'];
    }

    if (isset($input['limit_count'])) {
        $count = absint($input['limit_count']);
        $clean['limit_count'] = ($count > 100) ? 100 : $count;
    }

    return $clean;
}

public function section_callback() {
    echo '<p>' . __('이 섹션은 플러그인의 주요 설정을 담당합니다.', 'my-sample-plugin') . '</p>';
}

public function api_key_input() {
    $settings = get_option('my_sample_plugin_settings');
    $value = $settings['api_key'] ?? '';
    echo '<input type="text" name="my_sample_plugin_settings[api_key]" value="' . esc_attr($value) . '" class="regular-text">';
    echo '<p class="description">' . __('API 키를 입력하세요.', 'my-sample-plugin') . '</p>';
}

sanitize_settings() 함수는 사용자 입력을 안전하게 처리하는 데 핵심적인 역할을 합니다.

3.3 관리자 인터페이스 생성

설정 페이지와 메뉴를 추가합니다.

public function add_admin_menu() {
    add_options_page(
        __('샘플 플러그인 설정', 'my-sample-plugin'),
        __('샘플 플러그인', 'my-sample-plugin'),
        'manage_options',
        'my-sample-plugin-settings',
        [$this, 'render_settings_page']
    );
}

public function render_settings_page() {
    if (!current_user_can('manage_options')) {
        wp_die(__('접근 권한이 없습니다.', 'my-sample-plugin'));
    }

    ?>
    <div class="wrap">
        <h1></h1>
        <form action="options.php" method="post">
            
        </form>
    </div>
    

// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);     // 에러를 debug.log에 기록
define('WP_DEBUG_DISPLAY', false); // 화면에 오류 표시 안 함

public function init() {
    $this->load_translation_domain();

    if (defined('WP_DEBUG') && WP_DEBUG) {
        add_action('wp_footer', [$this, 'debug_info']);
    }
}

public function debug_info() {
    if (current_user_can('manage_options')) {
        $settings = get_option('my_sample_plugin_settings');
        echo '';
    }
}

# Copyright (C) 2023 개발자 이름
msgid ""
msgstr ""
"Project-Id-Version: 샘플 플러그인 1.0.0\\n"
"Report-Msgid-Bugs-To: \\n"
"POT-Creation-Date: 2023-10-01 12:00+0000\\n"
"PO-Revision-Date: 2023-10-01 12:00+0000\\n"
"Last-Translator: 개발자 이름 <email@example.com>\\n"
"Language-Team: LANGUAGE <LL@li.org>\\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=UTF-8\\n"
"Content-Transfer-Encoding: 8bit\\n"
"X-Generator: Poedit 3.0.1\\n"

msgid "주 설정"
msgstr ""

msgid "API 키"
msgstr ""

msgid "API 키를 입력하세요."
msgstr ""

public function sanitize_settings($input) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log('입력: ' . print_r($input, true));
    }
    // ... 정제 로직 ...
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log('출력: ' . print_r($sanitized, true));
    }
    return $sanitized;
}

=== 샘플 플러그인 ===
Contributors: developerusername
Tags: sample, demo, tutorial
Requires at least: 5.6
Tested up to: 6.3
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

이 플러그인은 워드프레스 플러그인 개발의 기초 개념을 설명합니다.

== 설명 ==
세부 설명: 기능, 사용 목적, 특징 등을 기술합니다.

== 설치 ==
1. `/wp-content/plugins/` 폴더에 플러그인 파일 업로드
2. 워드프레스 관리자에서 플러그인 활성화
3. 설정 페이지에서 옵션 구성

== 변경 기록 ==
= 1.0.0 =
* 초기 버전 출시

// 임시 캐시 예시
public function get_cached_data() {
    $key = 'my_plugin_cached_data';
    $data = get_transient($key);

    if (false === $data) {
        $data = $this->expensive_operation();
        set_transient($key, $data, 12 * HOUR_IN_SECONDS); // 12시간 유지
    }

    return $data;
}