gper/Gnuboard7

Fork 0

Files

T

HeuJung 1db039ff34 v7.0.0-beta.4 release

2026-05-11 11:29:41 +09:00

13 KiB

Raw Blame History

학습용 샘플 확장 (Sample Extensions)

G7 확장 시스템을 처음 접하는 개발자를 위한 학습용 최소 샘플 확장 4종 가이드. 각 샘플은 해당 확장 타입의 모든 계층을 1파일씩 포함한 "읽기 쉬운 레퍼런스" 입니다.

TL;DR (5초 요약)

1. 샘플 확장 4종: gnuboard7-hello_module / _plugin / _admin_template / _user_template
2. 위치: modules/_bundled/, plugins/_bundled/, templates/_bundled/ 하위
3. 용도: 스캐폴딩 결과 검증, 계층 구조 1:1 비교, 훅/레이아웃/테스트 학습
4. hidden: 모든 샘플은 manifest.hidden=true → 관리자 UI 기본 제외 (CLI 정상)
5. 설치: php artisan {type}:install gnuboard7-hello_*

샘플 확장 4종 한눈에 보기

확장	타입	경로	파일 수	테스트	주 시연
`gnuboard7-hello_module`	모듈	`modules/_bundled/gnuboard7-hello_module/`	34	11/11 green	Memo CRUD + 훅 발행
`gnuboard7-hello_plugin`	플러그인	`plugins/_bundled/gnuboard7-hello_plugin/`	15	6/6 green	Action + Filter 훅 구독
`gnuboard7-hello_admin_template`	Admin 템플릿	`templates/_bundled/gnuboard7-hello_admin_template/`	31	13/13 green (공통)	Basic 8개 컴포넌트 + 에러 6종
`gnuboard7-hello_user_template`	User 템플릿	`templates/_bundled/gnuboard7-hello_user_template/`	28	13/13 green (공통)	홈 + Memo 리스트 연동

모든 샘플은 manifest.hidden = true 로 설정되어 있어 관리자 UI 의 모듈/플러그인/템플릿 목록에서 기본 제외됩니다. artisan CLI 로는 정상 설치/관리할 수 있습니다.

각 확장이 시연하는 계층

1. `gnuboard7-hello_module` — 학습용 모듈

실제 비즈니스 모듈이 필요로 하는 모든 계층을 1파일씩 포함합니다. 복잡한 도메인 로직은 배제하고, Memo 라는 최소 엔티티 1개의 CRUD + 훅 발행 흐름만 보여줍니다.

계층	예시 파일	역할
Entry	`module.php`	`AbstractModule` 상속, 권한/메뉴 정의
Model	`src/Models/Memo.php`	Eloquent 모델
Migration	`database/migrations/*_create_memos_table.php`	테이블 스키마
Factory	`database/factories/MemoFactory.php`	테스트 데이터 생성
Seeder	`database/seeders/DatabaseSeeder.php` + `Sample/`	설치/샘플 시더 분리
Repository (Interface)	`src/Contracts/Repositories/MemoRepositoryInterface.php`	DI 인터페이스
Repository (Impl)	`src/Repositories/MemoRepository.php`	Eloquent 구현체
Service	`src/Services/MemoService.php`	비즈니스 로직 + 훅 발행
FormRequest	`src/Http/Requests/Admin/MemoRequest.php`	검증
Resource	`src/Http/Resources/MemoResource.php`	API 응답 포맷
Controller	`src/Http/Controllers/Admin/MemoController.php`	RESTful CRUD
Listener	`src/Listeners/*Listener.php`	훅 구독 (자체 발행도 예시)
Layout	`resources/layouts/admin/memos/*.json`	관리자 목록/폼 레이아웃
Test	`tests/Feature/MemoControllerTest.php` + `tests/Unit/`	Feature + Unit
다국어 (백엔드)	`src/lang/{ko,en}/messages.php`	PHP 배열
다국어 (프론트)	`resources/lang/{ko,en}.json`	JSON

실제 모듈이 N 개 엔티티를 다룬다면, 위 계층을 N 배로 확장합니다.

2. `gnuboard7-hello_plugin` — 학습용 플러그인

플러그인의 핵심 역할인 훅 구독 을 시연합니다. 모듈의 Memo 생성 훅을 구독하여 부가 작업을 수행하는 Action 리스너와, 리스트 응답을 가공하는 Filter 리스너를 각각 1개씩 포함합니다.

계층	예시 파일	역할
Entry	`plugin.php` (루트)	`AbstractPlugin` 상속
Listener (Action)	`src/Listeners/*ActionListener.php`	훅 발생 시 부가 작업
Listener (Filter)	`src/Listeners/*FilterListener.php`	`type: 'filter'` 명시, 반환값으로 가공
Settings Schema	`config/settings/defaults.json` + `getSettingsSchema()`	관리자 UI 설정
Settings Layout	`resources/layouts/admin/plugin_settings.json`	설정 UI (자동 바인딩 패턴)
Test	`tests/Feature/`, `tests/Unit/`	훅 발행 → 구독 검증
다국어 (프론트)	`resources/lang/{ko,en}.json`	JSON (백엔드 PHP 다국어 없음)

