fix(core,extensions): 확장 쓰기 경로 공통화 · HTMLPurifier 정의 캐시 storage 이전

https://github.com/gnuboard/g7/issues/125 — 상품 상세설명을 HTML 로 저장할 때
HTMLPurifier 가 모듈 vendor 폴더 안에 정의 캐시를 만들려다 실패해 저장이 매번 500 으로
끝나던 문제를 고친다. vendor 를 읽기 전용으로 두는 표준 배포에서 그 쓰기는 예외가 아니라
PHP 경고로 나오고 Laravel 이 이를 ErrorException 으로 승격시킨다. 캐시는 설정 해시당 1회만
기록되므로 캐시가 영영 생기지 않아 재시도해도 같은 결과였다.

캐시 경로를 storage 아래로 옮기고, 그 경로마저 확보하지 못하면 캐시만 끄고 정화는 그대로
수행한다 — 캐시는 성능 장치이고 정화는 보안 장치라, 전자의 실패가 후자를 건너뛰게 만들면
안 된다. 저장은 성공하므로 운영자에게 도달하는 흔적이 로그 하나뿐이라 error 수준으로 남긴다
(출하 기본 로그 수준이 error 라 warning 은 기본 설치 상태에서 파일에 남지 않는다).

그 과정에서 갈라져 있던 두 축을 코어 한 곳으로 모은다.

- 쓰기 디렉토리 확보: 억제 생성·chmod·setgid·소유권 상속·쓰기 판정 절차가 정적 게시와
 정의 캐시 두 곳에 서로 다른 하드닝으로 복제돼 있었다(억제 mkdir·setgid·clearstatcache 가
 사본마다 한쪽씩 빠져 있었다). FilePermissionHelper 의 ensureWritableDirectory 와
 hardenDirectory 로 통합하고, 실패 사유는 out 파라미터로 올려 정책(조용한 성능 저하 대
 시끄러운 실패)은 호출부가 정하게 둔다.

- 확장 저장 경로: storage_path('app/modules/…') 손조립이 30곳에 흩어져 있어 테스트 격리
 분기를 넣으려면 사본마다 복제해야 했고, 한 곳만 빠뜨려도 그 확장의 테스트가 운영 설정
 파일을 덮어쓴다. 디스크 root 를 단일 출처로 읽는 ExtensionStoragePath 로 전환하고 테스트
 분기는 config/filesystems.php 한 줄에서 끝낸다.

함께 고친 것

- 테스트가 운영 라우트 캐시로 부팅해 확장 allowlist 가 라우트 축에서 통째로 무력화되던
 문제. 삭제가 아니라 경로를 돌린다 — 라우트 캐시는 확장 작업 전까지 재생성되지 않아,
 삭제하면 운영 사이트가 그때까지 라우트 파일 스캔 경로로 떨어진다.
- PHPUnit 프로세스가 확장 vendor 의 제3자 composer 패키지를 오토로드하지 않아 그 패키지를
 쓰는 코드 경로가 통째로 테스트 불가였던 문제. 확장 자신의 오토로더를 그대로 쓰면 활성
 디렉토리가 _bundled 를 이기고 base path 유추까지 깨지므로, 생성된 맵에서 제3자 항목만
 골라 별도 로더로 등록한다.
- 게시 폴더가 setgid 를 갖지 않아, 명령줄과 웹이 번갈아 만든 하위 폴더를 다른 쪽이 쓰지
 못하던 문제.
- 관리자 템플릿이 HTML 정화 라이브러리를 직접 지정하지 않아 전이 의존으로 딸려온 구버전이
 쓰이던 문제.

동반 산출물

- 규정 표(·AGENTS.md) 6행 + storage-driver/service-repository/testing-guide 문서
- audit 룰 2종 + coverage 6항목. 저장소가 이미 전량 전환돼 전수 실행이 공허 통과하므로
 판정식은 픽스처 36건이 잠근다
- INSTALL.md 에 설치 후 파일 권한 절 추가 (vendor 쓰기 권한 불요를 명시)
This commit is contained in:
HeuJung committed 2026-08-28 15:22:22 +09:00
1 parent fc27a6edf6
commit 85e266d361
88 files changed
+1913 -332

No files matched your search

+25
View File
@@ -73,6 +73,31 @@ powershell -Command "npm run test:run"
2. `_bundled` src/ → PSR-4 prepend 등록 (활성 디렉토리보다 우선 검색)
3. `autoload-extensions.php` → 이미 로드된 _bundled 항목은 스킵
4. Manager/RouteServiceProvider → `class_exists` 가드로 중복 선언 방지
5. 확장 `vendor/` → 제3자 composer 패키지만 골라 별도 로더로 등록
### 확장의 제3자 composer 패키지
확장이 자기 `composer.json` 으로 들여온 제3자 패키지(예: HTML 정화 라이브러리)는 `tests/bootstrap.php`
가 등록합니다. 확장별 테스트 베이스 클래스에서 같은 일을 다시 하지 않습니다 — 규칙이 두 곳으로
갈라지면 한쪽만 고쳐져 조용히 어긋납니다.
```
금지: 확장 vendor 의 autoload.php 를 그대로 require
필수: 생성된 맵에서 제3자 항목만 골라 vendorDir 없는 로더로 등록
```
그 오토로더를 그대로 쓰면 두 가지가 오류 없이 깨집니다.
1. 확장 **자신의** PSR-4 와 files 를 활성 디렉토리로 매핑하고 자신을 prepend 로 걸어, 위 2번의
`_bundled` 등록을 이깁니다. 테스트가 `_bundled` 가 아니라 활성 디렉토리 사본을 검증하게 되어
"`_bundled` 에서만 작업한다" 는 규율이 조용히 깨집니다.
2. Composer 로더는 `vendorDir` 를 가지면 등록 로더 목록의 맨 앞에 자신을 넣는데, 테스트용 앱
생성이 그 첫 항목에서 base path 를 유추합니다. 이후 테스트의 앱 부팅이 확장 디렉토리에서
`bootstrap/app.php` 를 찾다 실패합니다. (운영 진입점은 base path 를 명시 전달하므로 영향이 없습니다.)
이 결손은 그 패키지를 쓰는 코드 경로를 아무도 테스트하지 않는 동안 드러나지 않습니다. 확장에
제3자 패키지를 추가하면 그 패키지를 실제로 로드하는 테스트를 함께 두고, 로드 실패를 skip 이 아니라
단언 실패로 드러냅니다.
### 주의사항