WordPress 플러그인 개발 완전 가이드: 제로에서 시작하여 첫 번째 기능 플러그인을 구축하는 방법

준비 작업 및 환경 설정

코드를 작성하기 시작하기 전에, 적합한 개발 환경이 필요합니다. 여기에는 로컬에 설치된 WordPress, 코드 편집기, 그리고 기본적인 지식이 포함됩니다.

먼저, 로컬 서버 환경이 준비되어 있는지 확인하세요. XAMPP, MAMP, Local by Flywheel 또는 Docker와 같은 도구를 사용하면 쉽게 로컬 서버를 설정할 수 있습니다. WordPress를 설치하고 설정하면 안전한 ‘샌드박스’ 환경이 생성되어, 온라인 웹사이트에 영향을 주지 않고 테스트를 진행할 수 있습니다.

둘째로, 효과적으로 사용할 수 있는 코드 편집기가 필요합니다. Visual Studio Code, PhpStorm, Sublime Text 모두 훌륭한 선택지입니다. 이들 편집기들은 PHP, HTML, JavaScript, CSS를 잘 지원하며, 코드 하이라이팅, 자동 완성, 디버깅 기능도 갖추고 있습니다.

추천 읽기 제로에서 원까지: WordPress 플러그인 개발 입문 및 모범 사례 가이드。

마지막으로, WordPress 플러그인의 기본 구조를 이해하는 것이 매우 중요합니다. 플러그인은 본질적으로 하나 이상의 PHP 파일로 구성되며, 이 파일들은 WordPress가 설치된 디렉터리 내에 저장됩니다. /wp-content/plugins/ 폴더 안에 있습니다. 각 플러그인은 반드시 하나의 메인 파일을 가지고 있어야 하며, 이 파일에는 해당 플러그인에 대한 헤더 정보가 포함되어 있어 WordPress 시스템에 자신을 등록하는 데 사용됩니다.

플러그인의 메인 파일 생성 및 선언 방법

플러그인을 만드는 첫 번째 단계는 메인 파일을 생성하고 올바른 헤더 주석을 추가하는 것입니다. 이 파일은 일반적으로 플러그인의 기능을 나타내는 이름으로 명명됩니다. 예를 들어, my-first-plugin.php. Please use your local environment for this. /wp-content/plugins/ 디렉터리 내에 새로운 폴더를 만들고, 그 이름을 ‘새폴더’로 지정하세요. my-first-plugin그런 다음 해당 폴더 내에 메인 파일을 생성하세요.

플러그인 헤더는 플러그인의 메타정보를 담고 있는 파일로, WordPress에 플러그인의 이름, 설명, 버전, 개발자 등의 정보를 알려줍니다. 다음은 가장 기본적인 플러그인 헤더의 예시입니다:

<?php
/**
 * Plugin Name:       我的第一个功能插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个学习 WordPress 插件开发的示例插件，用于展示基础功能。
 * Version:           1.0.0
 * Author:            你的名字
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 * Domain Path:       /languages
 */

이 파일을 저장한 후, WordPress 관리자에 로그인하고 “플러그인” 페이지로 이동하면 “My First Feature Plugin”이라는 이름의 새로운 플러그인이 플러그인 목록에 표시될 것입니다. 이제 이 플러그인을 활성화할 수 있습니다. 하지만 아직은 실제로 어떠한 기능도 없습니다.

Core Architecture: Action and Filter Hooks

WordPress의 강력한 확장 기능의 핵심은 바로 ‘후크(Hooks)’ 시스템에 있습니다. 이 시스템을 통해 개발자들은 특정 시점이나 데이터가 사용되기 전/후에 자신의 코드를 삽입할 수 있습니다. 후크에는 두 가지 종류가 있습니다: ‘액션(Action)’과 ‘필터(Filter)’입니다.

추천 읽기 WordPress 테마 개발 입문 가이드: 제로에서 시작하여 나만의 웹사이트 템플릿을 만들어보세요.。