플러그인은 완전한 페이지 레이아웃 등록 불가 — 설정 UI (plugin_settings.json) 와 layout_extensions (확장 지점/Overlay) 만 허용됩니다.

3. `gnuboard7-hello_admin_template` — 학습용 Admin 템플릿

Admin 템플릿의 최소 구성을 보여줍니다. sirsoft-admin_basic 의 전체 컴포넌트 세트 중 꼭 필요한 Basic 8개 와 에러 레이아웃 6종만 포함합니다.

계층	예시 파일	역할
Entry	`template.json`	type: admin, components 레지스트리, error_config
Components	`src/components/basic/{Div,Button,Input,...}.tsx`	HTML 태그 래핑 Basic 8개
Layouts (베이스)	`layouts/_admin_base.json`	헤더 + 사이드바 + 콘텐츠 슬롯
Layouts (초기)	`layouts/admin_dashboard.json`	대시보드 예시
Layouts (에러)	`layouts/errors/{401,403,404,500,503,maintenance}.json`	에러 6종 필수
Routes	`routes.json`	`/admin/` 라우트
Test	`__tests__/layouts/*.test.tsx`	`createLayoutTest()` 기반 렌더링 테스트
다국어	`lang/{ko,en}.json`	common.* 키만

4. `gnuboard7-hello_user_template` — 학습용 User 템플릿

User 템플릿의 최소 구성을 보여줍니다. gnuboard7-hello_module 의 Memo API 를 data_sources 로 연동하여 홈 페이지에 리스트를 출력하는 예시를 포함합니다.

계층	예시 파일	역할
Entry	`template.json`	type: user, features 플래그, components 레지스트리
Components	`src/components/basic/*.tsx`	Basic 컴포넌트
Layouts (베이스)	`layouts/_user_base.json`	헤더 + 콘텐츠 + 푸터
Layouts (홈)	`layouts/home.json`	Memo 모듈 `data_sources` 연동
Layouts (에러)	`layouts/errors/*.json`	에러 6종
Routes	`routes.json`	`/` 루트, `auth_required: false`
Test	`__tests__/layouts/*.test.tsx`	API 모킹 + 렌더링 테스트

샘플 복제 워크플로우

"Hello 모듈을 템플릿으로 새 모듈 acme-blog 만들기" 시나리오:

# 1. _bundled 하위에 복제
cp -r modules/_bundled/gnuboard7-hello_module modules/_bundled/acme-blog

# 2. 식별자/네임스페이스 일괄 치환 (에디터 전역 치환)
#    gnuboard7-hello_module   → acme-blog
#    Gnuboard7\HelloModule    → Acme\Blog
#    gnuboard7                → acme
#    HelloModule              → Blog
#    hello_module             → blog
#    Memo / memo / memos      → Post / post / posts  (도메인 이름 변경)

# 3. manifest 정리
#    - module.json: hidden 필드 제거 (또는 false) — 새 모듈은 UI 노출 필요
#    - version: 0.1.0 으로 초기화
#    - description: 새 모듈 설명으로 교체

# 4. 오토로드 갱신 후 설치
php artisan extension:update-autoload
php artisan module:install acme-blog
php artisan module:activate acme-blog

# 5. 테스트 실행으로 복제 무결성 확인
php vendor/bin/phpunit modules/_bundled/acme-blog/tests

복제 후 반드시 제거해야 할 항목:

manifest.hidden 필드 (또는 false 로 설정)
README/CHANGELOG 의 "학습용 샘플" 문구
Sample/ 시더의 학습용 더미 데이터 (실제 샘플 데이터로 교체)

학습 순서 권장

확장 시스템을 처음 접하는 경우 다음 순서를 권장합니다:

1) gnuboard7-hello_module         (백엔드 계층 전부 — Service/Repository/Controller/Request/Resource)
        ↓
2) gnuboard7-hello_plugin         (훅 구독 — Action + Filter)
        ↓
3) gnuboard7-hello_admin_template (프론트엔드 컴포넌트 + 레이아웃 테스트)
        ↓
4) gnuboard7-hello_user_template  (모듈 API 연동 — data_sources)
        ↓
5) sirsoft-page / sirsoft-board 등 실전 확장
        (다중 엔티티, 복잡한 권한 범위, 동적 메뉴 등 본격적인 패턴)

1~2 단계는 백엔드 개발자가 반드시 거쳐야 하는 최소 학습 경로입니다.
3~4 단계는 프론트엔드 담당자가 components.md / layout-json.md / layout-testing.md 와 함께 읽으면 좋습니다.
5 단계부터는 실전 패턴(권한 범위, 동적 엔티티, SEO 변수 등) 이 등장하므로 본격적인 개발 전 module-basics.md 의 "동적 권한/역할/메뉴 보존 규칙" 을 먼저 숙지합니다.

