본문 바로가기
← 패키지 목록

Core

인증된 제출자

cms-orbit/core

제출자 이우진
최신 v4.7.9라이센스 MIT배포 2026년 10월 22일
인증DevOps

CMS Orbit 코어: Inertia + React로 렌더링되는 서버 주도형 Screen/Layout/Field 엔진입니다.

CMS Orbit Core

어디서 영감을 받았나요?

Orbit Core는 처음부터 새로 작성한 코드이지만, ref/ 디렉터리에 모아 둔 선행 프로젝트들의 좋은 아이디어를 골라 이어받았습니다. 각 프로젝트에서 무엇을 가져왔는지 짧게 소개합니다.

참고 프로젝트 (ref/)Orbit Core에 담긴 것
Laravel Orchid (platform-master)Screen / Layout / Field 선언형 관리자 UI, 권한·메뉴·필터·전역 검색 등 "백오피스를 PHP로 설명한다"는 철학. Hotwire/Turbo 기반이던 흐름은 Inertia + React로 다시 매핑했습니다.
Orchid CRUD (crud-master)파일 하나로 CRUD를 설명하던 Resource 패턴. Orbit에서는 Eloquent 모델을 건드리지 않도록 **Entity**로 분리해 발전시켰습니다.
Filament (filament-5.7-beta)관리자 UI의 시각적 언어 — fi-* 스타일 섹션·배지·빈 상태, OKLCH 기반 색상 팔레트, 테이블 툴바·탭 필터 등. PHP 계약은 Orchid에서, 화면 표현과 디자인 토큰은 Filament에서 많이 가져왔습니다.
CMS Orbit v3 (cms-orbit)이 저장소의 이전 세대 제품입니다. Orchid + Vue 3 + stancl/tenancy 조합으로 쌓은 CMS 경험, 패키지 구조, 문서형 콘텐츠 아이디어가 v4 Core의 출발점이 되었습니다.
XpressEngine 3 (xpressengine-master)설정 레지스트리와 번들형 확장 모델. orbit_config()의 계층적 값 해석(인스턴스 → 전역 → 타입 기본값)은 XE3의 chain-of-responsibility 폴백에서 영감을 받았습니다.

NOTE

ref/는 런타임 의존성이 아니라 설계 참고용 아카이브입니다. Orbit Core는 위 프로젝트들을 Composer로 가져오지 않으며, Laravel + Inertia v3 위에서 독립 패키지로 동작합니다.


cms-orbit/core는 Laravel용 Orbit 관리자 엔진의 중심 패키지입니다.
PHP에서 정의한 Screen / Layout / Field / Entity 계약을 Inertia + React로 렌더링하여, CRUD 관리자 화면·문서형 콘텐츠·설정 화면·메뉴·권한 구성을 하나의 흐름으로 묶어 줍니다.

무엇을 제공하나요?

  • Entity 기반의 선언형 관리자 CRUD
  • Screen / Layout / Field 기반의 서버 주도형 UI 계약
  • DocumentEntity 기반의 문서형 콘텐츠 엔진
  • orbit_config()와 설정 레지스트리를 통한 사이트 설정 관리
  • Orbit 셸, 메뉴, 브랜딩, Breadcrumb, 검색, 권한 연동
  • 라이트/다크 전환, 레이아웃별 디자인 토큰, 브랜딩 로고/심볼 교체, 파비콘 변형 생성까지 포함한 관리자 테마 시스템
  • 예제 화면과 필드 확장을 바로 확인할 수 있는 Demo 섹션
  • 외부 분석 도구 없이 동작하는 내장 방문 통계(페이지뷰·방문자·국가·리퍼러)

요구사항

  • PHP ^8.4
  • Laravel ^13.0
  • Inertia Laravel ^3.0

설치

composer require cms-orbit/core:^4.0php artisan orbit:install

orbit:install은 다음 작업을 한 번에 처리합니다.

  • 설정·마이그레이션·스텁 게시
  • entities/ 디렉터리와 OrbitProvider 준비
  • Inertia/Vite 연결(orbit:frontend-sync)
  • 프런트 npm 의존성 병합 + npm install + npm run build
  • AI 가이드 배포(orbit:ai)
  • Laravel Boost 자동 갱신(아래 참고)

대화형 설치에서는 announcement / popup / sendgo 같은 가벼운 위성 패키지를 추가로 선택할 수 있습니다(--with=announcement,popup로 비대화형 지정 가능, saas/blog는 제외).

NOTE

npm 빌드를 건너뛰려면 php artisan orbit:install --skip-npm을 사용하세요. npm이 설치되어 있지 않으면 자동 빌드를 건너뛰고 수동 실행 방법을 안내합니다.

설치 / CI 체크리스트

항목권장
기존 User 모델덮어쓰기 확인에서 아니오를 선택하거나, CI에서는 --no-interaction(덮어쓰지 않음) 사용
CI 빌드php artisan orbit:install --no-interaction --skip-npm 실행 후 별도로 npm ci && npm run build
위성 패키지php artisan orbit:install --with=announcement,popup 또는 설치 중 multiselect로 선택
의존성 감사CI에 composer audit 포함