액션 훅(Action Hook)을 사용하면 특정 WordPress 이벤트가 발생할 때 사용자 정의 함수를 실행할 수 있습니다. 예를 들어, 글이 게시될 때와 같은 경우입니다.publish_post), 메뉴를 관리자 후면에서 로드할 때(admin_menu) 또는 웹 페이지의 헤더에 스크립트를 로드할 때(wp_enqueue_scripts사용하기 add_action() 이 함수를 사용하면 자신이 작성한 함수를 액션 후크(Action Hook)에 등록할 수 있습니다.

액션 훅을 사용하여 백엔드 메뉴를 추가합니다.

가정해 보겠습니다. 우리가 플러그인에 설정 페이지를 추가하려고 합니다. 이 작업은 WordPress 관리자 페이지에서 수행할 것입니다. admin_menu 이 액션 후크를 사용하려면 해당 코드를 주 파일에 플러그인 헤더 정보 다음에 추가하세요.

// 在管理后台添加菜单
function mfp_add_admin_menu() {
    add_menu_page(
        '我的插件设置',          // 页面标题
        '我的插件',             // 菜单标题
        'manage_options',       // 所需权限
        'my-first-plugin',      // 菜单 slug
        'mfp_settings_page',    // 用于显示页面内容的回调函数
        'dashicons-admin-generic', // 图标（可选）
        80                     // 菜单位置（可选）
    );
}
add_action( 'admin_menu', 'mfp_add_admin_menu' );

// 设置页面的回调函数
function mfp_settings_page() {
    ?>
    <div class="wrap">
        <h1></h1>
        <p>제 첫 번째 플러그인의 설정 페이지에 오신 것을 환영합니다!</p>
    </div>
    &lt;?php
}

필터 후크(filter hook)를 사용하면 데이터를 수정할 수 있습니다. 이 후크는 하나의 값을 받아, 사용자가 정의한 함수에서 처리한 후, 수정된 값을 반환해야 합니다. 예를 들어, 기사의 제목을 수정하는 경우가 이에 해당합니다.the_title), 기사 내용을 수정합니다.the_content) 또는 발췌문의 길이를 수정할 수 있습니다.excerpt_length사용하기 add_filter() 이 함수는 사용자가 정의한 함수를 필터 훅에 연결하는 역할을 합니다.

필터를 사용하여 기사 내용을 수정합니다.

각 기사의 내용 끝에 자동으로 저작권 선언문을 추가하는 간단한 기능을 만들어 봅시다.

// 在文章内容后添加自定义文本
function mfp_add_copyright_to_content( $content ) {
    // 仅对网站前端的主循环中的文章生效
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $custom_text = '<p><em>저작권 고지: 본 문서의 내용은 본 사이트에 속합니다. 재발행할 경우 출처를 명시해 주시기 바랍니다.</em></p>';
        $content .= $custom_text;
    }
    return $content;
}
add_filter( 'the_content', 'mfp_add_copyright_to_content' );

구체적인 기능 구현: 단축어(셋업 코드) 및 줄여쓴 코드의 사용

쇼트코드(Shortcode)는 WordPress가 제공하는 강력한 기능으로, 사용자가 글이나 페이지에 간단한 태그를 삽입함으로써 특정 기능을 쉽게 활용할 수 있게 해줍니다. [my_shortcode]복잡한 동적 콘텐츠를 생성하거나 특정 기능을 수행하기 위해 사용됩니다. 이는 콘텐츠 제작자에게 매우 큰 유연성을 제공합니다.

간단한 단축키를 만들고 등록해 보세요.

간단한 코드를 생성하는 데에는 두 단계가 필요합니다: 첫째, 코드 처리 함수를 정의하고, 그 다음에 그 함수를 사용하는 것입니다. add_shortcode() 이 함수는 WordPress에 등록됩니다. 현재 날짜와 인사말을 표시하는 간단한 쇼트코드를 만들어 봅시다.

추천 읽기 쉽게 시작하여 전문가가 되기까지: WordPress 플러그인 개발의 완벽한 가이드와 실전 튜토리얼。

