그누보드5 SE 플러그인 만들기 매뉴얼

그누보드5 SE는 폴더 하나로 새 페이지·기능을 추가하는 사용자 모듈 시스템을 제공합니다. app/modules/<이름>/index.php 파일을 두면 자동으로 /<이름> URL로 라우팅됩니다. (Next.js app router와 비슷한 방식)

여기서 말하는 "플러그인"은 app/modules/의 사용자 모듈을 뜻합니다. app/plugin/은 에디터·캡차 등 시스템이 쓰는 서드파티 라이브러리 폴더로, 직접 만들 일은 거의 없습니다.

URL ↔ 파일 매핑

첫 모듈 만들기

app/modules/hello/index.php를 만들면 곧바로 /hello로 열립니다.

<?php
include_once('./_common.php');   // 프론트 컨트롤러가 CWD를 app/ 으로 고정해 그대로 동작
?>
<h1>안녕하세요 👋</h1>
<p>첫 번째 사용자 모듈입니다.</p>

브라우저에서 https://도메인/hello로 접속해 확인합니다.

테마와 같은 디자인 입히기 (modern shell)

테마(theme/basic)와 같은 헤더·푸터·다크모드를 그대로 쓰려면 아래 골격으로 감쌉니다.

<?php
include_once('./_common.php');

require_once(G5_THEME_PATH.'/modern/_head.inc.php');
include_once('./head.sub.php');
?>
<div class="m-shell">
    <?php require G5_THEME_PATH.'/modern/_nav.inc.php'; ?>
    <main class="m-container">
        <!-- 페이지 본문 -->
    </main>
    <?php require G5_THEME_PATH.'/modern/_footer.inc.php'; ?>
</div>
<?php include_once('./tail.sub.php');

카드·글자는 디자인 토큰을 쓰면 다크모드에 자동 대응됩니다: var(--m-surface), var(--m-text), var(--m-text-muted), var(--m-radius-lg), var(--m-shadow).

동적 경로 — [slug]

폴더명을 대괄호로 감싸면 그 자리의 URL 값이 변수로 주입됩니다.

app/modules/blog/[slug]/index.php   →   /blog/hello-world

<?php
include_once('./_common.php');
$slug = $_GET['slug'] ?? '';   // 'hello-world'
echo '글 주소: '.htmlspecialchars($slug);

모듈 전용 데이터 — data/modules/

SQLite·캐시·업로드 등 모듈 자체 데이터는 data/modules/<이름>/ 아래에 둡니다. 이 경로는 .htaccess가 **직접 URL 접근을 차단(403)**하므로 안전합니다.

$dir = G5_DATA_PATH.'/modules/hello';
if (!is_dir($dir)) mkdir($dir, 0755, true);
$db = new PDO('sqlite:'.$dir.'/store.sqlite');

규칙 (중요)

• 진입점은 항상 index.php — 다른 .php는 직접 호출되지 않습니다.
• 폴더명 segment는 ^[a-zA-Z0-9_-]+$만 허용 (경로 우회·역슬래시 차단).
• 시스템 경로가 항상 우선 — /login, /board/..., /shop/..., /admin/... 등 기존 경로는 모듈로 덮어쓸 수 없습니다.
• 페이지 안에서 include_once('./_common.php')가 그대로 동작합니다(프론트 컨트롤러가 app/을 작업 디렉터리로 고정).

켜고 끄기

별도 관리자 UI·DB·설정이 없습니다. 파일시스템이 곧 상태입니다.

• 활성: app/modules/<이름>/index.php 존재
• 비활성: 폴더명에 점을 넣어 라우팅에서 제외 (예: hello.off) — 코드는 보존, URL만 사라짐
• 제거: 폴더 삭제

모듈을 GitHub 저장소로 따로 관리하면 다른 그누보드5 SE 사이트에 폴더만 복사해 재사용할 수 있습니다.