README

cms-orbit/popup은 Orbit 문서 엔진 위에 구축된 팝업 패키지입니다.
관리자에서는 팝업 콘텐츠를 문서처럼 관리하고, 프런트에서는 활성 팝업만 골라 오버레이로 띄울 수 있습니다.

주요 기능

cms-orbit/core 기반 문서형 팝업 콘텐츠
Orbit 관리자 CRUD 자동 등록
노출 기간(started_at, ended_at) 관리
"오늘 하루 보지 않기"를 위한 ignore_days 지원
스타일 JSON(styles) 기반 오버레이 커스터마이징
활성 팝업 조회 API와 OrbitPopups React 컴포넌트 제공

설치

composer require cms-orbit/popup:^4.0
php artisan migrate
php artisan orbit:frontend-sync   # orbit:install 직후라면 생략 가능
npm run dev                       # OrbitPopups 컴포넌트 개발 시

cms-orbit/core가 먼저 설치·설정(orbit:install)되어 있어야 합니다.

Laravel Boost

이 패키지는 resources/boost/guidelines/popup.md, resources/boost/skills/popup-development/를 제공합니다.

Boost 최초 설정: 호스트에서 php artisan boost:install 1회
이후: orbit:install / orbit:sync가 이 패키지를 Boost에 등록하고 boost:update 실행 (Boost가 이미 설정된 경우)

호스트 설정

작업	필수 여부
`composer require cms-orbit/popup` + `php artisan migrate`	필수
`php artisan orbit:frontend-sync`	필수 (`@cms-orbit/popup` alias)
레이아웃에 `<OrbitPopups />` 1회 렌더	필수 (어느 공개 레이아웃에 띄울지는 호스트가 선택)
API 라우트 수동 등록	불필요

빠른 시작

1. 관리자에서 팝업 작성

관리자 화면에서 제목, 본문, 노출 시작/종료 시각, 다시 보지 않기 일수, 타이틀 노출 여부, 스타일 JSON을 관리할 수 있습니다.

2. 레이아웃에 오버레이 연결

호스트 레이아웃에 OrbitPopups를 한 번만 렌더링하면, 현재 시각 기준으로 활성 상태인 팝업을 자동 조회해 표시합니다.

import { OrbitPopups } from '@cms-orbit/popup';

export function AppShell() {
    return (
        <>
            <OrbitPopups />
        </>
    );
}

기본 조회 엔드포인트는 /popups/active이며, 필요하면 endpoint prop으로 바꿀 수 있습니다.

<OrbitPopups endpoint="/custom/popups/active" />

공개 엔드포인트

popups.active

기본 경로:

/popups/active

운영 팁

ignore_days가 0 이하이면 세션 단위로만 닫힘 상태를 기억합니다.
ignore_days가 1 이상이면 localStorage에 만료 시각을 저장해 "오늘 하루 보지 않기" 흐름을 구현합니다.
styles에는 폭, 위치, 여백 같은 오버레이 스타일 값을 JSON으로 넣어 개별 팝업을 손쉽게 조정할 수 있습니다.

업데이트 노트

4.3.0

cms-orbit/core ^4.5 → ^4.6: core 4.6.0 이 OrbitAccess 라우팅 리졸버와 여러 관리자 화면 수정(PostgreSQL 500, strict mode, orbit:install 의 OrbitProvider 미등록)을 담고 있습니다.
GitHub Actions 워크플로 추가: php 8.4·8.5 로 composer validate 와 pint --test 를 돌리는 ci.yml, 그리고 태그의 composer.json version 이 태그명과 일치하는지 확인하는 release-guard.yml. Packagist 는 불일치 태그를 조용히 무시합니다.
위성 패키지의 CI 는 cms-orbit/core 를 Packagist 게시본으로 받으므로, "지금 게시된 core 와 이 패키지의 제약이 함께 해석되는가" 까지 같이 검증합니다.
pint 포맷 정규화: pint --test 를 CI 게이트로 걸려면 기존 코드가 설정에 맞아야 해서 함께 정규화했습니다. 순수 포맷 변경이며 동작은 바뀌지 않습니다.

4.2.0

laravel/framework ^11.0 || ^12.0 || ^13.0 → ^13.0: Laravel 13 전용으로 좁혔습니다.
cms-orbit/core ^4.4 → ^4.5.
왜 좁혔나: 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 으로 올리거나 이전 버전에 머물러야 합니다.

4.1.0

php 제약 ^8.3 → ^8.4: php 8.3 환경에서는 더 이상 설치되지 않습니다.
cms-orbit/core ^4.1 → ^4.4.
생산 의존은 하나도 바뀌지 않았습니다. php 하한 상향으로 새로 받게 된 패키지는 Pest 5 계열(require-dev)뿐입니다. cms-orbit 전 패키지의 직접 의존 20개를 최신판과 전수 대조했고, 나머지 18개는 이미 php ^8.3 에서 최신을 받고 있었습니다. 이번 상향은 기능 확보가 아니라 장기 정리 목적입니다.
소비자의 Laravel 11·12 지원은 유지됩니다 (laravel/framework ^11.0 || ^12.0 || ^13.0).

4.0.3

php 제약 ^8.3 복구: 게시된 태그는 모두 ^8.3 이었으나 main 에서 ^8.2 로 내려가 있었습니다. Laravel 13 은 php ^8.3 을 요구하므로 php ^8.2 + laravel/framework ^13 조합은 php 8.2 환경에서 조용히 Laravel 11 을 설치합니다.
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 가 자동 설정됩니다.

License

MIT

cms-orbit / popup

Maintainers

Package info

Statistics

Security