1. 플러그인 & 모듈 관리 개요

DXCMS 관리자 패널의 [플러그인 & 모듈 관리] 메뉴는 사이트의 기능을 확장하는 플러그인을 설치•활성화•비활성화하고, 활성화된 플러그인을 시스템의 각 모듈 타입에 연결(드라이버 설정)하며, 개발자를 위한 플러그인 제작 가이드를 제공하는 통합 도구입니다.

📌  접근 경로: 관리자 대시보드 → 플러그인 & 모듈 관리 (URL: /admin/plugins) 플러그인 디렉터리: /plugins/{플러그인명}/

1.1 플러그인 시스템 개념

DXCMS는 핵심 코드를 변경하지 않고 plugins/ 디렉터리에 파일을 추가하는 것만으로 기능을 확장하는 플러그인 아키텍처를 제공합니다.
 

구성 요소	역할
플러그인 (Plugin)	plugins/ 디렉터리에 설치된 기능 확장 패키지. plugin.php 진입점 파일과 선택적 manifest.php(메타데이터)로 구성.
모듈 타입 (Type)	시스템이 정의한 기능 카테고리. PluginRegistry에 등록된 타입(예: notification·analytics·editor 등). 각 타입은 드라이버 하나를 선택해 사용.
드라이버 (Driver)	특정 모듈 타입에 등록된 플러그인. dx_register_plugin()으로 등록. 모듈 설정 탭에서 활성화.
훅 (Hook)	플러그인이 특정 시점에 실행되도록 등록하는 콜백. dx_add_hook()으로 등록, dx_run_hook()으로 실행.
PluginRegistry	플러그인 타입 정의·등록·조회를 담당하는 PHP 싱글톤 클래스.

1.2 화면 구성 — 3탭 구조

탭	설명
📦 플러그인 목록	설치된 모든 플러그인 카드. 활성화·비활성화·사용 가이드·마켓 공유 기능.
⚙ 활성 모듈 설정	활성화된 플러그인을 모듈 타입별 드라이버로 선택·설정. 플러그인별 개별 설정값 입력.
📖 개발자 가이드	플러그인 제작을 위한 디렉터리 구조·SDK·usage_guide 스키마 문서.

2. 플러그인 목록 탭

/plugins/ 디렉터리의 모든 플러그인이 카드 형태로 표시됩니다. sort_order → name 순으로 정렬됩니다. 플러그인이 하나도 없으면 "설치된 플러그인이 감지되지 않았습니다." 안내가 표시됩니다.

2.1 플러그인 자동 감지