설치 직후 관리자 계정을 만들려면 다음 명령을 실행합니다.

php artisan orbit:admin

프런트 자산을 직접 개발/빌드하려면(선택 사항):

npm installnpm run dev   # 또는 npm run build

Laravel Boost

상황할 일
Laravel Boost 미설치orbit:ai만 실행 — AGENTS.md, .cursor/rules 등에 Orbit 가이드를 배포합니다.
Boost 설치됐지만 최초 설정 전php artisan boost:install을 1회 실행합니다.
Boost 이미 설정됨 (boost.json 존재)orbit:install / orbit:sync가 cms-orbit 패키지를 Boost에 등록하고 boost:update를 자동 실행합니다.

각 cms-orbit/* 패키지의 resources/boost/guidelines/와 resources/boost/skills/는 위 흐름을 통해 IDE에 병합됩니다. 패키지를 추가하거나 업그레이드한 뒤에는 orbit:frontend-sync와 함께 orbit:sync 또는 boost:update를 실행하세요.

호스트 설정 (수동 작업 최소화)

작업필수 여부설명
php artisan orbit:install필수 (최초 1회)설정, 마이그레이션, User/OrbitProvider 스텁, 프런트 브리지
php artisan orbit:frontend-sync패키지 추가/제거 시resources/orbit/frontend.json 기준으로 Vite alias·Inertia 브리지·orbit.css를 생성하고, 필요한 npm 의존성을 package.json에 병합
package.json 수동 의존성 추가불필요frontend.json의 dependencies 중 누락분만 sync가 병합(기존 버전은 보존)
npm install && npm run build 수동 실행불필요 (install이 자동 수행)--skip-npm을 쓰거나 npm이 없을 때만 수동 실행
php artisan orbit:sync선택설정/스텁만 안전하게 재동기화 (User 모델은 기본적으로 덮어쓰지 않음)
vite.config.* 수동 alias불필요orbit:frontend-sync가 // ORBIT:ALIASES:START 블록을 관리
resources/js/pages/* 수동 re-export불필요위 sync 명령이 패키지 페이지 브리지를 생성
React 스타터킷불필요순정 Laravel에 resources/js/app.tsx가 없으면 sync가 React 진입점과 Vite 플러그인을 준비합니다. 기존 app.js와 호스트가 소유한 app.tsx는 보존합니다.
Wayfinder 설치·생성 설정불필요Core가 Composer 의존성을 선언하며, sync가 필요한 npm 의존성과 Vite 플러그인을 연결합니다. 빌드 시 관리자 라우트를 생성합니다.
Entity를 app/Orbit/OrbitProvider에 등록호스트 전용 Entity 사용 시패키지 Entity는 서비스 프로바이더가 자동 등록합니다. entities/ 스캔은 코어가 런타임 PSR-4로 연결하므로 호스트 composer.json에 "Entities\\": "entities/"를 추가할 필요가 없습니다.

기존 Laravel User 모델을 유지하려면 설치 중 덮어쓰기 확인에서 아니오를 선택하고, 안내되는 trait/extends 호환 가이드를 따르세요.

호스트 routes/orbit.php의 라우트 이름

패키지 자체의 라우트 파일은 orbit. 이름 접두사 아래 등록되지만, 호스트의 routes/orbit.php는 기본적으로 접두사를 받지 않습니다. domain·prefix·미들웨어는 동일하게 적용되므로 이름만 다릅니다.

// routes/orbit.php (호스트) Route::screen('dashboard', ConsoleDashboardScreen::class)->name('dashboard'); // 등록되는 이름: "dashboard"

오류가 나지 않기 때문에, config('orbit.index')를 orbit.dashboard로 두거나 breadcrumb에서 $trail->parent('orbit.dashboard')를 사용할 때 "Route not defined" 오류로 처음 드러납니다. 이를 해결하는 방법은 두 가지가 있습니다.

1) 이름에 직접 접두사를 붙입니다 (기본 동작이며 추가 설정이 필요 없습니다)

Route::screen('dashboard', ConsoleDashboardScreen::class)->name('orbit.dashboard');

2) 패키지 파일과 동작을 맞춥니다 — config/orbit.php에서 옵션을 켜면 호스트 파일의 라우트도 orbit. 접두사를 받습니다.

'host_routes' => [ 'name_prefix' => true, // 또는 ORBIT_HOST_ROUTES_NAME_PREFIX=true ],

기본값이 false인 이유는, 이미 1번 방식으로 접두사를 직접 적어 둔 호스트에서 이 옵션을 켜면 이름이 orbit.orbit.dashboard가 되기 때문입니다. 2번 방식으로 옮길 때는 호스트 라우트 파일의 ->name('orbit.…')도 함께 제거하세요.

php artisan vendor:publish --tag=orbit-assetsphp artisan vendor:publish --tag=orbit-config

빠른 시작

1. Entity 등록

Orbit는 EntityRegistry에 등록된 Entity를 기준으로 관리자 메뉴, 권한, CRUD 라우트와 화면을 구성합니다. 호스트 전용 Entity는 App\Orbit\OrbitProvider에 등록하세요. AppServiceProvider에 흩어 두지 않는 것이 좋습니다.

orbit:install이 만들어 주는 기본 형태는 다음과 같습니다.

// app/Orbit/OrbitProvider.php public function boot(): void { Orbit::registerEntities(base_path('entities')); }

개별 클래스를 명시해서 등록할 수도 있습니다.

use App\Orbit\Entities\PostEntity; use CmsOrbit\Core\Support\Facades\Orbit; Orbit::registerEntities([PostEntity::class]);

패키지가 제공하는 Entity(announcement, popup 등)는 해당 패키지의 서비스 프로바이더가 자동으로 등록합니다.

슈퍼 관리자 역할의 권한 맵은 등록된 권한 fingerprint가 바뀌면 기본적으로 자동 동기화됩니다(orbit.permissions.auto_sync_super_admin, 수동 실행: php artisan orbit:fresh-super-admin-role).

2. Entity 정의

간단한 Entity는 다음과 같은 형태로 시작할 수 있습니다.

use App\Models\Post; use CmsOrbit\Core\Foundation\Entity\Entity; use CmsOrbit\Core\Screen\Fields\Input; use CmsOrbit\Core\Screen\TD; 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')), ]; } }

3. Entity vs DocumentEntity

상황사용할 클래스
posts, members처럼 전용 Eloquent 모델·테이블이 있는 경우Entity
공지·팝업·배너처럼 에디터 기반이며 공용 documents 테이블을 쓰는 경우DocumentEntity

4. 문서형 콘텐츠 만들기

공지사항, 팝업처럼 공용 문서 테이블을 활용하는 콘텐츠는 DocumentEntity를 상속하면 됩니다. Orbit가 다국어 문서 레이어, CRUD 흐름, 공개 URL 연결에 필요한 기반을 제공합니다.

5. 설정 화면과 Demo 확인

설치 후 개발 환경에서는 Demo 섹션이 자동으로 등록되어, 필드·레이아웃·차트·설정 예제를 바로 둘러볼 수 있습니다. 필요하면 ORBIT_DEMO=false 또는 orbit.demo.enabled 설정으로 끌 수 있습니다.

핵심 개념

Entity

Eloquent 모델을 Orbit 관리자 화면에 연결하는 선언형 설명자입니다. 필드, 컬럼, 보기(legend), 메뉴 섹션, 정렬 순서, 권한 포인트를 한 클래스에 모을 수 있습니다.

Screen / Layout / Field

PHP 빌더에서 만든 계약을 JSON으로 직렬화하면 React 컴포넌트가 이를 렌더링합니다. 기본 필드로 충족되지 않는 경우에는 커스텀 필드나 레이아웃을 추가로 등록할 수 있습니다.

Document 엔진

문서형 콘텐츠는 공용 documents / document_contents 구조를 사용합니다. 공지, 팝업, 배너처럼 에디터 기반 콘텐츠를 패키지 단위로 확장하기에 알맞습니다.

Orbit 셸과 디자인 토큰

Orbit 셸은 상단바, 사이드바, 카드, 페이지 배경을 CSS 변수 기반 색상 토큰으로 렌더링합니다. 따라서 셸 테마를 맞출 때 개별 컴포넌트 클래스를 일일이 덮어쓰지 않아도 공통된 톤을 쉽게 유지할 수 있습니다.

브랜딩 업로드와 파비콘

브랜딩 설정에서는 라이트/다크 로고와 심볼을 각각 연결할 수 있고, 파비콘 이미지는 크롭한 뒤 업로드할 수 있습니다. PNG 파비콘을 올리면 브라우저 메타 링크에 쓸 수 있는 apple-touch-icon, 192/512 PNG, 웹 매니페스트까지 함께 생성되도록 설계되어 있습니다.

방문 통계 (Analytics)

Orbit Core는 CaptureAnalytics 미들웨어와 orbit_analytics_pageviews 테이블로 가벼운 방문 분석 기능을 내장하고 있습니다. 별도의 SaaS 없이 페이지뷰·방문자·리퍼러·디바이스·국가를 수집하며, 관리자 대시보드와 Visitor Records 화면에서 확인할 수 있습니다.

수집 항목

각 페이지뷰(GET HTML/Inertia 응답)마다 다음 항목을 저장합니다.

항목설명
페이지page_path, route_name, route_uri, 유입(is_entrance)
방문자 식별visitor_hash(쿠키 UUID의 HMAC), visit_token(30분 세션)
사용자로그인 시 user_id, user_type, user_name, user_email 귀속
클라이언트browser_family, device_type, user_agent, is_bot
유입referrer_host(동일 호스트는 Direct)
네트워크ip_address(IPv4 마지막 옥텟·IPv6 접두사 익명화), country_code(ISO 3166-1 alpha-2)
범위instance_id(멀티 인스턴스 앱), visited_on

원본 방문자 UUID는 DB에 저장하지 않고 visitor_hash만 보관합니다. HMAC 키는 기본적으로 APP_KEY(config('app.key'))입니다. APP_KEY를 로테이션하면 기존 visitor_hash와의 연속성이 끊어집니다.

트래픽이 많은 환경에서는 ORBIT_ANALYTICS_QUEUE=true(orbit.analytics.queue)로 페이지뷰 INSERT를 큐로 넘길 수 있습니다. 다만 쿠키 발급은 여전히 동기로 처리됩니다.

수집하지 않는 요청

기본값 기준으로 아래 요청은 집계에서 제외됩니다.

  • 관리자 라우트 — analytics.exclude_admin_routes가 켜져 있으면 orbit.* 라우트는 제외됩니다.
  • 봇 — User-Agent 패턴 또는 analytics.filter_bots 설정으로 걸러냅니다.
  • Do Not Track — DNT: 1 헤더가 있으면 제외됩니다(analytics.respect_do_not_track).
  • GET 이외의 요청 — POST·PUT 등 변경 요청은 제외됩니다.
  • HTML이 아닌 응답 — JSON API(Inertia X-Inertia 요청은 제외 대상 아님), 3xx/4xx/5xx 응답은 집계하지 않습니다.
  • 라우트 미매칭 — 라우트가 매칭되지 않은 요청은 제외됩니다.
  • 수집 비활성 — analytics.enabled가 꺼져 있거나 orbit_analytics_pageviews 테이블이 없을 때는 수집하지 않습니다.

Visitor Records (관리자)

Users & Roles 섹션의 Visitor Records Entity에서 원시 페이지뷰를 조회할 수 있습니다.

  • 목록 — 최근 30일 메트릭 카드(페이지뷰, 인기 페이지·리퍼러·디바이스), 검색, 테이블 필터(방문 기간, Audience: 전체/게스트/로그인 사용자)
  • 상세 — 방문·방문자·네트워크 정보와, 동일한 visitor_hash의 Other visits by this visitor 이력
  • Scope — instance_id가 null이면 Host, 값이 있으면 Instance 배지로 표시

인스턴스 컨텍스트가 있는 관리자에서는 해당 인스턴스의 기록과 호스트(instance_id가 null) 기록을 함께 볼 수 있습니다.

게스트 → 로그인 귀속

로그인에 성공하면(Login 이벤트) 다음 순서로 처리합니다.

  1. 귀속 — 현재 orbit_analytics_visit 토큰(없으면 최근 10분 이내의 visitor_hash)으로 저장된, 아직 귀속되지 않은 페이지뷰에 사용자 정보를 채웁니다.
  2. 쿠키 교체 — rotateIdentityAfterLogin()으로 방문자·방문 쿠키를 새 UUID로 교체하여, 로그인 전후 세션을 분리합니다.

로그아웃하면 forgetIdentityAfterLogout()으로 두 쿠키를 삭제합니다. 로그인·로그아웃 감사 로그는 Authentication & Security 설정 그룹과 연동된 활동 로그에도 남습니다.

쿠키

쿠키수명용도
orbit_analytics_visitor395일장기 방문자 식별(DB에는 HMAC 해시만 저장)
orbit_analytics_visit30분단일 방문(세션) 구분, 입장 페이지 판별

두 쿠키는 HttpOnly, SameSite=Lax, 경로 /로 설정됩니다. Laravel EncryptCookies 미들웨어의 예외 목록에 등록되어 있어 암호화되지 않습니다. 미들웨어가 요청마다 쿠키 값을 읽어야 하기 때문입니다.

국가 코드

AnalyticsGeoLocator가 국가를 결정하며, 우선순위는 다음과 같습니다.

  1. 프록시/엣지 헤더 — CF-IPCountry(Cloudflare), CloudFront-Viewer-Country, X-AppEngine-Country, Fly-Client-Country, X-Vercel-IP-Country 등. ORBIT_ANALYTICS_COUNTRY_HEADERS로 헤더를 추가로 지정할 수 있습니다.
  2. MaxMind GeoIP — 로컬 .mmdb DB로 공인 IP를 조회합니다(IP 원본은 저장하지 않음).
  3. PHP geoip 확장(선택) — geoip_country_code_by_name()을 사용합니다(IP 원본은 저장하지 않음).
  4. 로컬 개발 폴백 — APP_ENV=local일 때만 ORBIT_ANALYTICS_DEV_COUNTRY(예: KR)가 적용됩니다.
Cloudflare vs GeoIP
방식적합한 경우장점단점
Cloudflare 등 엣지 헤더CDN·리버스 프록시 뒤에 두는 프로덕션추가 패키지·DB가 필요 없고, 요청당 조회 비용도 없음Cloudflare 같은 인프라가 필요
MaxMind GeoIP자체 서버·VPS, 헤더가 없는 환경인프라에 독립적이며 오프라인 조회 가능DB 다운로드·갱신이 필요하고 MaxMind 무료 계정 등록이 필요
개발 폴백Valet·localhost설정 한 줄로 테스트 가능local 환경에서만 동작

프로덕션에서는 Cloudflare, CloudFront, Fly.io, Vercel 등 앞단에서 국가 헤더가 전달되도록 구성하는 것을 권장합니다. CDN/프록시 없이 직접 서비스한다면 MaxMind GeoIP를 활성화하세요.

MaxMind GeoLite2 설정

GeoIP는 요청 시점의 전체 IP로만 조회하며, DB에 저장할 때는 기존처럼 익명화된 IP만 저장합니다.

  1. MaxMind에서 무료 계정을 만듭니다(GeoLite2 End User License Agreement 동의 필요).
  2. 계정에서 License key를 발급합니다.
  3. GeoLite2 Country DB를 다운로드합니다.
mkdir -p storage/app/geoip curl -L "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=YOUR_LICENSE_KEY&suffix=tar.gz" \ | tar -xz --strip-components=1 -C storage/app/geoip --wildcards '*/GeoLite2-Country.mmdb'
  1. .env에 다음을 추가합니다.
