1장. 플러그인 제작 준비
DXCMS 플러그인은 PHP 파일 두 개(plugin.php, manifest.php)만 있으면 즉시 동작합니다. 빌드 도구나 패키지 매니저 없이 파일을 만들고 서버에 올리면 다음 요청부터 자동으로 로드됩니다.
1.1 필요한 사전 지식
- PHP 기본 — if/foreach/echo, 클로저(function($args){}), 배열
- 훅 개념 이해 — dx_add_hook() 으로 등록 → dx_run_hook() 발동 시 실행
- DXCMS 구조 — plugins/ 폴더 위치, dx_config() 함수, dx_base_url() 함수
1.2 플러그인 폴더 생성
- plugins/ 폴더 아래에 새 폴더 생성
- 폴더명 규칙: 영소문자•숫자•하이픈•언더스코어만 사용 (예: my-plugin, slack-notifier)
- 폴더명이 플러그인의 고유 ID가 됩니다 — 중복 없이 의미있는 이름 선택
plugins/
my-plugin/ ← 새 폴더 생성
plugin.php ← 생성 (메인 실행 파일)
manifest.php ← 생성 (메타 정보)
💡 개발 팁
example-plugin 폴더를 그대로 복사해서 시작하면 가장 빠릅니다.
결제 플러그인은 custom-payment-template을 복사하여 수정하세요.
DX_DEBUG=true를 설정하면 PHP 오류가 화면에 표시됩니다.
2장. manifest.php 작성
manifest.php는 플러그인의 신분증입니다. 관리자 → 플러그인 목록에 표시될 이름•버전•설명이 여기서 결정됩니다. 마켓에 공유할 때도 이 파일의 정보가 자동으로 사용됩니다.
2.1 manifest.php 전체 형식
<?php
// plugins/my-plugin/manifest.php
// 이 파일은 배열을 return 합니다.
return array(
"name" => "My Plugin", // 관리자 목록 표시 이름 ★필수
"version" => "1.0.0", // 버전 ★필수
"description" => "플러그인 기능 설명", // 관리자 목록 설명
"author" => "개발자명",
"author_url" => "https://mysite.com",
"type" => "utility", // 플러그인 분류 타입
"min_version" => "8.0.0", // 최소 DXCMS 버전
"tags" => "알림,슬랙,연동", // 쉼표 구분 검색 태그
"category" => "utility", // 카테고리
"homepage" => "https://...", // 홈페이지 URL
"license" => "MIT",
);
2.2 type 필드 선택 기준
| type 값 |
사용 시점 |
| "editor" |
글쓰기 에디터를 제공하는 플러그인 (CKEditor, TinyMCE 등) |
| "payment" |
결제 PG사 연동 플러그인 (토스, 카카오페이 등) |
| "captcha" |
CAPTCHA 서비스 연동 (reCAPTCHA, hCaptcha) |
| "sms" |
SMS 발송 서비스 연동 |
| "socket" |
WebSocket 실시간 기능 |
| "social_login" |
소셜 로그인 연동 |
| "utility" |
기능 추가, 알림, 분석 등 기타 모든 플러그인 |
3장. plugin.php 단계별 구현
3.1 파일 시작 — 보안 체크
모든 plugin.php의 첫 줄은 반드시 직접 접근 차단 코드여야 합니다.
<?php
/**
* My Plugin — DesignOneX CMS
* 플러그인 설명을 여기에 작성하세요.
*/
// 직접 접근 차단 — 반드시 첫 번째 실행 코드로 작성
if (!defined("DX_CMS")) exit("Direct access not allowed.");
3.2 dx_register_plugin() — 타입 등록
에디터•결제•캡챠처럼 관리자가 선택할 수 있는 타입에 속한 플러그인만 이 함수를 호출합니다. 단순 기능 추가 플러그인은 이 단계를 생략해도 됩니다.
// PluginRegistry에 등록 — 관리자 드롭다운에 표시됨
dx_register_plugin(array(
"id" => "my-plugin", // 폴더명과 일치 권장
"type" => "editor", // PluginRegistry 타입
"name" => "My Plugin", // 드롭다운 표시 이름
"version" => "1.0.0",
"description" => "설명",
"author" => "개발자명",
"priority" => 10, // 드롭다운 정렬 (낮을수록 위)
// 관리자 설정 필드 정의
"settings" => array(
"api_key" => array(
"label" => "API 키",
"type" => "text",
"required" => true,
"placeholder" => "sk_live_...",
"description" => "서비스 대시보드에서 발급",
"default" => "",
),
),
// 관리자 화면 사용 안내
"usage_guide" => array(
"what" => "이 플러그인이 하는 일",
"steps" => array(
"1. 관리자 > 플러그인 > 모듈 설정에서 선택",
"2. API 키를 입력하고 저장",
),
"note" => "테스트 키는 test_으로 시작합니다.",
),
));
3.3 활성화 조건 체크 패턴
editor•payment•captcha 타입은 관리자가 하나를 선택합니다. 내 플러그인이 선택된 경우에만 훅을 등록해야 무거운 기능이 불필요하게 실행되지 않습니다.
// ── 패턴 1: 활성화 체크 후 return (가장 일반적) ──────────
if (dx_active_plugin("editor") !== "my-plugin") return;
// 이 줄 이후는 내 플러그인이 활성화된 경우만 실행
// ── 패턴 2: 콜백 내부에서 체크 ──────────────────────────
dx_add_hook("dx_editor_render", function($args) {
if (dx_active_plugin("editor") !== "my-plugin") return;
// 에디터 출력
});
// ── 패턴 3: 설정값 체크 ─────────────────────────────────
$enabled = dx_config("plugin_my-plugin_enabled", "1");
if ($enabled !== "1") return;
3.4 훅 등록 — 실제 기능 구현
dx_add_hook()으로 훅 포인트에 콜백을 등록합니다. 콜백은 클로저, 함수명 문자열, 배열([객체, 메서드]) 모두 지원합니다.
// ── 클로저 (가장 일반적) ─────────────────────────────────
dx_add_hook("dx_head", function($ctx) {
echo '<link rel="stylesheet" href="' . dx_base_url("plugins/my-plugin/assets/style.css") . '">';
}, 10);
// ── 전역 함수명 문자열 ───────────────────────────────────
function my_plugin_head($ctx) {
echo '<link rel="stylesheet" href="...">';
}
dx_add_hook("dx_head", "my_plugin_head", 10);
// ── 클래스 메서드 배열 ───────────────────────────────────
class MyPlugin {
public function onHead($ctx) { ... }
}
$plugin = new MyPlugin();
dx_add_hook("dx_head", array($plugin, "onHead"), 10);
// ── 정적 메서드 ──────────────────────────────────────────
dx_add_hook("dx_head", array("MyPlugin", "staticOnHead"), 10);
4장. settings — 관리자 설정 필드 완전 가이드
dx_register_plugin()의 settings 배열에 필드를 정의하면 관리자 → 플러그인 설정 UI가 자동으로 생성됩니다. 설정값은 settings 테이블에 plugin_{id}_{key} 형식으로 저장됩니다.
4.1 settings 필드 완전 정의
"settings" => array(
// ── text: 단일 줄 텍스트 입력 ────────────────────────
"api_key" => array(
"label" => "API 키", // 입력란 위에 표시되는 레이블
"type" => "text",
"required" => true, // true면 빈값 경고 표시
"placeholder" => "sk_live_...", // 입력란 힌트
"description" => "대시보드에서 발급", // 레이블 아래 회색 설명
"default" => "", // 저장값 없을 때 기본값
),
// ── password: 비밀번호 입력 (마스킹) ─────────────────
"secret_key" => array(
"label" => "시크릿 키",
"type" => "password",
),
// ── select: 드롭다운 선택 ────────────────────────────
"mode" => array(
"label" => "운영 모드",
"type" => "select",
"options" => array(
"test" => "테스트 (실결제 없음)",
"live" => "실서비스",
),
"default" => "test",
),
// ── textarea: 여러 줄 텍스트 ─────────────────────────
"webhook_urls" => array(
"label" => "웹훅 URL 목록",
"type" => "textarea",
"placeholder" => "URL을 한 줄에 하나씩 입력",
),
// ── checkbox_group: 다중 체크박스 ────────────────────
// 선택된 값들이 쉼표 구분 문자열로 저장됨
"methods" => array(
"label" => "지원 결제 수단",
"type" => "checkbox_group",
"options" => array(
"card" => "신용카드",
"bank" => "계좌이체",
"phone" => "휴대폰",
),
"default" => "card,bank",
),
),
4.2 settings 값 읽기
// plugin_{플러그인ID}_{설정키} 형식으로 저장됨
$apiKey = dx_config("plugin_my-plugin_api_key", ""); // 기본값 ""
$mode = dx_config("plugin_my-plugin_mode", "test"); // 기본값 "test"
$enabled = dx_config("plugin_my-plugin_enabled", "1") === "1"; // bool
// checkbox_group: 쉼표 구분 문자열로 저장됨
$methodsStr = dx_config("plugin_my-plugin_methods", "card");
$methods = array_filter(array_map("trim", explode(",", $methodsStr)));
// 결과: ["card", "bank"]
// 결제 플러그인 전용 단축 함수 (dx-payment-helper.php)
// require_once dirname(__FILE__) . "/../dx-payment-helper.php"; 후 사용
$apiKey = dx_pay_cfg("my-plugin", "api_key");
// 내부적으로 dx_config("plugin_my-plugin_api_key") 와 동일
⚠️ 보안 주의
password 타입의 시크릿 키는 반드시 서버 측 코드에서만 사용하세요.
클라이언트(JavaScript)로 절대 전달하면 안 됩니다.
dx_config()는 서버 PHP에서만 호출하므로 안전합니다
5장. 전체 훅 포인트 레퍼런스
5.1 레이아웃 훅 (모든 페이지)
| 훅 이름 |
위치 및 전달 인자 |
| dx_head |
<head> 안쪽. CSS·meta·JSON-LD 삽입. $context 배열 전달 |
| dx_top |
body 최상단 (dx_hook_top). $context 전달 |
| dx_{type}_top |
페이지 타입별 top. 예: dx_board_top, dx_auth_top |
| dx_middle |
콘텐츠 영역 중간 (dx_hook_middle). $context 전달 |
| dx_{type}_middle |
페이지 타입별 middle. 예: dx_board_middle |
| dx_bottom |
body 하단 (dx_hook_bottom). $context 전달 |
| dx_{type}_bottom |
페이지 타입별 bottom |
| dx_footer_scripts |
</body> 직전. JS 파일 삽입용 |
| dx_body_bottom |
</body> 최하단. 분석·채팅 위젯 등 |
5.2 게시판 훅
| 훅 이름 |
발동 시점 및 인자 |
| dx_board_before |
핸들러 진입. board, action, skin, id 전달 |
| dx_board_list_context |
목록 $ctx 확정 직전. context 참조(&)로 전달 → 변경 가능 |
| dx_board_view_context |
상세 $ctx 확정 직전. context 참조(&)로 전달 |
| dx_board_write_context |
글쓰기 $ctx 확정 직전 |
| dx_board_before_save |
글 저장 직전. data 참조(&) 전달 → 커스텀 필드 추가 가능 |
| dx_after_write |
글 저장 완료 후. post_id, board, data |
| dx_board_after_save |
저장 후. redirect URL 변경 가능 |
| dx_board_before_delete |
글 삭제 직전. post, board_key |
| dx_board_after_delete |
글 삭제 완료 후. post_id, board_key |
| dx_after_comment |
댓글 등록 후. comment_id, post_id, board |
| dx_board_after |
핸들러 처리 완료 후 |
5.3 회원 훅
| 훅 이름 |
발동 시점 및 인자 |
| dx_after_login |
로그인 성공 후. user 배열 전달 |
| dx_after_logout |
로그아웃 후. user 배열 전달 |
| dx_after_register |
회원가입 완료 후. user_id, data 전달 |
5.4 포인트•좋아요•친구 훅
| 훅 이름 |
발동 시점 및 인자 |
| dx_after_point |
포인트 변동 후. member_id, type, point, balance |
| dx_levelup |
회원 레벨 상승 시. member_id, old_level, new_level |
| dx_after_like |
좋아요 등록 후. post_id, owner_id |
| dx_add_friend |
친구 추가 후. member_id, target_id |
5.5 에디터•결제•캡챠•관리자 훅
| 훅 이름 |
발동 시점 및 인자 |
| dx_editor_render |
에디터 HTML 출력. name, value, options, editor |
| dx_editor_init |
dx_render_editor() 내부 브릿지. 에디터 실행 진입점 |
| dx_payment_request |
dx_request_payment() 호출 시. 결제창 HTML/JS 출력 |
| dx_captcha_drivers |
CAPTCHA 드라이버 등록 시 |
| dx_sms_drivers |
SMS 드라이버 등록 시 |
| dx_admin_dashboard_widgets |
관리자 대시보드 위젯 삽입 |
| dx_shop_after_purchase |
쇼핑몰 결제 완료 후. order 정보 |
5.6 Filter 훅 — 값 변형
Filter 훅은 값을 받아 가공 후 반환하는 방식입니다. 동일 필터에 여러 플러그인이 연결되면 체인으로 처리됩니다.
// 필터 등록 — 글 내용에 광고 자동 삽입 예시
dx_add_filter("post_content", function($content, $args) {
$adHtml = '<div class="ad-box">광고</div>';
return $content . $adHtml;
}, 10);
// 게시글 제목 필터 등록
dx_add_filter("post_title", function($title, $args) {
// 금칙어 필터
return str_replace("금칙어", "***", $title);
});
// 필터 실행 — CMS 또는 테마에서
$content = dx_apply_filter("post_content", $rawContent, $args);
6장. 에디터 플러그인 제작
에디터 플러그인은 게시글•댓글 글쓰기 폼에 WYSIWYG 에디터를 제공합니다. 관리자가 에디터 드롭다운에서 선택하면 dx_render_editor() 호출 시 내 에디터가 렌더링됩니다.
6.1 에디터 렌더링 흐름
// 글쓰기 폼(write.php)에서
dx_render_editor("content", $existingContent, ["board"=>$board]);
↓
// dx_render_editor() 내부에서
$editorId = dx_active_plugin("editor"); // "my-editor"
dx_run_hook("dx_editor_render", ["name"=>$name,"value"=>$value,...]);
↓
// 내 플러그인의 dx_editor_render 훅 콜백 실행
6.2 에디터 플러그인 전체 구현
<?php
// plugins/my-editor/plugin.php
if (!defined("DX_CMS")) exit;
// 1. editor 타입으로 등록
dx_register_plugin(array(
"id" => "my-editor",
"type" => "editor",
"name" => "My Editor",
"version" => "1.0.0",
"settings" => array(
"height" => array(
"label" => "에디터 높이 (px)",
"type" => "text",
"default" => "400",
),
"use_comment_editor" => array(
"label" => "댓글에도 에디터 사용",
"type" => "select",
"options" => array("1"=>"사용","0"=>"사용 안 함"),
"default" => "1",
),
),
));
// 2. 내 에디터가 활성화된 경우만 실행
if (dx_active_plugin("editor") !== "my-editor") return;
// 3. 에디터 렌더 훅 등록
dx_add_hook("dx_editor_render", function($args) {
$name = isset($args["name"]) ? $args["name"] : "content";
$value = isset($args["value"]) ? $args["value"] : "";
$height = (int)dx_config("plugin_my-editor_height", "400");
// CDN 중복 로드 방지
static $loaded = false;
if (!$loaded) {
$loaded = true;
echo '<script src="https://cdn.example.com/my-editor.min.js"></script>' . " ";
}
// textarea + 에디터 초기화
$safeId = "editor_" . preg_replace("/[^a-zA-Z0-9_]/", "_", $name);
echo '<textarea id="' . $safeId . '" name="' . htmlspecialchars($name, ENT_QUOTES) . '"'
. ' style="display:none">' . htmlspecialchars($value, ENT_QUOTES, "UTF-8") . '</textarea>';
echo '<div id="' . $safeId . '_container" style="height:' . $height . 'px"></div>';
echo '<script>'
. 'MyEditor.create(document.getElementById("' . $safeId . '_container"), {'
. ' initialData: ' . json_encode($value) . ','
. ' height: ' . $height
. '}).then(editor => {'
. ' editor.model.document.on("change:data", () => {'
. ' document.getElementById("' . $safeId . '").value = editor.getData();'
. ' });'
. '});';
echo '</script>';
}, 10);
💡 use_comment_editor 설정의 의미
"use_comment_editor"=>"1" 로 저장하면 댓글 폼에도 에디터가 표시됩니다.
이 값은 dx_editor_use_comment() 함수가 자동으로 읽습니다:
$useEditor = dx_editor_use_comment(); // bool
설정 키 형식: plugin_{에디터ID}_use_comment_editor
7장. 결제 플러그인 제작
결제 플러그인은 dx_request_payment() 호출 시 결제창 HTML/JS를 출력하고, 결제 완료 후 서버에서 금액을 검증하는 함수를 제공합니다. dx-payment-helper.php에 cURL/HTTP 유틸리티가 내장되어 있습니다.
7.1 결제 흐름
[고객 "결제하기" 버튼 클릭]
↓
dx_request_payment(array(
"order_id" => "order_123",
"amount" => 29000,
"product_name" => "DXCMS 라이선스",
"buyer_name" => "홍길동",
"buyer_email" => "user@example.com",
"return_url" => dx_base_url("payment/success"),
"fail_url" => dx_base_url("payment/fail"),
))
↓ dx_payment_request 훅 발동
[내 플러그인 → PG사 결제창 HTML/JS 출력]
↓ 고객이 결제 완료
[PG사 → return_url 리다이렉트 (PaymentKey, orderId, amount)]
↓ return_url 핸들러 (pages/ 또는 boards/)에서
$result = my_pg_confirm($_GET); // 서버 검증
if ($result["success"]) {
// 주문 DB 업데이트, 포인트 지급 등
}
7.2 결제 플러그인 전체 구현
<?php
// plugins/my-pg-payment/plugin.php
if (!defined("DX_CMS")) exit;
// dx-payment-helper.php 로드 (HTTP 요청 유틸)
require_once dirname(__FILE__) . "/../dx-payment-helper.php";
// 1. payment 타입으로 등록
dx_register_plugin(array(
"id" => "my-pg-payment",
"type" => "payment",
"name" => "나의 결제사",
"version" => "1.0.0",
"settings" => array(
"client_key" => array(
"label" => "클라이언트 키", "type" => "text", "required" => true,
),
"secret_key" => array(
"label" => "시크릿 키", "type" => "password", "required" => true,
),
"mode" => array(
"label" => "운영 모드", "type" => "select",
"options" => array("test"=>"테스트","live"=>"실서비스"),
"default" => "test",
),
),
));
// 2. 활성화 체크 — 내 플러그인이 아니면 종료
if (dx_active_plugin("payment") !== "my-pg-payment") return;
// 3. 결제창 훅 등록
dx_add_hook("dx_payment_request", function($data) {
$clientKey = dx_pay_cfg("my-pg-payment", "client_key");
$mode = dx_pay_cfg("my-pg-payment", "mode", "test");
if (!$clientKey) {
dx_payment_error_html("결제 키가 설정되지 않았습니다.");
return;
}
$orderId = isset($data["order_id"]) ? $data["order_id"] : dx_payment_order_id("MY");
$amount = isset($data["amount"]) ? (int)$data["amount"] : 0;
$productName = isset($data["product_name"]) ? $data["product_name"] : "결제";
$returnUrl = isset($data["return_url"]) ? $data["return_url"] : dx_base_url("payment/success");
$failUrl = isset($data["fail_url"]) ? $data["fail_url"] : dx_base_url("payment/fail");
dx_payment_wrap_open("나의 결제사"); // 결제창 래퍼 열기
?>
<script src="https://your-pg.com/sdk.js"></script>
<script>
YourPG.request({
clientKey: <?php echo json_encode($clientKey); ?>,
orderId: <?php echo json_encode($orderId); ?>,
amount: <?php echo $amount; ?>,
orderName: <?php echo json_encode($productName); ?>,
successUrl: <?php echo json_encode($returnUrl); ?>,
failUrl: <?php echo json_encode($failUrl); ?>,
});
</script>
<?php
dx_payment_wrap_close(); // 결제창 래퍼 닫기
});
// 4. 서버 검증 함수
function my_pg_confirm(array $params) {
$secretKey = dx_pay_cfg("my-pg-payment", "secret_key");
$mode = dx_pay_cfg("my-pg-payment", "mode", "test");
$paymentKey = isset($params["paymentKey"]) ? $params["paymentKey"] : "";
$orderId = isset($params["orderId"]) ? $params["orderId"] : "";
$amount = isset($params["amount"]) ? (int)$params["amount"]: 0;
if (!$paymentKey || !$orderId || $amount <= 0) {
return dx_payment_fail("필수 파라미터 누락");
}
// PG사 API 서버 검증
$apiUrl = $mode === "live"
? "https://api.your-pg.com/v1/payments/confirm"
: "https://test-api.your-pg.com/v1/payments/confirm";
$resp = dx_payment_http_post(
$apiUrl,
json_encode(array(
"paymentKey" => $paymentKey,
"orderId" => $orderId,
"amount" => $amount,
)),
array("Authorization: Basic " . base64_encode($secretKey . ":"))
);
$result = json_decode($resp, true);
if (!isset($result["orderId"])) {
$msg = isset($result["message"]) ? $result["message"] : "결제 검증 실패";
return dx_payment_fail($msg);
}
return dx_payment_ok(array(
"tid" => isset($result["paymentKey"]) ? $result["paymentKey"] : $paymentKey,
"order_id" => $orderId,
"amount" => $amount,
"raw" => $result,
));
}
7.3 dx-payment-helper.php 제공 함수
| 함수 |
설명 |
| dx_payment_http_post($url, $body, $headers) |
cURL 우선 POST 요청. file_get_contents 폴백 |
| dx_payment_http_get($url, $headers) |
cURL 우선 GET 요청 |
| dx_pay_cfg($pluginId, $key, $default="") |
dx_config("plugin_{id}_{key}") 단축 함수 |
| dx_payment_order_id($prefix="DX") |
고유 주문 ID 생성 (prefix+날짜+밀리초) |
| dx_payment_wrap_open($title) |
결제창 래퍼 div 열기 HTML 출력 |
| dx_payment_wrap_close() |
결제창 래퍼 닫기 HTML 출력 |
| dx_payment_ok($data) |
성공 배열 반환: ["success"=>true, "tid"=>..., ...] |
| dx_payment_fail($message) |
실패 배열 반환: ["success"=>false, "message"=>...] |
| dx_payment_error_html($msg) |
오류 메시지 HTML 출력 |
8장. 유틸리티 플러그인 실전 제작
8.1 성능 디버그 플러그인
DX_DEBUG 모드일 때 화면 우측 하단에 실행 시간과 DB 쿼리 수를 표시합니다.
plugin.php
<?php
if (!defined("DX_CMS")) exit;
if (defined("DX_DEBUG") && DX_DEBUG) {
dx_add_hook("dx_body_bottom", function() {
$time = round((microtime(true) - DX_START_TIME) * 1000, 2);
$qc = Database::getInstance()->getQueryCount();
echo '<div style="position:fixed;bottom:10px;right:10px;'
. 'background:rgba(15,23,42,.85);color:#fff;padding:8px 14px;'
. 'border-radius:10px;font-size:11px;z-index:9999;font-family:monospace">'
. '⚡ ' . $time . 'ms | DB: ' . $qc . '쿼리'
. '</div>';
}, 999);
}
8.2 글 등록 시 이메일 알림 플러그인
새 게시글이 등록될 때 관리자 이메일로 알림을 발송합니다.
<?php
if (!defined("DX_CMS")) exit;
dx_register_plugin(array(
"id" => "email-notifier",
"type" => "utility",
"name" => "이메일 알림",
"version" => "1.0.0",
"settings" => array(
"notify_email" => array(
"label" => "알림 받을 이메일",
"type" => "text",
"placeholder" => "admin@example.com",
),
"board_keys" => array(
"label" => "알림 게시판 (비우면 전체, 쉼표 구분)",
"type" => "text",
"placeholder" => "notice,free",
),
),
));
dx_add_hook("dx_after_write", function($args) {
$notifyEmail = dx_config("plugin_email-notifier_notify_email", "");
if (!$notifyEmail) return;
// 게시판 필터
$boardKeysStr = dx_config("plugin_email-notifier_board_keys", "");
if ($boardKeysStr) {
$keys = array_map("trim", explode(",", $boardKeysStr));
$boardKey = isset($args["board"]["board_key"]) ? $args["board"]["board_key"] : "";
if (!in_array($boardKey, $keys)) return;
}
$postId = isset($args["post_id"]) ? $args["post_id"] : "";
$board = isset($args["board"]) ? $args["board"] : array();
$data = isset($args["data"]) ? $args["data"] : array();
$title = isset($data["title"]) ? $data["title"] : "(제목 없음)";
$boardName = isset($board["board_name"]) ? $board["board_name"] : "";
$boardKey = isset($board["board_key"]) ? $board["board_key"] : "";
$postUrl = dx_base_url($boardKey . "/view/" . $postId);
$subject = "[새 글] [{$boardName}] {$title}";
$message = "새 게시글이 등록되었습니다. "
. "제목: {$title} "
. "게시판: {$boardName} "
. "URL: {$postUrl}";
@mail($notifyEmail, $subject, $message,
"From: noreply@" . (isset($_SERVER["HTTP_HOST"]) ? $_SERVER["HTTP_HOST"] : "localhost"));
}, 10);
8.3 글쓰기 커스텀 필드 플러그인
게시글에 "출처 URL" 커스텀 필드를 추가하고, 뷰 페이지에 표시하는 예시입니다. dx_board_before_save 훅과 dx_board_view_context 훅을 함께 활용합니다.
plugin.php
<?php
if (!defined("DX_CMS")) exit;
dx_register_plugin(array(
"id" => "source-url-field",
"type" => "utility",
"name" => "출처 URL 필드",
"version" => "1.0.0",
));
// 1. 글쓰기 폼에 필드 추가 (write_context 훅)
dx_add_hook("dx_board_write_context", function($args) {
// $args["context"] 참조로 접근 가능
// 글쓰기 폼 하단에 필드 출력은 dx_bottom 훅 활용
});
// 2. 글쓰기 폼 하단에 HTML 필드 주입
dx_add_hook("dx_board_bottom", function($ctx) {
if (!isset($ctx["type"]) || ($ctx["type"] !== "write" && $ctx["type"] !== "edit")) return;
$editPost = isset($ctx["editPost"]) ? $ctx["editPost"] : array();
$curVal = isset($editPost["source_url"]) ? $editPost["source_url"] : "";
?>
<div style="margin-top:12px">
<label style="display:block;font-size:.8rem;font-weight:700;color:#64748b;margin-bottom:6px">출처 URL</label>
<input type="url" name="source_url"
value="<?php echo htmlspecialchars($curVal, ENT_QUOTES, "UTF-8"); ?>"
placeholder="https://..."
style="width:100%;padding:9px 14px;border:1px solid #e2e8f0;border-radius:10px;font-size:.875rem">
</div>
<?php
});
// 3. 저장 전 데이터에 추가
// ※ dx_board_before_save의 data는 실제 DB 컬럼이어야 함
// posts 테이블에 source_url 컬럼이 없으면 settings나 별도 테이블 사용
// 여기서는 content에 메타 태그로 포함하는 방식 예시:
dx_add_hook("dx_board_before_save", function($args) {
$sourceUrl = isset($_POST["source_url"]) ? trim($_POST["source_url"]) : "";
if (!$sourceUrl) return;
// URL 검증
if (!filter_var($sourceUrl, FILTER_VALIDATE_URL)) return;
// content에 출처 정보 메타 추가 (data 참조 변경)
$args["data"]["source_url"] = $sourceUrl; // posts 테이블에 컬럼 필요
});
// 4. 뷰 페이지에 출처 URL 표시
dx_add_hook("dx_board_view_context", function($args) {
// $args["context"]["post"]에 source_url이 있으면 뷰에서 출력
// 실제 표시는 테마의 board/view.php에서 $post["source_url"] 사용
});
9장. DxContainer (DI 컨테이너) 활용
DxContainer는 라라벨 스타일 DI 컨테이너입니다. 플러그인이 제공하는 서비스(SMS 발송기, 이메일 클라이언트 등)를 등록하면 다른 플러그인이나 테마에서 가져다 쓸 수 있습니다.
9.1 서비스 등록 (plugin.php에서)
// 싱글턴 등록 — 한 번 생성 후 재사용
dx_app()->singleton("sms", function() {
return new MySmsSender(
dx_config("plugin_my-sms_api_key"),
dx_config("plugin_my-sms_sender") // 발신번호
);
});
// 팩토리 등록 — 호출마다 새 인스턴스
dx_app()->bind("mailer", function() {
return new MyMailer(dx_config("smtp_host"));
});
9.2 서비스 사용 (다른 곳에서)
// 훅 콜백, 테마 파일, boards handler 등 어디서든
$sms = dx_make("sms");
$sms->send("01012345678", "인증번호: 123456");
// dx_make() = dx_app()->make() 단축 함수
$mailer = dx_make("mailer");
$mailer->send("user@example.com", "제목", "내용");
// 등록 여부 확인
if (dx_app()->bound("sms")) {
$sms = dx_make("sms");
}
10장. DxRouter — 플러그인 전용 URL 등록
플러그인이 독립 URL(예: /my-plugin/dashboard, /api/my-plugin/data)을 처리해야 할 때 DxRouter를 사용합니다. 기존 파일 기반 라우팅보다 깔끔하게 URL을 관리할 수 있습니다.
10.1 기본 라우트 등록
// plugin.php에서
// 단순 클로저 라우트
DxRouter::get("/my-plugin/dashboard", function() {
if (!dx_is_login()) dx_redirect(dx_base_url("auth/login"));
$db = Database::getInstance();
$data = $db->rows("SELECT * FROM ...");
// 렌더링
$dxth = DxTheme::getInstance();
ob_start();
include __DIR__ . "/views/dashboard.php";
$dx_content = ob_get_clean();
$layoutFile = $dxth->resolve("layout/main.php");
if ($layoutFile) require $layoutFile;
else echo $dx_content;
})->middleware("auth");
// POST 라우트
DxRouter::post("/api/my-plugin/save", function() {
dx_csrf_check();
$data = dx_post("data", "");
dx_json(array("success" => true, "message" => "저장됨"));
})->middleware(array("auth", "csrf"));
// 그룹 라우트
DxRouter::group(array("prefix" => "/my-plugin", "middleware" => "auth"), function() {
DxRouter::get("/list", function() { /* 목록 */ });
DxRouter::get("/view", function() { /* 상세 */ });
DxRouter::post("/save", function() { /* 저장 */ })->middleware("csrf");
});
10.2 미들웨어 옵션
| 미들웨어 |
동작 |
| "auth" |
비로그인 시 /auth/login 으로 리다이렉트 |
| "admin" |
비관리자 시 403 오류 |
| "csrf" |
POST 요청 시 CSRF 토큰 검증. 실패 시 403 |
| 배열로 여러 개 |
->middleware(["auth", "csrf"]) 순서대로 모두 실행 |
11장. 관리자 패널•위젯 추가
11.1 관리자 대시보드 위젯 추가
dx_admin_dashboard_widgets 훅으로 관리자 대시보드에 위젯을 삽입할 수 있습니다.
// plugin.php에서
dx_add_hook("dx_admin_dashboard_widgets", function() {
$db = Database::getInstance();
$count = (int)$db->value("SELECT COUNT(*) FROM `{$db->table("posts")}`");
?>
<div style="background:#fff;border:1px solid #e2e8f0;border-radius:12px;padding:20px;">
<h3 style="margin:0 0 8px;font-size:.9rem;font-weight:700">내 플러그인 통계</h3>
<p style="margin:0;font-size:1.5rem;font-weight:800;color:#1a73e8">
<?php echo number_format($count); ?>
<span style="font-size:.8rem;color:#64748b">총 게시글</span>
</p>
</div>
<?php
});
11.2 관리자 전용 설정 페이지 (DxRouter 활용)
// plugin.php에서
DxRouter::get("/admin/my-plugin/settings", function() {
if (!dx_is_admin()) { http_response_code(403); exit; }
ob_start();
include __DIR__ . "/admin/settings.php"; // admin/settings.php
$dx_content = ob_get_clean();
$layout = DxTheme::getInstance()->resolve("layout/main.php");
if ($layout) require $layout;
else echo $dx_content;
})->middleware("admin");
DxRouter::post("/admin/my-plugin/settings", function() {
if (!dx_is_admin()) { dx_json(array("success"=>false),403); }
dx_csrf_check();
$db = Database::getInstance();
$val = dx_post("some_setting", "");
$db->query(
"INSERT INTO `{$db->table("settings")}` (setting_key,setting_value,updated_at)
VALUES (?,?,NOW()) ON DUPLICATE KEY UPDATE setting_value=?,updated_at=NOW()",
array("plugin_my-plugin_some_setting", $val, $val)
);
if (class_exists("DxCache")) DxCache::flush();
dx_json(array("success"=>true));
})->middleware(array("admin","csrf"));
12장. 디버깅 및 배포 체크리스트
12.1 개발 시 디버깅 방법
// config.php에서 디버그 모드 활성화
define("DX_DEBUG", true); // 오류가 화면에 표시됨
// 훅 실행 로그 확인 (DX_DEBUG=true 시)
$executed = HookManager::getInstance()->getExecuted();
error_log(print_r($executed, true));
// 등록된 훅 목록 확인
$allHooks = HookManager::getInstance()->getAll();
// 플러그인 설정값 확인
var_dump(dx_config("plugin_my-plugin_api_key"));
// 오류는 data/error.log 에 기록됨
dx_log("내 플러그인 초기화", "debug"); // info/debug: 기록 안 됨
dx_log("설정 오류", "error"); // error: data/error.log 기록
12.2 자주 발생하는 문제
| 증상 |
원인 및 해결 |
| 플러그인이 목록에 안 보임 |
manifest.php 없거나 return array() 형식 오류. PHP 구문 오류 확인 |
| 훅이 실행되지 않음 |
훅 이름 오타. dx_run_hook 실행 위치 확인. DX_DEBUG=true로 실행 로그 출력 |
| settings 값이 저장 안 됨 |
설정 키 오타 (plugin_{id}_{key} 형식 확인). DxCache::flush() 후 재확인 |
| 활성화해도 기능이 동작 안 함 |
dx_active_plugin("타입") !== "내ID" 체크 위치 확인. return 구문 위치 확인 |
| 중복 실행됨 |
static $loaded 변수로 초기화 중복 방지. 전역 상수로도 가능 |
| PHP 버전 오류 |
PHP 5.6 호환: []대신 array(), 단순 클로저 사용 |
12.3 배포 체크리스트
- [ ] manifest.php에 name, version 작성 완료
- [ ] plugin.php 첫 줄: if (!defined("DX_CMS")) exit 포함
- [ ] 모든 사용자 입력값 htmlspecialchars() 처리
- [ ] POST 처리 시 dx_csrf_check() 호출
- [ ] 파일 업로드 처리 시 확장자•크기 검증
- [ ] dx_config()로 설정값 읽기 (하드코딩 금지)
- [ ] 에러 발생 시 dx_log("오류 내용", "error") 로 로깅
- [ ] DX_DEBUG=false 상태에서 최종 동작 확인
- [ ] PHP 5.6 호환 코드 작성 확인 ([] → array(), 화살표 함수 금지)
- [ ] data/ 폴더나 plugins/ 폴더 외부 경로 접근 없는지 확인
