Files
Gnuboard7/modules/_bundled/sirsoft-page/src/Services/PageService.php
T
HeuJung e619b21b2b perf(page): 검색 전량 적재 제거 및 상한 계약 소비
검색이 조건에 맞는 페이지 전체를 읽어 온 뒤 PHP 에서 화면 분량만 잘라 내고
있었다. 실제 page/per_page 를 저장소까지 하달해 필요한 분량만 조회한다.
구체 엔진 직접 호출도 해석기 경유로 옮겨 플러그인 검색엔진이 페이지 검색에
적용된다.

관리자 목록은 화면에 본문이 나오지 않는데도 항목마다 본문을 함께 읽고 있었다.
목록 조회에서 제외하고 총 건수에 상한 계약을 적용했다.

발행 페이지 목록과 통합검색의 페이지 탭 정렬에 필요한 색인을 더했다. 신규 설치는
마이그레이션이, 기존 사이트는 업그레이드 스텝이 적용한다.

관리자 목록의 페이저가 총 건수를 끝까지 세지 못한 경우 "1페이지뿐" 으로 접혀
뒤쪽 페이지에 도달할 수 없던 것을 고쳤다.
2026-08-06 11:13:52 +09:00

520 lines
18 KiB
PHP

<?php
namespace Modules\Sirsoft\Page\Services;
use App\Extension\HookManager;
use App\Helpers\PermissionHelper;
use App\Search\SearchPagePolicy;
use App\Support\Query\BoundedCount;
use App\Support\Query\BoundedPage;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Pagination\CursorPaginator;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\DB;
use Modules\Sirsoft\Page\Models\Page;
use Modules\Sirsoft\Page\Models\PageVersion;
use Modules\Sirsoft\Page\Repositories\Contracts\PageRepositoryInterface;
use Modules\Sirsoft\Page\Repositories\Contracts\PageVersionRepositoryInterface;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
/**
* 페이지 서비스
*
* 페이지 생성/수정/삭제/발행 비즈니스 로직을 담당합니다.
*/
class PageService
{
/**
* 검색 정렬 이름 → [실제 컬럼, 방향] 선언
*
* 코어({@see SearchPagePolicy})가 이 선언을 읽어 커서 적용 여부를 판정한다.
* 여기에 없는 정렬 이름(관련도순 등)은 커서로 처리하지 않고 offset 을 유지한다.
*/
public const SEARCH_SORT_MAP = [
'latest' => ['created_at', 'desc'],
'oldest' => ['created_at', 'asc'],
];
/**
* 커서(키셋) 경계로 쓸 수 있는 실제 컬럼 선언
*/
public const SEARCH_CURSOR_COLUMNS = ['created_at'];
public function __construct(
private PageRepositoryInterface $pageRepository,
private PageVersionRepositoryInterface $pageVersionRepository,
private PageAttachmentService $pageAttachmentService,
) {}
/**
* 페이지 목록을 조회합니다.
*
* @param array $filters 필터 조건
* @param int $perPage 페이지당 항목 수
* @return LengthAwarePaginator 페이지 목록
*/
public function getPages(array $filters = [], int $perPage = 20): LengthAwarePaginator
{
$filters = HookManager::applyFilters('sirsoft-page.page.filter_list_query', $filters);
return $this->pageRepository->paginate($filters, $perPage);
}
/**
* 페이지를 생성합니다.
*
* 생성 후 버전 1 스냅샷을 저장합니다.
*
* @param array $data 페이지 생성 데이터
* @return Page 생성된 페이지 모델
*/
public function createPage(array $data): Page
{
HookManager::doAction('sirsoft-page.page.before_create', $data);
$data = HookManager::applyFilters('sirsoft-page.page.filter_create_data', $data);
return DB::transaction(function () use ($data) {
$userId = Auth::id();
$pageData = array_merge($data, [
'created_by' => $userId,
'updated_by' => $userId,
'current_version' => 1,
]);
// 발행 상태로 생성 시 published_at 설정
if (! empty($pageData['published'])) {
$pageData['published_at'] = now();
}
$page = $this->pageRepository->create($pageData);
// 버전 1 스냅샷 저장
$this->saveVersionSnapshot($page, $userId);
// temp_key 첨부파일 연결 및 파일 이동 (업로드 순서대로 order 부여)
if (! empty($data['temp_key'])) {
$this->pageAttachmentService->linkTempAttachmentsWithMove(
$data['temp_key'],
$page->id
);
}
HookManager::doAction('sirsoft-page.page.after_create', $page, $data);
return $page;
});
}
/**
* 페이지를 수정합니다.
*
* 수정 후 버전 스냅샷을 저장하고 current_version을 증가시킵니다.
*
* @param Page $page 페이지 모델
* @param array $data 수정할 데이터
* @return Page 수정된 페이지 모델
*/
public function updatePage(Page $page, array $data): Page
{
if (! PermissionHelper::checkScopeAccess($page, 'sirsoft-page.pages.update')) {
throw new AccessDeniedHttpException(__('auth.scope_denied'));
}
HookManager::doAction('sirsoft-page.page.before_update', $page, $data);
$snapshot = $page->toArray();
$data = HookManager::applyFilters('sirsoft-page.page.filter_update_data', $data, $page);
return DB::transaction(function () use ($page, $data, $snapshot) {
$userId = Auth::id();
$updateData = array_merge($data, [
'updated_by' => $userId,
'current_version' => $page->current_version + 1,
]);
// 발행 상태이거나 발행 전환 시 published_at 갱신
if (! empty($updateData['published'])) {
$updateData['published_at'] = now();
}
$page = $this->pageRepository->update($page, $updateData);
// 버전 스냅샷 저장
$this->saveVersionSnapshot($page, $userId);
// temp_key 첨부파일 연결 및 파일 이동 (업로드 순서대로 order 부여)
if (! empty($data['temp_key'])) {
$this->pageAttachmentService->linkTempAttachmentsWithMove(
$data['temp_key'],
$page->id
);
}
HookManager::doAction('sirsoft-page.page.after_update', $page, $data, $snapshot);
return $page;
});
}
/**
* 페이지를 삭제합니다 (소프트 삭제).
*
* 첨부파일도 함께 소프트 삭제합니다.
*
* @param Page $page 페이지 모델
* @return bool 삭제 성공 여부
*/
public function deletePage(Page $page): bool
{
if (! PermissionHelper::checkScopeAccess($page, 'sirsoft-page.pages.delete')) {
throw new AccessDeniedHttpException(__('auth.scope_denied'));
}
HookManager::doAction('sirsoft-page.page.before_delete', $page);
return DB::transaction(function () use ($page) {
// 첨부파일 삭제: 물리 파일 + DB 소프트 삭제 (DB CASCADE 의존 금지)
$attachments = $this->pageAttachmentService->getByPageId($page->id);
foreach ($attachments as $attachment) {
$this->pageAttachmentService->deleteAttachment($attachment);
}
$result = $this->pageRepository->delete($page);
HookManager::doAction('sirsoft-page.page.after_delete', $page);
return $result;
});
}
/**
* 페이지 발행 상태를 변경합니다.
*
* @param Page $page 페이지 모델
* @param bool $published 발행 여부
* @return Page 수정된 페이지 모델
*/
public function changePublishStatus(Page $page, bool $published): Page
{
if (! PermissionHelper::checkScopeAccess($page, 'sirsoft-page.pages.update')) {
throw new AccessDeniedHttpException(__('auth.scope_denied'));
}
HookManager::doAction('sirsoft-page.page.before_publish', $page, $published);
$updateData = [
'published' => $published,
'updated_by' => Auth::id(),
];
// 발행 시 published_at 갱신
if ($published) {
$updateData['published_at'] = now();
}
$page = $this->pageRepository->update($page, $updateData);
HookManager::doAction('sirsoft-page.page.after_publish', $page, $published);
return $page;
}
/**
* 여러 페이지의 발행 상태를 일괄 변경합니다.
*
* @param array $ids 페이지 ID 목록
* @param bool $published 발행 여부
* @return int 변경된 페이지 수
*/
public function bulkChangePublishStatus(array $ids, bool $published): int
{
if (empty($ids)) {
return 0;
}
return DB::transaction(function () use ($ids, $published) {
$userId = Auth::id();
$count = 0;
foreach ($ids as $id) {
// 존재하지 않는 페이지가 섞이면 예외 → 트랜잭션 전체 롤백 (all-or-nothing)
$page = $this->pageRepository->findOrFail((int) $id);
HookManager::doAction('sirsoft-page.page.before_publish', $page, $published);
$updateData = [
'published' => $published,
'updated_by' => $userId,
];
// 발행 시 published_at 갱신
if ($published) {
$updateData['published_at'] = now();
}
$page = $this->pageRepository->update($page, $updateData);
// 페이지별 after_publish 발화 → 활동로그 per-item 기록
HookManager::doAction('sirsoft-page.page.after_publish', $page, $published);
$count++;
}
return $count;
});
}
/**
* 페이지 버전을 복원합니다.
*
* 지정된 버전의 스냅샷으로 현재 페이지 내용을 덮어쓰고
* 새로운 버전 스냅샷을 생성합니다.
*
* @param Page $page 페이지 모델
* @param int $versionId 복원할 버전 ID
* @return Page 복원된 페이지 모델
*
* @throws ModelNotFoundException 버전이 해당 페이지에 속하지 않을 때
*/
public function restoreVersion(Page $page, int $versionId): Page
{
if (! PermissionHelper::checkScopeAccess($page, 'sirsoft-page.pages.update')) {
throw new AccessDeniedHttpException(__('auth.scope_denied'));
}
// 상위 페이지 스코프를 Repository where 절에 반영한다 (SSoT).
// 사후 비교로 처리하면 예외 타입이 컨트롤러 catch 사슬과 어긋나 500 이 되고,
// 같은 위반에 404 를 내는 조회(getVersion)와 계약이 갈린다.
$version = $this->pageVersionRepository->findForPage($page->id, $versionId);
return DB::transaction(function () use ($page, $version) {
$userId = Auth::id();
$updateData = [
'title' => $version->title,
'content' => $version->content,
'content_mode' => $version->content_mode,
'seo_meta' => $version->seo_meta,
'updated_by' => $userId,
'current_version' => $page->current_version + 1,
];
$page = $this->pageRepository->update($page, $updateData);
// 복원 버전 스냅샷 저장 (복원 원본 버전 번호 전달)
$this->saveVersionSnapshot($page, $userId, $version->version);
HookManager::doAction('sirsoft-page.page.after_restore', $page, $version);
return $page;
});
}
/**
* ID로 페이지를 조회합니다.
*
* @param int $id 페이지 ID
* @return Page 페이지 모델
*
* @throws ModelNotFoundException
*/
public function getPage(int $id): Page
{
$page = $this->pageRepository->findOrFail($id);
if (! PermissionHelper::checkScopeAccess($page, 'sirsoft-page.pages.read')) {
throw new AccessDeniedHttpException(__('auth.scope_denied'));
}
return $page;
}
/**
* 슬러그로 발행된 페이지를 조회합니다.
*
* $allowUnpublished 가 true 이면 미발행 페이지도 반환합니다. 관리자 미리보기
* (사용자 화면에서 발행 전 페이지 확인)를 위한 것으로, 권한 판정은 호출부(컨트롤러)가
* 담당하고 이 메서드는 허용 여부만 플래그로 전달받습니다.
*
* @param string $slug 페이지 슬러그
* @param bool $allowUnpublished 미발행 페이지 반환 허용 여부 (관리자 미리보기)
* @return Page|null 페이지 모델 또는 null
*/
public function getPublishedPageBySlug(string $slug, bool $allowUnpublished = false): ?Page
{
$page = $this->pageRepository->findBySlug($slug);
if (! $page) {
return null;
}
return ($page->published || $allowUnpublished) ? $page : null;
}
/**
* 페이지 버전 이력을 조회합니다.
*
* @param Page $page 페이지 모델
* @return Collection 버전 목록 (최신순)
*/
public function getVersions(Page $page): Collection
{
return $this->pageVersionRepository->getVersionsByPage($page);
}
/**
* 페이지에 속한 버전을 조회합니다.
*
* @param int $pageId 페이지 ID
* @param int $versionId 버전 ID
* @return PageVersion 버전 모델
*
* @throws ModelNotFoundException
*/
public function getVersion(int $pageId, int $versionId): PageVersion
{
return $this->pageVersionRepository->findForPage($pageId, $versionId);
}
/**
* 슬러그 중복 여부를 확인합니다.
*
* @param string $slug 확인할 슬러그
* @param int|null $excludeId 제외할 페이지 ID (수정 시)
* @return bool 중복 여부 (true: 중복)
*/
public function slugExists(string $slug, ?int $excludeId = null): bool
{
return $this->pageRepository->slugExists($slug, $excludeId);
}
/**
* 키워드로 발행된 페이지를 검색합니다.
*
* @param string $keyword 검색 키워드
* @param string $orderBy 정렬 컬럼
* @param string $direction 정렬 방향 (asc, desc)
* @param int $perPage 페이지당 항목 수
* @param int $page 페이지 번호
* @return BoundedPage 페이지 결과 (총 건수 정확도 포함)
*/
public function searchByKeyword(
string $keyword,
string $orderBy = 'created_at',
string $direction = 'desc',
int $perPage = 10,
int $page = 1
): BoundedPage {
return $this->pageRepository->searchByKeyword($keyword, $orderBy, $direction, $perPage, $page);
}
/**
* 키워드로 페이지를 커서(키셋)로 검색합니다.
*
* 커서 적용 가능 여부는 코어({@see SearchPagePolicy})가 판정한다. 이 서비스는
* 정렬 선언({@see self::SEARCH_SORT_MAP})만 제공하고 규칙을 다시 쓰지 않는다.
*
* @param string $keyword 검색 키워드
* @param string $sort 정렬 옵션
* @param int $perPage 페이지당 항목 수
* @param string|null $cursor 인코딩된 커서 (첫 페이지면 null)
* @return CursorPaginator|null 커서 페이지 결과 (커서 적용 불가 시 null)
*/
public function searchByKeywordWithCursor(
string $keyword,
string $sort = 'latest',
int $perPage = 10,
?string $cursor = null
): ?CursorPaginator {
$sortKeys = SearchPagePolicy::sortKeys($sort, self::SEARCH_SORT_MAP);
if (! SearchPagePolicy::usesCursor($cursor, $sortKeys, self::SEARCH_CURSOR_COLUMNS)) {
return null;
}
return $this->pageRepository->searchByKeywordWithCursor($keyword, $sortKeys, $perPage, $cursor);
}
/**
* 키워드와 일치하는 발행된 페이지 수를 조회합니다.
*
* @param string $keyword 검색 키워드
* @return BoundedCount 일치하는 페이지 수 (정확도 포함)
*/
public function countByKeyword(string $keyword): BoundedCount
{
return $this->pageRepository->countByKeyword($keyword);
}
/**
* 현재 페이지 상태를 버전 스냅샷으로 저장합니다.
*
* @param Page $page 페이지 모델
* @param int $userId 작성자 ID
* @param int|null $restoredFrom 복원 원본 버전 번호 (복원 시에만)
*/
private function saveVersionSnapshot(Page $page, int $userId, ?int $restoredFrom = null): void
{
$this->pageVersionRepository->create([
'page_id' => $page->id,
'version' => $page->current_version,
'title' => $page->title,
'content' => $page->content,
'content_mode' => $page->content_mode,
'seo_meta' => $page->seo_meta,
'changes_summary' => $this->calculateChangesSummary($page, $restoredFrom),
'created_by' => $userId,
]);
}
/**
* 이전 버전과 비교하여 변경 요약을 계산합니다.
*
* @param Page $page 페이지 모델
* @param int|null $restoredFrom 복원 원본 버전 번호
* @return array|null 변경 요약 (최초 생성 시 null)
*/
private function calculateChangesSummary(Page $page, ?int $restoredFrom): ?array
{
// 최초 생성 (version 1)은 변경 요약 없음
if ($page->current_version <= 1) {
return null;
}
$previousVersion = $this->pageVersionRepository->findByPageAndVersion(
$page,
$page->current_version - 1
);
// 이전 버전이 없으면 변경 요약 계산 불가
if (! $previousVersion) {
return null;
}
$changedFields = [];
$compareFields = ['title', 'content', 'seo_meta'];
foreach ($compareFields as $field) {
if (json_encode($page->{$field}) !== json_encode($previousVersion->{$field})) {
$changedFields[] = $field;
}
}
// content_mode는 문자열 비교
if ($page->content_mode !== $previousVersion->content_mode) {
$changedFields[] = 'content_mode';
}
return [
'changed_fields' => $changedFields,
'restored_from' => $restoredFrom,
];
}
}