// 定义简码的处理函数
function mfp_show_greeting_shortcode( $atts ) {
    // 使用 shortcode_atts 定义默认参数，并合并用户传入的参数
    $atts = shortcode_atts(
        array(
            'name' => '访客',
        ),
        $atts,
        'greeting'
    );

// 获取当前时间
    $current_time = current_time( 'mysql' );
    $hour = date( 'H', strtotime( $current_time ) );

// 根据时间生成问候语
    if ( $hour < 12 ) {
        $greeting = '上午好';
    } elseif ( $hour < 18 ) {
        $greeting = '下午好';
    } else {
        $greeting = '晚上好';
    }

// 构建输出
    $output = &#039;<div class="mfp-greeting">'$output .= sprintf( '<p>%s, %s!</p>'`, esc_html($atts['name'])), esc_html($greeting));  
    $output .= sprintf('<p>현재 시간은: %s입니다.</p>'`, esc_html($current_time));  
    $output .= '</div>';

return $output;
}
// 注册简码，第一个参数是用户使用的标签名
add_shortcode( 'greeting', 'mfp_show_greeting_shortcode' );

이제 사용자들은 기사 편집기에서 이 기능을 사용할 수 있습니다. [greeting name="张三"]그러면 페이지에 “장삼, 안녕하세요! 현재 시간은 2026-...”이라고 표시됩니다. 매개변수를 전달하지 않으면 기본적으로 “방문자”라는 값이 사용됩니다.

고급 실습: 데이터베이스 테이블 및 옵션 페이지 생성하기

더 복잡한 플러그인의 경우 자체 데이터를 저장해야 할 수 있습니다. WordPress는 두 가지 주요 방법을 제공합니다: WordPress 옵션 API를 사용하여 간단한 키-값 쌍 데이터를 저장하거나, 구조화된 데이터를 저장하기 위해 사용자 정의 데이터베이스 테이블을 생성하는 것입니다.

옵션 API를 사용하여 설정을 저장합니다.

옵션 API는 플러그인의 설정 정보를 저장하는 데 매우 적합합니다. 우리는 이전에 만든 백엔드 설정 페이지를 개선하여 간단한 설정 내용을 저장하고 읽을 수 있도록 할 예정입니다.

먼저, 우리는 폼을 만들어야 합니다. mfp_settings_page() 함수 내에 설정을 처리하기 위한 간단한 폼을 추가하세요:

function mfp_settings_page() {
    // 检查用户是否提交了表单
    if ( isset( $_POST['mfp_submit_settings'] ) ) {
        // 安全检查：验证 nonce
        if ( ! isset( $_POST['mfp_settings_nonce'] ) || ! wp_verify_nonce( $_POST['mfp_settings_nonce'], 'mfp_save_settings' ) ) {
            wp_die( '安全验证失败！' );
        }
        // 权限检查
        if ( ! current_user_can( 'manage_options' ) ) {
            wp_die( '权限不足！' );
        }
        // 清理并保存选项
        $custom_message = sanitize_textarea_field( $_POST['custom_message'] );
        update_option( 'mfp_custom_message', $custom_message );
        echo '<div class="notice notice-success is-dismissible"><p>설정이 저장되었습니다!</p></div>';
    }

// 从数据库读取现有值
    $saved_message = get_option( 'mfp_custom_message', '这是默认的欢迎信息。' );
    ?&gt;
    <div class="wrap">
        <h1></h1>
        <form method="post" action="" data-trp-original-action="">
            <?php wp_nonce_field( 'mfp_save_settings', 'mfp_settings_nonce' ); ?>
            <table class="form-table">
                <tr>
                    <th scope="row"><label for="custom_message">커스텀 메시지:</label></th>
                    <td>
                        <textarea name="custom_message" id="custom_message" rows="5" cols="50" class="large-text"><?php echo esc_textarea( $saved_message ); ?></textarea>
                        <p class="description">이 텍스트는 `[show_message]` 단축어를 사용할 때 표시됩니다.</p>
                    </td>
                </tr>
            </table>
            <?php submit_button( '保存更改', 'primary', 'mfp_submit_settings' ); ?>
        <input type="hidden" name="trp-form-language" value="ko"/></form>
    </div>
    &lt;?php
}

그런 다음, 저장된 메시지를 표시하기 위한 새로운 단축키를 만듭니다.

function mfp_show_message_shortcode() {
    $message = get_option( 'mfp_custom_message', '这是默认的欢迎信息。' );
    return '<div class="mfp-custom-message">'`. wp_kses_post( wpautop( '$message' ) ). `'</div>'php
add_shortcode('show_message', 'mfp_show_message_shortcode');

이제 관리자는 플러그인 설정 페이지에서 메시지를 자유롭게 커스터마이징할 수 있으며, 작성자는 단지 글에서 해당 메시지를 사용하기만 하면 됩니다. [show_message] 이 메시지는 단순한 약어(코드)만으로도 출력할 수 있습니다.

플러그인이 활성화되면 사용자 정의 테이블이 생성됩니다.

주문, 로그와 같은 복잡한 관계형 데이터를 저장해야 하는 플러그인의 경우, 자체적인 데이터베이스 테이블을 생성해야 할 수 있습니다. 이 작업은 일반적으로 플러그인이 활성화될 때 수행됩니다. WordPress는 이러한 경우에 필요한 기능을 제공합니다. register_activation_hook 이것은 활성화될 때 실행될 함수를 정의하는 것입니다.

참고: 다음 코드는 예시에 불과하며, 실제 개발에서는 더 엄격한 오류 처리 메커니즘과 데이터베이스 추상화 계층이 필요합니다. $wpdb)의 사용에 관한 내용입니다.

// 插件激活时运行的函数
function mfp_create_custom_table() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'mfp_plugin_logs'; // 确保表名唯一
    $charset_collate = $wpdb->get_charset_collate();

$sql = "CREATE TABLE IF NOT EXISTS $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        log_time datetime DEFAULT CURRENT_TIMESTAMP NOT NULL,
        user_id bigint(20) DEFAULT 0,
        action varchar(255) NOT NULL,
        details text,
        PRIMARY KEY  (id)
    ) $charset_collate;";

// 引入 WordPress 升级 API，用于执行 dbDelta 函数
    require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
    dbDelta( $sql );
}
// 注册激活钩子
register_activation_hook( __FILE__, 'mfp_create_custom_table' );

요약

이 가이드를 통해 여러분은 WordPress 플러그인 개발의 핵심 프로세스를 경험하셨습니다. 환경 설정부터 플러그인 파일의 작성에 이르기까지, 액션(Action)과 필터(Filter) 핸들러를 사용하여 WordPress의 기능을 확장하는 방법을 배웠으며, 단축키(shortcode)를 통해 사용자에게 유연한 콘텐츠 삽입 기능을 제공하는 방법도 익혔습니다. 또한 옵션 API를 활용하여 설정을 저장하고 사용자 정의 데이터베이스 테이블을 생성하는 기본 방법도 학습하셨습니다. 이러한 내용들은 기능이 풍부한 플러그인을 구축하는 데 필수적인 기초입니다. 좋은 코드 구조, 보안성(예: nonce 검증, 권한 체크), 그리고 국제화(i18n) 준비는 전문적인 플러그인 개발에서 결코 간과할 수 없는 요소들입니다. 다음 단계로는 WordPress REST API, 사용자 정의 글 유형, 메타데이터(Meta Boxes), 그리고 프론트엔드 스크립트 및 스타일의 표준화된 적용을 살펴보며 더욱 복잡하고 강력한 플러그인을 개발해 나가실 수 있습니다.

자주 묻는 질문

플러그인에는 주 파일이 하나만 있어야 합니까?

그렇지 않습니다. 한 플러그인은 여러 개의 PHP 파일을 포함할 수 있습니다. 하지만 반드시 하나의 메인 파일이 있어야 하며, 이 메인 파일에는 플러그인에 대한 정보(헤더 정보)가 포함되어 있어서 WordPress가 해당 플러그인을 인식할 수 있도록 해줍니다. 복잡한 플러그인의 경우, 다양한 기능의 코드를 여러 파일에 나누어 저장한 후 메인 파일을 통해 이를 호출함으로써 더 나은 코드 관리와 모듈화를 실현합니다.

어떻게 하면 사용자가 프론트엔드 양식을 통해 제출한 데이터를 안전하게 처리할 수 있을까요?

사용자가 제출한 데이터를 처리할 때는 엄격한 검증, 정제, 그리고 이스케이피 처리가 반드시 필요합니다. 입력 데이터에 대해서는 적절한 처리 절차를 적용해야 합니다. sanitize_text_field()、sanitize_email()、sanitize_textarea_field() 등의 함수를 사용하여 데이터를 정리합니다. HTML 페이지에 출력되는 데이터에 대해서는… esc_html()、esc_attr() 또는 wp_kses_post() 에스케이프 처리를 수행해야 합니다. 또한, 크로스사이트 요청 위조를 방지하기 위해 반드시 WordPress의 nonce 메커니즘을 사용해야 하며, 해당 메커니즘을 적절히 활용해야 합니다. current_user_can() 사용자 권한을 확인하세요.

내 플러그인이 다른 플러그인과 함수명 충돌을 피하는 방법은 무엇인가요?

최선의 방법은 네임스페이스를 사용하는 것입니다(PHP 5.3 이상에서 가능) 또는 모든 함수, 클래스, 상수를 고유한 접두사 아래에 두는 것입니다. 예를 들어, 이 가이드에 있는 모든 함수는 “mfp_”(My First Plugin의 약자)로 시작합니다. 객체 지향 프로그래밍을 사용하는 경우에는 코드를 클래스 안에 담아두는 것도 이름 충돌을 해결하는 효과적인 방법입니다.

개발이 완료된 후에는 플러그인을 어떻게 배포하거나 공식 디렉터리에 등록할 수 있을까요?

플러그인을 WordPress.org 공식 플러그인 디렉터리에 제출하려면, 디렉터리 규격에 맞는 플러그인 패키지를 만들어야 합니다. 이때 일반적으로 표준화된 파일 구조가 사용됩니다. README.txt상세한 번역 지원, 호환성에 대한 명시가 포함되어 있으며, 코드는 WordPress 코딩 표준을 준수합니다. WordPress.org에서 개발자 계정을 신청한 후, SVN 도구를 사용하여 코드를 지정된 코드 저장소에 업로드해야 합니다.