패키지 분석laravel패키지core

Core 패키지 분석 — 한국 Laravel 개발자 가이드

작성: 라라벨 코리아 (초안)

발행: 2026년 7월 12일

CMS Orbit 코어: Inertia + React로 렌더링되는 서버 기반 Screen/Layout/Field 엔진.

요약

cms-orbit/core v4.0.4는 Laravel + Inertia v3 + React 조합 위에서 동작하는 서버 주도형 관리자 CMS 엔진입니다. Laravel Orchid의 선언형 UI 철학과 Filament의 시각적 언어를 재해석하여 Screen / Layout / Field / Entity 계약을 PHP에서 정의하고 React로 렌더링하는 구조를 채택했습니다. PHP 8.3 이상, Laravel 11–13, Inertia Laravel 3.x가 필수 요건이므로, 도입 전 프로젝트 스택 전반의 버전 확인이 선행되어야 합니다.

핵심 내용

설계 철학: "세 프로젝트의 교집합"

CMS Orbit Core는 기존 오픈소스를 Composer로 의존하지 않으면서도 세 프로젝트의 핵심 아이디어를 명시적으로 계승합니다.

원본 프로젝트	Orbit에 흡수된 것	변경점
Laravel Orchid	Screen / Layout / Field 선언형 계약, 권한·메뉴·전역 검색	Hotwire → Inertia + React 로 렌더링 재매핑
Orchid CRUD	Resource 패턴 (한 파일 CRUD)	Eloquent 모델 비침투적 `Entity` 로 분리
Filament	`fi-*` 시각 토큰, OKLCH 팔레트, 테이블 툴바	PHP 계약은 Orchid 방식 유지, 디자인 토큰만 차용
XpressEngine 3	설정 레지스트리	`orbit_config()` 계층적 폴백(인스턴스 → 전역 → 타입 기본값)

이 접근은 "바퀴를 다시 만든다"는 비판을 받을 수 있지만, 런타임 의존성을 최소화하면서 설계 의도를 명확히 문서화했다는 점에서 장기 유지보수에 유리합니다.

핵심 기능 분석

1. Entity 기반 선언형 CRUD

class PostEntity extends Entity
{
    public function model(): string { return Post::class; }

    public function fields(): array
    {
        return [
            Input::make('title')->title(__('Title'))->required(),
        ];
    }

    public function columns(): array
    {
        return [
            TD::make('id', __('ID'))->sort(),
            TD::make('title', __('Title')),
        ];
    }
}

Eloquent 모델 클래스를 직접 수정하지 않고 Entity 클래스가 관리자 UI 명세를 담당합니다.
EntityRegistry::registerClass()로 등록하면 메뉴·권한·CRUD 라우트가 자동 구성됩니다.
기존 Filament나 Orchid에 익숙한 개발자라면 학습 곡선이 완만한 편입니다.

2. 서버 주도형 UI (Screen / Layout / Field)

PHP 빌더에서 작성한 UI 계약이 JSON으로 직렬화되고, React 컴포넌트가 이를 렌더링합니다. 커스텀 필드나 레이아웃을 추가 등록할 수 있어 확장성이 있습니다. 단, 프런트엔드 빌드 파이프라인(Vite + npm)이 필수이므로 순수 백엔드 PHP 프로젝트에는 적합하지 않습니다.

3. 내장 방문 통계 (Analytics)

별도 SaaS(Google Analytics, Mixpanel 등) 없이 관리자 대시보드에서 방문 통계를 확인할 수 있습니다. 수집 항목과 프라이버시 설계가 주목할 만합니다.

프라이버시 설계 요점:

원본 방문자 UUID는 DB에 저장하지 않으며, HMAC 해시(visitor_hash)만 보관
IP 주소는 IPv4 마지막 옥텟, IPv6 접두사를 익명화
DNT: 1 헤더 존중 옵션 내장
봇 필터링, 관리자 라우트 제외 기능 기본 제공

국가 코드 판별 우선순위:

CF-IPCountry (Cloudflare) → CloudFront-Viewer-Country → Fly-Client-Country
→ MaxMind GeoLite2 (로컬 mmdb) → PHP geoip 확장
→ ORBIT_ANALYTICS_DEV_COUNTRY (로컬 개발 폴백)

주의: Analytics 쿠키(orbit_analytics_visitor, orbit_analytics_visit)는 Laravel EncryptCookies의 예외 목록에 등록되어 암호화되지 않습니다. 미들웨어가 요청마다 쿠키 값을 직접 읽어야 하기 때문입니다. 보안 검토 시 이 점을 명시적으로 확인하세요.

4. orbit:frontend-sync 와 프런트엔드 브리지