페이지 로드 시 /plugins/*/ 디렉터리를 glob으로 스캔하여 plugin.php가 존재하는 디렉터리를 플러그인으로 인식합니다.
 

DB 미등록 플러그인	plugins 테이블에 없는 플러그인은 자동으로 INSERT IGNORE. status=0(비활성)으로 초기 등록.
메타데이터 읽기	manifest.php가 있으면 include하여 name·version·description·author 등을 읽어옵니다.
manifest.php 없을 때	디렉터리명이 name으로, 버전 1.0.0으로 기본값 사용.
정렬	plugins 테이블의 sort_order ASC → name ASC 순으로 표시.

2.2 플러그인 카드 구성

구성 요소	설명
아이콘	활성화 상태에 따라 초록(활성)/회색(비활성). 플러그인이 등록한 모듈 타입의 아이콘. 미등록이면 📦 박스 아이콘.
플러그인명·버전	manifest.php의 name + 버전(V1.0.0). 버전 없으면 미표시.
상태 배지	ACTIVE(초록 깜빡임)/DISABLED(회색). 현재 활성화 여부.
모듈 타입 배지	플러그인이 등록한 모듈 타입(예: 알림·에디터)을 인디고 배지로 표시.
설명 텍스트	manifest.php의 description. 최대 너비 내에서 말줄임.
[마켓 공유] 버튼	DesignOneX 마켓에 플러그인을 공유/중단. 공유 중인 플러그인은 보라색 "공유 중" 배지.
[활성화하기/사용 중지] 버튼	비활성: 검정 "활성화하기" 버튼. 활성: 빨간 "사용 중지" 버튼. POST 폼으로 즉시 처리.

2.3 활성화/비활성화 처리

[활성화하기] 또는 [사용 중지] 버튼 클릭 시 POST 요청이 전송됩니다.
 

액션	처리 내용
활성화 (status=1)	plugins 테이블에서 해당 directory의 status를 1로 업데이트. "활성화되었습니다. 아래 사용 방법을 확인하세요." 메시지. 해당 플러그인 카드로 자동 스크롤.
비활성화 (status=0)	status를 0으로 업데이트. "비활성화되었습니다." 메시지. 해당 플러그인이 모듈 설정 탭에서 제외됨.

💡  플러그인을 활성화한 직후 해당 카드에 하늘색 테두리(border-sky-500)와 링(ring-sky-500/10)이 적용되어 시각적으로 강조됩니다. 자동 스크롤로 해당 카드가 화면 중앙에 표시됩니다.

3. 플러그인 사용 가이드 패널

활성화된 플러그인이 usage_guide 데이터를 등록한 경우, 카드 하단에 접이식 사용 가이드 패널이 표시됩니다. 플러그인을 방금 활성화한 경우 자동으로 펼쳐집니다.

3.1 가이드 패널 구성 요소

구성 요소	usage_guide 키	표시 내용 및 조건
기능 요약	what	하늘색 배경 흰색 카드. "기능 요약" 라벨 아래 한 문장 설명. 예: "새 댓글이 달리면 상단에 알림 아이콘이 표시됩니다."
설치 안내	steps	단계별 설치 지시사항. 배열로 작성. 각 단계가 번호 달린 카드 형태로 표시.
자동 적용 알림	auto	true이면 "🎉 이 플러그인은 별도의 테마 수정 없이 자동으로 적용됩니다." 초록 배너 표시.
테마 연동 코드	hooks	auto가 없거나 false이면 표시. 어두운 배경의 코드 블록에 <?php dx_run_hook('훅이름'); ?> 코드가 표시됩니다. [코드 복사] 버튼 제공.
적용 모습	preview	"👁️ 적용 모습:" 앰버 배경 배너. 실제 UI에서 어떻게 보이는지 텍스트로 안내.
참고사항	note	회색 배경 정보 박스. 주의사항·제한·추가 설명 등.
모듈 설정 이동	(항상 표시)	"⚙️ 지금 활성 모듈로 설정하기" 파란 버튼. /admin/plugins?tab=modules로 이동.

💡  [이 플러그인의 사용 가이드 보기] 버튼(▼ 아이콘)을 클릭하면 가이드가 펼쳐집니다. 방금 활성화된 플러그인은 자동으로 열린 상태(rotate-180)로 표시됩니다.

3.2 테마 연동 코드 복사 기능

hooks 항목이 있는 플러그인에서는 각 훅 코드 우측 상단에 [코드 복사] 버튼이 표시됩니다.
 

코드 형식	<?php dx_run_hook('훅이름'); ?> 형식의 PHP 코드.
복사 방법	[코드 복사] 버튼 클릭 → navigator.clipboard API로 클립보드에 복사. 지원 안되면 textarea execCommand 폴백.
복사 완료	버튼 텍스트가 "COPIED" + 초록색으로 1.5초간 변경 후 복원.
사용법	복사한 코드를 테마 PHP 템플릿의 원하는 위치(헤더·푸터·사이드바 등)에 붙여넣기.

4. DesignOneX 마켓 공유

플러그인 카드의 [마켓 공유] 버튼으로 자신이 만든 플러그인을 DesignOneX 마켓에 공개할 수 있습니다.

4.1 공유 시작

1. [마켓 공유] 버튼 클릭 → 카드 하단에 보라색 공유 설정 패널 표시
2. [공개용 짧은 설명] 입력 (플러그인 핵심 기능 한 줄 설명)
3. [태그 키워드] 입력 (쉼표로 구분. 예: 디자인, 통계, 관리)
4. [마켓 공유 시작하기] 버튼 클릭
5. 공유 처리: plugins 테이블 is_shared=1, share_key=무작위 32자 HEX 저장
6. "공유가 활성화되었습니다." 성공 메시지 확인
7. 이후 카드에 보라색 "공유 중" 배지 표시

4.2 공유 중 상태

공유 키 (share_key)	dx_random_hex(32)로 생성된 64자리 HEX 문자열. 마켓 식별자로 사용.
shared_at	최초 공유 시점. 이후 재공유해도 변경되지 않습니다(IF(shared_at IS NULL, NOW(), shared_at)).
나의 등록물 보기	공유 패널 우측의 [나의 등록물 보기] 버튼으로 /admin/market?tab=my 이동.
공유 중단	[공유 중단] 버튼 클릭 → 확인 창 후 is_shared=0으로 변경. share_key는 유지됩니다.

⚠️  공유된 플러그인은 DesignOneX 마켓에서 다른 사용자가 다운로드할 수 있습니다. 플러그인에 민감한 정보(API 키, 비밀번호 등)가 포함되지 않도록 주의하세요.

5. 활성 모듈 설정 탭

[활성 모듈 설정] 탭에서는 시스템의 각 모듈 타입에 어떤 플러그인(드라이버)을 사용할지 선택하고, 해당 플러그인의 개별 설정값을 입력합니다. 이 탭에는 플러그인 목록 탭에서 활성화(status=1)된 플러그인만 표시됩니다.

5.1 모듈 타입 패널 구성

PluginRegistry에 등록된 각 모듈 타입마다 하나의 설정 패널이 표시됩니다.
 

구성 요소	설명
패널 헤더	모듈 타입 아이콘·이름·설명. 현재 활성 드라이버가 있으면 우측에 초록 깜빡임 "Active: 드라이버명" 배지.
"사용 가능한 플러그인 없음" 상태	해당 타입에 등록된 활성 플러그인이 없을 때. "플러그인 탭에서 해당 타입의 플러그인을 먼저 활성화하세요." 안내.
드라이버 선택 드롭다운	활성화된 플러그인 목록. 선택 즉시 우측 설정 패널이 해당 플러그인 설정으로 전환됨(togglePluginSettings JS).
플러그인 개별 설정	선택된 드라이버의 settings 배열에 정의된 설정 필드. 텍스트·비밀번호·셀렉트·텍스트에어리어·체크박스 그룹 지원.

5.2 설정 필드 타입

타입	HTML 입력 요소	특징 및 저장 방식
text (기본)	<input type="text">	일반 텍스트 입력. settings 테이블에 문자열로 저장. DB 키: plugin_{플러그인ID}_{설정키}.
password	<input type="password">	비밀번호형 마스킹 입력. API 키·시크릿 등 민감 정보에 사용.
select	<select>	options 배열에 정의된 {value:label} 목록에서 하나 선택.
textarea	<textarea rows=3>	여러 줄 텍스트. 주로 긴 설정값(HTML·CSS 코드 등)에 사용.
checkbox_group	<input type="checkbox">	options 배열의 여러 값을 다중 선택. 쉼표 구분 문자열로 DB에 저장. 예: "a,b,c".

💡  checkbox_group 타입은 plugin_cb_{설정키}[] 배열로 POST됩니다. 서버에서 implode(",", ...)으로 합산 후 settings 테이블에 저장합니다. PHP에서 읽을 때는 explode(",", $value)로 분리하세요.

5.3 설정 저장 처리

1. CSRF 토큰 검증
2. 각 모듈 타입의 setting_key 값(드라이버 선택)을 settings 테이블에 UPSERT
3. plugin_settings[key]=value 형식의 플러그인 개별 설정값 UPSERT
4. plugin_cb_{key}[] 체크박스 그룹을 쉼표 문자열로 변환 후 UPSERT
5. DxCache::flush()로 전체 캐시 초기화
6. PRG 패턴: 저장 후 ?saved=1 파라미터로 GET 리다이렉트 → "설정이 저장되었습니다." 메시지

💡  PRG(Post-Redirect-Get) 패턴 덕분에 브라우저 새로고침 시 중복 저장이 방지됩니다. 저장 후 URL에 ?saved=1이 추가됩니다.

5.4 드라이버 선택과 설정 패널 전환

드라이버 드롭다운 변경 시 togglePluginSettings(type, selectedId) JavaScript 함수가 실행됩니다.
 

동작 방식	해당 타입(type)에 속하는 모든 플러그인 설정 패널을 display:none으로 숨김. 선택된 드라이버의 패널만 display:block으로 표시.
패널 ID 형식	plugin-settings-{타입}-{플러그인ID}. 예: plugin-settings-notification-my-plugin.
즉시 반영	설정 저장 전에도 드라이버를 바꾸면 해당 플러그인의 설정 필드가 즉시 표시됩니다.

6. 개발자 가이드 탭

[개발자 가이드] 탭은 플러그인을 직접 제작하려는 개발자를 위한 SDK 문서를 제공합니다. 디렉터리 구조, dx_register_plugin() 사용법, usage_guide 스키마 명세가 포함됩니다.

6.1 플러그인 디렉터리 구조

최소 구조는 plugin.php 하나입니다. 나머지는 선택 사항입니다.
 

파일	역할 및 설명
plugin.php (필수)	플러그인 진입점. 훅 등록(dx_add_hook) + dx_register_plugin() 호출. 이 파일 없으면 플러그인으로 인식 안 됨.
manifest.php (선택)	메타데이터 배열 반환. name·version·description·author·author_url 키. 없으면 디렉터리명과 기본값 사용.
assets/ (선택)	JavaScript·CSS·이미지 등 정적 파일. 플러그인이 필요한 리소스를 이 디렉터리에 보관.

6.2 plugin.php 기본 구조

plugin.php에서 반드시 포함해야 하는 요소를 설명합니다
 

함수/코드	설명
if(!defined("DX_CMS")) exit()	직접 URL 접근 방지. 반드시 파일 상단에 포함.
dx_register_plugin(array(...))	플러그인을 PluginRegistry에 등록. id·type·name·version·settings·usage_guide 등 키 포함.
dx_add_hook('훅이름', 함수)	특정 시점에 실행될 콜백 함수 등록. 여러 훅을 등록 가능.
dx_run_hook('훅이름')	등록된 훅을 실행. 테마 템플릿에 삽입하여 플러그인 콘텐츠 출력.

6.3 dx_register_plugin() 매개변수

키	필수 여부	설명 및 예시
id	필수	플러그인 고유 식별자. 디렉터리명과 일치 권장. 예: "my-notification".
type	필수	모듈 타입 식별자. PluginRegistry에 등록된 타입과 일치해야 합니다. 예: "notification".
name	권장	관리자 UI에 표시될 플러그인 표시 이름. 예: "내 알림 플러그인".
version	권장	버전 문자열. 예: "1.2.0".
settings	선택	플러그인 설정 필드 정의 배열. [설정키 => [label, type, default, placeholder, options]] 구조.
usage_guide	권장	사용 가이드 배열. what·steps·auto·hooks·preview·note 키. 관리자 UI에서 시각화.

6.4 usage_guide 스키마 명세

키	데이터 타입	설명
what	string	핵심 기능 한 줄 설명. 관리자 "기능 요약" 패널에 표시.
steps	array	활성화 후 완료해야 할 절차 배열. 각 요소가 번호 달린 카드로 표시.
auto	bool/true	true이면 "테마 수정 없이 자동 적용" 배너 표시. hooks 대신 사용.
hooks	array	[훅이름 => 설명] 연관 배열. 각 훅의 PHP 코드와 복사 버튼이 표시됨. auto가 없을 때 사용.
preview	string	적용 모습 텍스트. "👁 적용 모습:" 배너에 표시.
note	string	추가 주의사항·제한·참고 설명. 회색 정보 박스에 표시.

6.5 manifest.php 예시

manifest.php는 플러그인의 메타데이터를 배열로 반환하는 PHP 파일입니다.
 

name	플러그인 표시 이름. 예: "내 알림 플러그인".
version	버전 문자열. 예: "2.1.0".
description	플러그인 설명. 카드에 표시됨.
author	개발자 이름 또는 회사명.
author_url	개발자 웹사이트 URL.

7. 플러그인 설치 및 운영 절차

7.1 외부에서 받은 플러그인 설치

1. 플러그인 파일을 서버의 /plugins/{플러그인폴더명}/ 디렉터리에 업로드 (FTP 또는 파일 관리자)
2. 폴더 안에 plugin.php가 존재하는지 확인
3. 관리자 → [플러그인 & 모듈 관리] 메뉴 접속
4. [플러그인 목록] 탭에서 새로 설치된 플러그인 카드 확인 (자동 감지)
5. [활성화하기] 버튼 클릭
6. 사용 가이드 패널에서 steps 단계 순서대로 설정
7. [활성 모듈 설정] 탭으로 이동하여 해당 모듈 타입의 드라이버로 선택
8. 플러그인 개별 설정값 입력 (API 키 등)
9. [모든 설정사항 저장하기] 버튼 클릭
10. 사이트에서 기능 동작 확인

7.2 플러그인 비활성화

1. [플러그인 목록] 탭에서 비활성화할 플러그인의 [사용 중지] 버튼 클릭
2. "비활성화되었습니다." 메시지 확인
3. [활성 모듈 설정] 탭에서 해당 플러그인이 드라이버 목록에서 제거됨 확인
4. 필요하면 다른 드라이버로 교체 설정 후 저장

💡  플러그인을 비활성화해도 파일은 /plugins/ 디렉터리에 그대로 유지됩니다. 언제든지 다시 활성화할 수 있습니다.

7.3 플러그인 완전 제거

1. [사용 중지] 버튼으로 비활성화
2. FTP 또는 서버 파일 관리자로 /plugins/{플러그인폴더명}/ 디렉터리 삭제
3. 관리자 → 플러그인 목록 새로고침 시 해당 플러그인 카드가 사라짐

⚠️  플러그인 파일만 삭제하면 plugins 테이블의 DB 레코드는 남아 있습니다. 완전 정리가 필요하면 DB에서 해당 directory의 레코드를 수동으로 삭제하세요.

8. 자주 묻는 질문 (FAQ)

Q1. 플러그인을 활성화했는데 기능이 동작하지 않습니다.

A. 활성화 후 반드시 [활성 모듈 설정] 탭에서 해당 모듈 타입의 드라이버로 해당 플러그인을 선택하고 [저장]해야 합니다. 또한 사용 가이드의 steps에 안내된 테마 연동 코드(<?php dx_run_hook('훅이름'); ?>)를 테마 템플릿의 적절한 위치에 삽입해야 합니다.

Q2. 플러그인 목록에 설치한 플러그인이 표시되지 않습니다.

A. ① /plugins/{폴더명}/plugin.php 파일이 존재하는지 확인. ② 폴더명에 공백이나 특수문자가 없는지 확인(영문•숫자•하이픈•언더스코어만 허용). ③ 페이지를 새로고침하면 자동 감지합니다.

Q3. [활성 모듈 설정]에 드라이버가 표시되지 않습니다.

A. 해당 모듈 타입에 등록된 활성화된 플러그인이 없어서입니다. [플러그인 목록] 탭에서 해당 타입의 플러그인을 먼저 활성화하세요. 플러그인이 dx_register_plugin()에서 올바른 type 값을 등록해야 합니다.

Q4. 플러그인 설정을 저장했는데 변경이 안 됩니다.

A. PRG 패턴으로 저장 후 리다이렉트됩니다. 리다이렉트 후 URL에 ?saved=1이 붙으면 정상 저장된 것입니다. 캐시가 활성화된 환경에서는 DxCache::flush()가 자동으로 실행되므로 최대 수 초 내에 반영됩니다.

Q5. checkbox_group 설정값을 PHP 코드에서 읽으려면?

A. settings 테이블에 쉼표(,) 구분 문자열로 저장됩니다. dx_config("plugin_{플러그인ID}_{설정키}")로 읽은 후 explode(",", $value)로 배열로 변환하여 사용하세요.

Q6. 마켓 공유 후 플러그인을 업데이트하려면?

A. 파일을 서버에서 직접 수정하세요. 공유 설정(is_shared, share_key)은 별도로 변경할 필요 없습니다. 버전 번호는 manifest.php에서 수정하면 됩니다.

Q7. manifest.php가 없어도 플러그인이 동작합니까?

A. 네. manifest.php는 선택 사항입니다. 없으면 디렉터리명이 플러그인 이름으로, 버전 1.0.0이 사용됩니다. 단, 관리자 목록에서 이름•설명•버전이 제대로 표시되지 않으므로 작성을 권장합니다.

9. 용어 정리

용어	설명
plugins 테이블	플러그인 정보 DB 테이블. directory/name/version/description/author/status/sort_order/is_shared/share_key 컬럼.
plugin.php	플러그인 진입점 파일. 이 파일이 없으면 플러그인으로 인식되지 않음.
manifest.php	플러그인 메타데이터(name/version/description/author 등) 배열을 반환하는 파일.
PluginRegistry	플러그인 타입 정의·등록·조회 PHP 싱글톤 클래스.
모듈 타입 (Type)	시스템에 정의된 기능 카테고리. 예: notification·analytics·editor. 각 타입은 드라이버 1개 사용.
드라이버 (Driver)	모듈 타입에 등록된 플러그인. 모듈 설정 탭에서 타입별로 선택하여 활성화.
dx_register_plugin()	플러그인을 PluginRegistry에 등록하는 함수. id/type/settings/usage_guide 등 배열 인자.
dx_add_hook()	특정 훅에 콜백 함수를 등록하는 함수. plugin.php에서 사용.
dx_run_hook()	등록된 훅 콜백을 실행하는 함수. 테마 템플릿에서 사용.
usage_guide	플러그인 활성화 후 관리자에게 표시되는 사용 안내 배열. what/steps/auto/hooks/preview/note 키.
auto (usage_guide)	true이면 테마 수정 없이 자동 적용됨을 의미. hooks 대신 사용.
hooks (usage_guide)	{훅이름: 설명} 연관 배열. <?php dx_run_hook('훅'); ?> 코드 복사 UI 자동 생성.
setting_key	모듈 타입별 활성 드라이버를 저장하는 settings 테이블의 키.
plugin_{ID}_{키}	플러그인 개별 설정의 DB 저장 키 형식. 예: plugin_my-plugin_api_key.
checkbox_group	다중 선택 체크박스 타입. 선택값을 쉼표 구분 문자열로 저장.
plugin_cb_{key}[]	checkbox_group POST 파라미터 형식. 서버에서 implode(",", ...)으로 처리.
togglePluginSettings()	모듈 설정 탭의 드라이버 드롭다운 변경 시 설정 패널 전환 JS 함수.
dxToggleGuide()	플러그인 카드의 사용 가이드 패널 열기/닫기 JS 함수.
dxCopyHook()	테마 연동 코드를 클립보드에 복사하는 JS 함수.
share_key	마켓 공유 시 생성되는 64자 HEX 문자열. 마켓에서 플러그인 식별자로 사용.
PRG 패턴	Post-Redirect-Get. 설정 저장 후 ?saved=1로 GET 리다이렉트. 중복 저장 방지.