ORBIT_ANALYTICS_GEOIP_ENABLED=true ORBIT_ANALYTICS_GEOIP_DATABASE_PATH=/absolute/path/to/storage/app/geoip/GeoLite2-Country.mmdb

ORBIT_ANALYTICS_GEOIP_DATABASE_PATH를 생략하면 기본값인 storage/app/geoip/GeoLite2-Country.mmdb를 사용합니다.

  1. DB는 MaxMind 정책에 따라 주기적으로 갱신하세요(권장: 월 1회). cron 예시는 다음과 같습니다.
0 3 1 * * curl -L "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=YOUR_LICENSE_KEY&suffix=tar.gz" | tar -xz --strip-components=1 -C /path/to/storage/app/geoip --wildcards '*/GeoLite2-Country.mmdb'

로컬 개발(헤더·GeoIP DB가 없을 때) — ORBIT_ANALYTICS_DEV_COUNTRY=KR로 동작을 시뮬레이션하거나, MaxMind 테스트 DB(packages/cms-orbit/core/tests/fixtures/GeoIP2-Country-Test.mmdb)를 경로로 지정한 뒤 81.2.69.160 같은 공인 IP로 조회를 확인할 수 있습니다.

Valet·localhost처럼 위 방법을 하나도 쓰지 않으면 **country_code는 Unknown(null)**으로 표시됩니다.