orbit:frontend-sync 명령이 vite.config.*의 alias 블록(// ORBIT:ALIASES:START)과 Inertia 페이지 브리지를 자동 생성합니다. 패키지 추가·업그레이드 시마다 이 명령을 실행해야 하며, 수동으로 vite.config를 건드릴 필요가 없습니다.

5. Laravel Boost 연동

boost.json이 존재하는 프로젝트에서는 orbit:install / orbit:sync 실행 시 Orbit 가이드라인이 IDE(Cursor 등) 규칙 파일에 자동 병합됩니다. AI 코딩 도구를 사용하는 팀이라면 이 흐름을 활용할 수 있습니다.

한국 Laravel 개발자에게 미치는 영향

호환성 요건 — 스택 전면 검토 필요

요건	최소 버전	영향
PHP	8.3	PHP 8.1/8.2 프로젝트는 업그레이드 필수
Laravel	11 이상	Laravel 10 이하는 미지원
Inertia Laravel	3.x	Inertia 1.x/2.x 프로젝트는 마이그레이션 필요
Node / npm	Vite 빌드 가능 환경	순수 Blade 프로젝트는 별도 프런트 파이프라인 구성 필요

Inertia v3은 v1/v2와 API 일부가 달라 기존 Inertia 프로젝트를 v4 Orbit에 편입할 때 Inertia 마이그레이션이 병행되어야 합니다.

기존 User 모델 보호

설치 중 orbit:install이 User 모델 덮어쓰기를 시도합니다. 기존 모델을 유지하려면 설치 시 "아니오"를 반드시 선택하고, trait/extends 호환 가이드를 따라야 합니다. 이를 놓치면 기존 인증 로직이 덮어써질 수 있습니다.

Valet / Sail / Docker 환경별 고려사항

Laravel Valet (macOS 로컬)

Node/npm이 설치된 환경이라면 npm run dev로 바로 개발 가능
Analytics 국가 코드는 ORBIT_ANALYTICS_DEV_COUNTRY=KR을 .env에 추가하면 로컬에서 테스트 가능 (APP_ENV=local일 때만 동작)

Laravel Sail (Docker)

Sail 컨테이너 내부에서 npm install && npm run dev 실행 가능
MaxMind GeoLite2 mmdb 파일 경로를 컨테이너 내 절대 경로로 지정해야 함
ORBIT_ANALYTICS_GEOIP_DATABASE_PATH를 Docker 볼륨 마운트 경로에 맞게 설정

프로덕션 (Cloudflare / AWS CloudFront / Fly.io)

CDN/프록시가 국가 헤더(CF-IPCountry, CloudFront-Viewer-Country, Fly-Client-Country)를 전달하는 구조라면 MaxMind 없이도 국가 통계 수집 가능
Cloudflare를 쓰는 국내 프로젝트 대부분은 CF-IPCountry 헤더가 이미 전달되므로 별도 GeoIP 설정 불필요

보안 검토 사항

Analytics 쿠키가 암호화에서 제외되므로, 쿠키 내용을 민감 데이터로 오해하지 않도록 팀 내 공유 필요 (UUID 자체는 민감 정보가 아니나, 운영 정책 확인 권장)
visitor_hash는 HMAC 기반이므로 원본 UUID 역추적이 불가능한 설계 — GDPR/개인정보보호법 준수 여부 검토 시 이 설계를 근거로 활용 가능
관리자 라우트(orbit.*)를 Analytics에서 제외하는 analytics.exclude_admin_routes 옵션 기본값 확인 후 프로덕션 배포

실무 체크리스트

로컬 개발 환경

PHP 버전 확인: php -v → 8.3 이상인지 검증
Laravel 버전 확인: composer show laravel/framework → 11.x 이상
Inertia Laravel 버전 확인: composer show inertiajs/inertia-laravel → 3.x 이상 (없으면 별도 마이그레이션 계획 수립)
Node/npm 설치 확인: node -v, npm -v
.env에 로컬 국가 코드 추가: ORBIT_ANALYTICS_DEV_COUNTRY=KR
ORBIT_DEMO=true (기본값) 확인 후 Demo 섹션에서 필드·레이아웃 둘러보기

설치 절차

# 1. 패키지 설치composer require cms-orbit/core:^4.0# 2. 설치 명령 실행 (User 모델 덮어쓰기 여부 주의)php artisan orbit:install# 3. 관리자 계정 생성php artisan orbit:admin# 4. 프런트엔드 의존성 설치 및 빌드npm installnpm run dev

스테이징 환경

User 모델이 의도대로 유지/교체되었는지 확인
php artisan migrate 후 orbit_analytics_pageviews 테이블 생성 여부 확인
analytics.exclude_admin_routes 설정값 확인 (관리자 페이지뷰가 통계에 포함되지 않는지)
ORBIT_DEMO=false 설정하여 Demo 섹션 비활성화
CDN(Cloudflare 등) 사용 시 국가 헤더 전달 여부 테스트: curl -H "CF-IPCountry: KR" ...
CDN 미사용 시 MaxMind GeoLite2 mmdb 다운로드 및 경로 설정

ORBIT_ANALYTICS_GEOIP_ENABLED=true
ORBIT_ANALYTICS_GEOIP_DATABASE_PATH=/var/www/storage/app/geoip/GeoLite2-Country.mmdb

프로덕션 배포

npm run build 실행 후 Vite 빌드 산출물 확인
패키지 추가/업그레이드 시: php artisan orbit:frontend-sync 실행 (alias 블록 자동 갱신)
Laravel Boost 사용 팀: php artisan orbit:sync 또는 boost:update 실행
Analytics 쿠키 정책 문서 업데이트 (395일 장기 쿠키 포함 고지 여부 확인)
MaxMind GeoLite2 DB 주기적 갱신 스케줄 설정 (월 1회 권장)
ORBIT_DEMO=false 프로덕션 환경 변수 설정 확인

Entity 개발 시 반복 체크

새 Entity 작성 후 EntityRegistry::registerClass() 등록 확인
패키지 Entity는 해당 패키지의 Service Provider가 자동 등록 — 중복 등록 방지
DocumentEntity 활용 시 documents / document_contents 마이그레이션 실행 여부 확인

편집자 주: 이 문서는 cms-orbit/core v4.0.4 README 및 패키지 메타데이터를 기반으로 작성된 초안입니다. 실제 내부 구현 세부 사항은 패키지 소스 코드 및 공식 문서를 통해 재확인하시기 바랍니다. Laravel Boost 연동 부분은 boost.json 존재 여부에 따라 동작이 달라지므로, 해당 패키지의 별도 문서를 병행 검토하세요.