샘플 설치/제거 명령어

설치

# 모듈
php artisan module:install gnuboard7-hello_module
php artisan module:activate gnuboard7-hello_module

# 플러그인 (Hello 모듈이 먼저 활성화되어 있어야 훅 구독 검증 가능)
php artisan plugin:install gnuboard7-hello_plugin
php artisan plugin:activate gnuboard7-hello_plugin

# Admin 템플릿
php artisan template:install gnuboard7-hello_admin_template
php artisan template:activate gnuboard7-hello_admin_template

# User 템플릿
php artisan template:install gnuboard7-hello_user_template
php artisan template:activate gnuboard7-hello_user_template

샘플 데이터 시딩

# 설치 + 샘플 시더 실행 (Memo 더미 데이터 생성)
php artisan module:seed gnuboard7-hello_module --sample

숨김 포함 목록 조회

모든 Hello 샘플은 hidden: true 이므로 기본 목록에 나타나지 않습니다:

php artisan module:list --hidden
php artisan plugin:list --hidden
php artisan template:list --hidden

제거

php artisan template:deactivate gnuboard7-hello_user_template
php artisan template:uninstall gnuboard7-hello_user_template

php artisan template:deactivate gnuboard7-hello_admin_template
php artisan template:uninstall gnuboard7-hello_admin_template

php artisan plugin:deactivate gnuboard7-hello_plugin
php artisan plugin:uninstall gnuboard7-hello_plugin

php artisan module:deactivate gnuboard7-hello_module
php artisan module:uninstall gnuboard7-hello_module

제거 순서는 의존성의 역순 — 템플릿 → 플러그인 → 모듈. 플러그인이 모듈 훅을 구독하므로 플러그인을 먼저 비활성화해야 합니다.

hidden 플래그와 관리자 UI

모든 Hello 샘플은 manifest 에 "hidden": true 가 설정되어 있습니다:

{
    "identifier": "gnuboard7-hello_module",
    "version": "0.1.0",
    "hidden": true
}

동작

대상	hidden 적용
관리자 UI 기본 응답 (`GET /api/admin/modules` 등)	제외
artisan 기본 목록 (`module:list`, `plugin:list`, `template:list`)	제외
설치/활성화/제거 커맨드	정상 동작
업데이트 감지 (`:check-updates`, `:update`)	정상 동작
활성화 후 런타임 기능 (라우트/훅/권한)	정상 동작

숨김 포함 조회

# CLI
php artisan module:list --hidden
php artisan plugin:list --hidden
php artisan template:list --hidden

# API
GET /api/admin/modules?include_hidden=1
GET /api/admin/plugins?include_hidden=1
GET /api/admin/templates?include_hidden=1

학습 후 제거 권장

실전 프로젝트에서는 Hello 샘플을 제거 하여 관리자 UI 와 DB 를 정리할 것을 권장합니다. 복제 워크플로우로 새 확장을 만든 후에는 원본 샘플이 더 이상 필요하지 않습니다.

상세: extension-manager.md

13 KiB

Raw Blame History

학습용 샘플 확장 (Sample Extensions)

TL;DR (5초 요약)

목차

샘플 확장 4종 한눈에 보기

각 확장이 시연하는 계층

1. `gnuboard7-hello_module` — 학습용 모듈

2. `gnuboard7-hello_plugin` — 학습용 플러그인

3. `gnuboard7-hello_admin_template` — 학습용 Admin 템플릿

4. `gnuboard7-hello_user_template` — 학습용 User 템플릿

샘플 복제 워크플로우

학습 순서 권장

샘플 설치/제거 명령어

설치

샘플 데이터 시딩

숨김 포함 목록 조회

제거

hidden 플래그와 관리자 UI

동작

숨김 포함 조회

학습 후 제거 권장

관련 문서

13 KiB Raw Blame History

학습용 샘플 확장 (Sample Extensions)

TL;DR (5초 요약)

목차

샘플 확장 4종 한눈에 보기

각 확장이 시연하는 계층

1. gnuboard7-hello_module — 학습용 모듈

2. gnuboard7-hello_plugin — 학습용 플러그인

3. gnuboard7-hello_admin_template — 학습용 Admin 템플릿

4. gnuboard7-hello_user_template — 학습용 User 템플릿

샘플 복제 워크플로우

학습 순서 권장

샘플 설치/제거 명령어

설치

샘플 데이터 시딩

숨김 포함 목록 조회

제거

hidden 플래그와 관리자 UI

동작

숨김 포함 조회

학습 후 제거 권장

관련 문서

13 KiB

Raw Blame History

1. `gnuboard7-hello_module` — 학습용 모듈

2. `gnuboard7-hello_plugin` — 학습용 플러그인

3. `gnuboard7-hello_admin_template` — 학습용 Admin 템플릿

4. `gnuboard7-hello_user_template` — 학습용 User 템플릿