설정

Orbit 설정 화면에서 인스턴스별로 값을 덮어쓸 수 있습니다.

Analytics (방문 통계)

키기본값설명
analytics.enabledtrue페이지뷰 수집 on/off
analytics.exclude_admin_routestrueOrbit 관리자 라우트 제외
analytics.filter_botstrue봇 User-Agent 제외
analytics.respect_do_not_tracktrueDNT 헤더 존중
analytics.retention_days90보존 기간(일). 만료된 기록은 하루 1회 자동 삭제

환경 변수(config/orbit.php):

ORBIT_ANALYTICS_QUEUE=false ORBIT_AUTO_SYNC_SUPER_ADMIN=true ORBIT_ANALYTICS_DEV_COUNTRY=KR ORBIT_ANALYTICS_COUNTRY_HEADERS=X-Custom-Country ORBIT_ANALYTICS_GEOIP_ENABLED=true ORBIT_ANALYTICS_GEOIP_DATABASE_PATH=/absolute/path/to/GeoLite2-Country.mmdb

orbit.analytics.queue가 true이면 RecordPageview Job으로 INSERT를 큐에 넘깁니다(기본값 false, 동기 처리).

Authentication & Security (인증 및 보안) — 방문 통계 전용 스위치는 없지만, 로그인·로그아웃 시 방문 귀속과 쿠키 교체·삭제, 로그인 잠금(auth_security.*) 등 인증 이벤트가 방문 기록과 함께 동작합니다.

호스트 vs 인스턴스

instance_context()가 없는 요청(예: orbit.test 호스트 전역 트래픽)은 instance_id = null로 저장됩니다. 멀티 테넌트 인스턴스 URL에서는 해당 인스턴스 ID가 붙습니다. Visitor Records의 Scope 열과 필터로 구분할 수 있습니다.

마이그레이션

php artisan orbit:install(또는 php artisan migrate)을 실행하면 패키지 마이그레이션이 orbit_analytics_pageviews 테이블과 사용자 귀속·네트워크(ip_address, country_code)·user_agent 컬럼을 순차적으로 적용합니다. 기존 설치에 Core를 업그레이드할 때는 마이그레이션만 실행하면 됩니다.

테스트와 점검

composer validate --no-check-publish

호스트 앱 전체 동작까지 함께 확인하려면, 루트 애플리케이션에서 타입 체크와 Laravel 테스트를 함께 실행하는 것을 권장합니다.

업데이트 노트

4.6.2

  • orbit:frontend-sync가 bare @cms-orbit/core import에 필요한 TypeScript 경로를 자동으로 기록합니다 (#9). 업데이트 후 php artisan orbit:frontend-sync를 실행하세요. 주석이 들어 있는 tsconfig.json은 명령이 출력하는 경로 블록을 직접 반영해야 합니다.
  • 4.6.1에서 누락되었던 laravel/octane의 suggest 선언을 추가하고, 분리되어 있던 릴리스 이력을 main에 통합했습니다.

4.6.1

  • laravel/octane을 suggest에 추가했습니다: FoundationServiceProvider가 Laravel\Octane\Events\RequestReceived를 참조하지만 Event::listen의 클로저 타입으로만 쓰이므로 리플렉션이 문자열만 읽고, octane이 설치되지 않아도 정상 동작합니다(core 테스트가 octane 없이 통과). 하드 의존성이 아니므로 require가 아니라 suggest가 맞으며, 선언이 없어 관계 자체가 문서화되지 않았던 부분을 채웠습니다.

4.6.0

  • OrbitAccess 라우팅 리졸버 (#1) — 패널의 도메인·접두사·미들웨어를 요청마다 해석하고 컨테이너 싱글턴으로 바인딩합니다. 위성 패키지가 서브클래스로 교체해 마운트 지점을 바꿀 수 있습니다 (cms-orbit/saas의 {endpoint}/settings).
  • PostgreSQL 관리자 500 오류 수정 (#4) — 브랜드 자산 경로를 첨부 ID로 조회하면서 트랜잭션이 깨지고, 이후 모든 쿼리가 25P02로 실패하던 문제를 고쳤습니다.
  • Model::shouldBeStrict()를 쓰는 호스트에서 관리자가 죽는 문제 수정 (#5), orbit:install의 OrbitProvider 미등록 수정 (#6), 호스트 tsc를 막던 타입 오류 2건 수정 (#2).
  • safe()가 삼킨 예외를 report()합니다 (#7) — 폴백은 유지하되 원인이 로그에 남습니다. 위 #4·#5는 이 문제 때문에 원인을 찾기 어려웠습니다.
  • orbit:frontend-sync가 tsconfig paths를 동기화합니다 (#3) — 빌드는 통과하는데 types:check만 실패하던 문제를 해결했습니다.
  • 패키지 자체 타입 게이트 도입 (#3) — npm run types:check. 도입하자마자 실제 결함 3건을 추가로 찾아냈습니다.
  • orbit.host_routes.name_prefix opt-in (#8) — 호스트 routes/orbit.php에도 orbit. 접두사를 붙입니다. 기본값은 false입니다.
  • CI 워크플로 추가 — PHP 8.4·8.5 게이트와 태그 버전 일치 검사.
  • 테스트 3개 → 20개.

4.5.0

  • laravel/framework ^11.0 || ^12.0 || ^13.0 → ^13.0: Laravel 13 전용으로 범위를 좁혔습니다.
  • 왜 좁혔나: Pest 5를 채택한 4.4.0(패키지별로는 4.1.0)부터 pest-plugin-laravel 5가 laravel/framework ^13.23을 요구하게 되어, 이 저장소의 테스트가 Laravel 13으로만 해석됩니다. 즉 Laravel 11·12 호환성을 더 이상 검증할 수 없는 상태에서 그 범위를 계속 표방하고 있었습니다. 검증되지 않는 지원 범위를 제약 조건에 남겨 두지 않기로 했습니다.
  • Laravel 11·12 사용자는 업그레이드가 필요합니다. 이번 변경은 실제로 지원 구성을 제거하므로, PHP 하한을 올린 경우와 달리 사용자에게 직접 영향을 줍니다. Laravel 13으로 올리거나 이전 버전에 머물러야 합니다.
  • 함께 검토했지만 좁히지 않은 항목: laravel/scout ^10.0 || ^11.0(scout 10.25.0이 Laravel 13을 지원함을 실측으로 확인), inertiajs/inertia-laravel ^3.0, tabuna/breadcrumbs ^5.0, watson/active ^7.0 — 모두 Laravel 13에서 정상적으로 해석됩니다.

4.4.0

  • PHP 제약 ^8.3 → ^8.4: PHP 8.3 환경에서는 더 이상 설치되지 않습니다.
  • pestphp/pest ^5.0, pestphp/pest-plugin-laravel ^5.0, orchestra/testbench ^11.0 (모두 require-dev). Pest 5가 PHP ^8.4를 요구하는 것이 PHP 하한을 올린 이유입니다. testbench 범위를 좁힌 이유는 pest-plugin-laravel 5가 laravel/framework ^13.23을 요구하여 testbench 9(Laravel 11)·10(Laravel 12)이 Pest 5와 공존할 수 없기 때문입니다.
  • 프로덕션 의존성은 하나도 바뀌지 않았습니다. 직접 의존성 20개를 전수 대조했고, PHP 하한 상향으로 새로 열린 것은 위 두 dev 패키지뿐입니다. 나머지 18개는 이미 ^8.3에서 최신 버전을 받고 있었습니다. 이번 상향은 기능 확보가 아니라 장기적인 정리 차원입니다.
  • 사용자의 Laravel 11·12 지원은 유지됩니다 (^11.0 || ^12.0 || ^13.0). 다만 이 저장소의 테스트는 Laravel 13으로만 해석되므로, Laravel 11·12 호환성은 로컬 테스트로 검증되지 않습니다.

4.3.0

  • intervention/image ^3.0 → ^4.0: v4에서 이미지 API 이름이 바뀌어 MediaLibrary의 호출 4곳을 마이그레이션했습니다 — ImageManager::read() → decodeBinary(), encodeByPath() → encodeUsingPath(), encodeByMediaType() → encodeUsingMediaType()(2곳). v4는 intervention/gif ^5를 함께 요구합니다. 자체 코드에서 Intervention\Image v3 API를 직접 사용하는 호스트는 함께 마이그레이션해야 합니다. intervention/image를 직접 선언하지 않은 호스트는 전이 의존성으로 자동 상향되므로 영향을 받지 않습니다.

  • 테스트 기반 도입: core 최초의 자동 테스트입니다. phpunit.xml, testbench 하네스, MediaLibrary 이미지 파이프라인 테스트 3개(최대 폭 초과 시 축소 / 한계 이하이면 원본 유지 / branding+favicon 파비콘 변형 5종 + webmanifest)를 추가했습니다. 기록된 치수만 믿지 않고 디스크에 저장된 실제 바이트를 다시 디코딩해 크기를 확인합니다. processImage()가 예외를 report()로 삼키기 때문에 저장본을 검증하지 않으면 인코딩 실패가 조용히 지나가기 때문입니다. 실제로 v3 API 이름으로 되돌렸을 때 테스트가 실패하는 것까지 확인했습니다.

    composer install && vendor/bin/pest

4.7.0 호환성 업데이트

기존 호스트는 다시 빌드하기 전에 프런트엔드 의존성 제약을 먼저 업데이트하세요.

npm install @blocknote/core@^0.55 @blocknote/react@^0.55 @blocknote/mantine@^0.55 cropperjs@^2.2npm install -D @vitejs/plugin-react@^6.1php artisan orbit:frontend-syncnpm run build

React Compiler를 이미 설정해 둔 경우에는, 플러그인에서 제거된 babel 옵션을 @rolldown/plugin-babel과 @vitejs/plugin-react의 babel({ presets: [reactCompilerPreset()] })로 교체하세요. 새로 만든 Laravel 호스트는 orbit:install이 자동으로 설정합니다.

Socialite 5.31 이상은 Guzzle 8을 지원하므로, 아래 4.2.0에 적힌 Guzzle 다운그레이드 제약은 더 이상 적용되지 않습니다. Apple 로그인은 socialiteproviders/apple:^6.1과 HTTPS 환경에서 설치하세요. Core는 Apple의 POST 콜백을 수락하며, 호스트의 세션 쿠키 정책을 바꾸지 않고 암호화된 Secure/HttpOnly/SameSite=None 브라우저 nonce 쿠키를 검증합니다.

4.2.0

  • socialite를 선택 의존성으로 전환 (BREAKING): laravel/socialite와 socialiteproviders/*를 require에서 suggest로 옮겼습니다.

    새 Laravel 13 프로젝트는 guzzle 8.1을 lock에 고정합니다. 그런데 laravel/socialite는 어느 버전도(dev-master 포함) guzzle ^6.0|^7.0만 허용합니다. 그래서 core가 socialite를 하드 require 하는 동안에는 composer require cms-orbit/core가 항상 실패했고, -W로 guzzle을 7로 강제 다운그레이드해야만 설치할 수 있었습니다.

    코드는 이미 socialite를 선택적으로 다루고 있었습니다. 참조는 두 곳뿐이고 둘 다 가드가 걸려 있습니다 — AuthServiceProvider::registerSocialiteProviders()는 SocialiteWasCalled가 없으면 조기 반환하고, SocialLoginController는 abort_unless(class_exists(Socialite::class), 500)로 런타임에만 막습니다. Socialite 타입을 시그니처에 쓴 곳은 없습니다. 즉 매니페스트만 코드보다 강한 제약을 걸고 있었던 것입니다.

    이제 -W 없이 설치되며 guzzle 8.1이 그대로 유지됩니다.

  • 소셜 로그인을 사용하는 호스트는 직접 선언해야 합니다:

    composer require laravel/socialite socialiteproviders/manager \  socialiteproviders/kakao socialiteproviders/apple -W

    선언하지 않으면 소셜 로그인 라우트만 500을 반환하고 나머지 기능은 영향을 받지 않습니다. 여기서 -W가 필요한 이유는 그대로입니다 — socialite를 실제로 설치하는 순간 guzzle이 7로 내려갑니다. 상류가 guzzle 8을 지원할 때까지는 피할 수 없지만, 그 비용을 이제 소셜 로그인을 쓰는 프로젝트만 부담하게 됩니다.

4.1.0

  • PHP 제약 ^8.3 복구: 게시된 태그는 모두 ^8.3이었으나 main에서는 ^8.2로 내려가 있었습니다. Laravel 13은 PHP ^8.3을 요구하므로, php ^8.2 + laravel/framework ^13 조합은 PHP 8.2 환경에서 조용히 Laravel 11을 설치합니다.
  • tabuna/breadcrumbs ^4.0 || ^5.0 || ^6.0 → ^5.0: ^6.0은 존재하지 않는 버전이었습니다. 최신 5.0.0이 Laravel 10~13을 지원합니다.
  • laravel/pint ^1.14 → ^1.30 (1.30이 PHP ^8.3을 요구).
  • 릴리스 파이프라인 도입: .githooks/pre-push가 composer.json의 version 필드와 태그 이름이 어긋난 태그의 푸시를 차단합니다. cms-orbit/core의 4.0.8 태그가 version: 4.0.7로 만들어지는 바람에 Packagist가 아무 오류 없이 그 태그를 무시했고, 4.0.8이 게시되지 않았다는 사실을 아무도 알지 못한 사고가 있었기 때문입니다. bin/release <버전>은 version 갱신·검증·커밋·태그·푸시를 한 번에 묶어 이런 불일치를 원천 차단하며, cms-orbit/* 의존성이 실제로 Packagist에 게시되어 있는지 Composer 리졸버로 확인합니다. 저장소를 클론해 composer install을 실행하면 core.hooksPath가 자동으로 설정됩니다.
  • intervention/image는 ^3.0 유지: v4가 PHP ^8.3을 요구하므로 이제 설치할 수는 있지만, core가 쓰는 API 세 개의 이름이 모두 바뀝니다 (ImageManager::read() → decode(), encodeByPath() → encodeUsingPath(), encodeByMediaType() → encodeUsingMediaType()). 3.11.8은 계속 지원되고 보안 권고도 없으므로, 테스트가 없는 상태에서 썸네일·이미지 변환 경로를 건드리지 않기로 했습니다.

4.0.7

  • orbit:admin 로그인 정보 안내: 관리자를 생성한 뒤 로그인에 사용할 아이디와 비밀번호를 출력합니다. 비밀번호를 비워 두면 기본값 orbit1234가 사용되는데, 이를 명시적으로 보여 주어 "입력한 정보와 일치하는 사용자를 찾을 수 없습니다"라는 메시지를 오해하는 문제를 방지합니다. (보안상 로그인 실패 메시지는 계정이 없는 경우와 비밀번호가 틀린 경우를 구분하지 않습니다. 비밀번호를 비워 두고 만들었다면 orbit1234로 로그인하세요.)

4.0.6

  • npm run dev 즉시 실행 가능: orbit:frontend-sync가 vite.config.*에 alias 블록을 주입할 때 import { fileURLToPath } from 'node:url';도 자동으로 추가합니다. 순정 스타터킷의 vite.config.ts에는 해당 import가 없어 ReferenceError: fileURLToPath is not defined 오류로 dev 서버가 뜨지 않던 문제를 해결했습니다. (이미 import가 있으면 중복해서 추가하지 않습니다.)
  • 참고 (4.0.5 미만에서 올라오는 경우): 로그인 화면의 Target class [App\Http\Middleware\RequirePasswordChange] does not exist 오류는 4.0.5부터 미들웨어가 패키지로 이관되어 해결됩니다. 이미 config/orbit.php를 게시한 프로젝트라면 php artisan vendor:publish --tag=orbit-config --force로 설정을 갱신하세요.

4.0.5

  • 순정 Laravel + Core만으로 관리자 구동: Inertia 공유 데이터(메뉴·섹션·브랜딩·flash·알림·미디어·i18n)와 루트 뷰(orbit::orbit.app)를 패키지 내부로 이관했습니다. 이제 호스트의 app/Http/Middleware/HandleInertiaRequests.php나 resources/views/app.blade.php에 Orbit 전용 코드를 넣지 않아도, 새 ShareOrbitInertia 미들웨어가 Orbit 라우트 그룹에서 관리자 셸 props를 주입합니다. (기존에는 이 로직이 호스트에 있어야 해서, 순정 설치 시 메뉴·Entity·스타일이 비어 보이는 문제가 있었습니다.)
  • User 프레젠터 패키지화: 베이스 User 모델이 참조하던 호스트 클래스 App\CmsOrbit\Core\Presenters\UserPresenter에 대한 의존을 제거하고, 패키지 내부의 CmsOrbit\Core\Foundation\Presenters\UserPresenter(글로벌 검색 Searchable 구현)로 대체했습니다.
  • 강제 비밀번호 변경 스택 패키지화: RequirePasswordChange 미들웨어, ForcePasswordController, UpdateForcedPasswordRequest, orbit/auth/force-password 페이지를 코어로 이관했습니다.
  • 자체 완결형 스타일: orbit:frontend-sync가 호스트에 resources/css/orbit.css를 생성하고 패키지가 소유한 디자인 토큰(orbit-theme.css)을 import 합니다. 호스트의 app.css를 수정할 필요가 없습니다.
  • orbit:frontend-sync 안정화: vite.config.*에 resolve.alias 블록이 없어도 자동으로 생성하며, orbit.css를 Vite 입력에 등록합니다.

라이선스

MIT