본문으로 건너뛰기
가이드

설정 페이지 추가

앱 공통·테넌트별 설정과 비밀값을 관리하고, 업무 설정용 Resource 화면을 구분합니다.

앱 설정은 플랫폼이 관리하는 일반값·비밀값과 앱이 소유하는 업무 데이터로 구분합니다. 저장할 값의 성격에 맞는 경로를 선택하세요.

플랫폼에서 관리하는 설정·비밀값

외부 API 키, 연동 옵션 등은 공개 SDK의 Nexia\Settings\Contracts\SettingsContribution으로 선언합니다. settings()는 SettingDefinition 목록을 반환하며 실제 값은 선언에 넣지 않습니다.

  • scope: app: 해당 환경의 앱 공통 값입니다. Developers의 프로젝트 → 개발 환경 → 프로젝트 앱 → 해당 앱 → 앱 설정에서 관리합니다. 프로젝트 관리 권한이 필요합니다.
  • scope: tenant: 해당 환경·테넌트·앱에만 적용합니다. 샌드박스의 설정 → 앱 → 개발 중인 앱 설정 → 해당 앱 → 앱 설정에서 관리합니다.
  • managementPermission: 같은 앱이 선언한 관리 권한을 지정합니다. 설정 범위별 관리 권한 검사를 통과해야 변경할 수 있습니다.
  • secret: true: Backend 전용 비밀값입니다. 기본값을 넣거나 frontend: true와 함께 선언할 수 없습니다. 일반 설정의 프런트엔드 공개 여부도 별도로 선언합니다.

선언을 추가한 뒤 프로젝트의 nexia dev에서 준비 완료를 확인하세요. 설정 화면에서 등록·교체·삭제하며, 저장한 비밀값은 다시 표시하지 않고 등록 여부와 버전 등 상태만 확인합니다. 워크스페이스의 설정 → 자격 증명 및 접근은 권한을 관리하는 화면이며 비밀값을 입력하는 곳이 아닙니다.

Backend에서는 Nexia\Settings\Contracts\AppSettings의 get('app', $key) 또는 get('tenant', $key)로 명시한 범위를 읽습니다. 반환된 SettingValue의 configured로 등록 여부를 확인하고 use() 콜백 안에서 값을 사용합니다. 두 범위는 서로 대체되지 않습니다. 비밀값을 화면·응답·로그에 출력하거나 앱 저장소에 저장하지 마세요.

일반값과 비밀값의 저장·교체·삭제, 누락 시 처리, 두 앱에 같은 이름의 설정을 선언했을 때의 분리를 확인하세요. 개발 환경에서 저장한 값으로 운영 설정이 완료되지는 않습니다.

설정 선언 예제

Workshop 앱의 src/Contribution/WorkshopSettings.php를 만듭니다. 다른 앱에서는 생성된 namespace와 workshop 키를 사용 중인 값으로 바꾸세요. 생성 Manifest의 contributionLocations()가 src/Contribution을 이미 발견하므로 Core에 등록하지 않습니다.

코드 예시
PHP
<?php

declare(strict_types=1);

namespace Nexia\Apps\Acme\Workshop\Contribution;

use Nexia\Permission\AssignmentScope;
use Nexia\Permission\Contracts\PermissionContribution;
use Nexia\Permission\PermissionDefinition;
use Nexia\Settings\Contracts\SettingsContribution;
use Nexia\Settings\SettingDefinition;

final class WorkshopSettings implements PermissionContribution, SettingsContribution
{
    public static function catalogPermissionDefinitions(): array
    {
        return [PermissionDefinition::make(
            'workshop', 'settings', 'manage', assignmentScope: AssignmentScope::Tenant,
        )];
    }

    public static function settings(): array
    {
        return [new SettingDefinition(
            key: 'workshop.integration.api_key',
            scope: 'tenant',
            type: 'string',
            description: 'API key for the Workshop integration.',
            managementPermission: 'workshop.settings.manage',
            secret: true,
        )];
    }
}

resources/lang/en.json, ko.json, zh.json에 permissions.keys.workshop.settings.manage.label과 .description을 추가합니다. 각각 Manage Workshop settings / Allows managing Workshop settings., Workshop 설정 관리 / Workshop 설정을 관리할 수 있습니다., 管理 Workshop 设置 / 允许管理 Workshop 设置。를 사용합니다. 선언 반영 후 이 권한을 부여하고 위의 테넌트 앱 설정 화면에서 값을 저장하세요.

인가된 Backend 동작 안에서 값을 소비하는 발췌입니다. 예제 URL은 실제 연동 서비스의 신뢰할 수 있는 주소로 바꿔야 합니다. 사용자가 제공한 임의 URL로 비밀값을 전송하지 마세요.

코드 예시
PHP
use Nexia\Settings\Contracts\AppSettings;
use Illuminate\Support\Facades\Http;

$setting = app(AppSettings::class)->get('tenant', 'workshop.integration.api_key');
abort_unless($setting->configured, 422);
$response = $setting->use(fn ($key) => Http::withToken($key)
    ->timeout(10)->get('https://api.example.com/status'));
$response->throw();

비밀값이나 외부 응답 전체를 그대로 프런트엔드로 반환하지 않습니다. 연동 실패·미등록 상태는 앱의 사용자용 오류로 처리하고, 연동 서비스의 성공 조건은 앱에서 확인합니다.

업무 설정 화면 구성

  1. Resource 만들기에서 데이터와 보호된 API를 먼저 만듭니다. 테넌트 공통인지 조직별 설정인지 업무 규칙으로 결정하세요. 아래 People 증명서 정책은 Legal Entity 범위입니다. 별도 통합 설정 화면을 만들 때만 --no-navigation으로 기본 메뉴 항목을 숨깁니다.
  2. 생성된 화면을 그대로 쓰거나 App 화면 만들기에 따라 여러 Resource를 한 화면에 배치합니다. 컴포넌트 등록과 Manifest 경로 연결을 완료하세요. 각 API는 해당 Resource의 권한과 레코드 범위를 검사해야 하며, 페이지 공통 권한으로 수정 권한을 대신할 수 없습니다.
  3. App Menu 목적지 추가의 contribution에 groupId: 'settings'를 지정합니다.

packages/people/src/Contribution/PeopleCertificateSettings.php는 기존 증명서 설정 화면을 다음과 같이 연결합니다.

코드 예시
PHP
NavigationItem::make(
    id: 'people-certificate-settings',
    route: '/apps/people/settings/certificates',
    icon: 'file-badge',
    sort: 180,
    labelKey: 'people.certificate.settings.title',
    appKey: 'people',
    contextId: 'app',
    groupId: 'settings',
    permission: 'people.certificate_policy.read',
),

이 항목을 반환하는 클래스는 Nexia\Navigation\Contracts\NavigationContribution을 구현합니다. 같은 클래스에서 people.certificate_policy.update를 별도의 보호된 Legal Entity 권한으로 선언합니다. 적용할 때도 조회와 수정 권한을 분리하세요.

결과 확인

새 contribution 클래스는 discovery를 갱신해야 반영됩니다. 운영 가능한 테넌트에서 읽기 권한만 가진 사용자는 설정을 볼 수 있어야 하고, API에 직접 수정 요청을 보내면 거절되어야 합니다. 읽기 권한도 없는 사용자는 API로 설정 내용을 받을 수 없어야 합니다. 이 사례를 App 테스트하기의 패키지 테스트에 포함합니다.

설정 소유권 선택

필요한 설정구현 위치
코드 목록, 버전, 유효기간일반 App Resource
연동 옵션·외부 API 키SettingsContribution의 app 또는 tenant 설정; 비밀값은 secret 선언
관련 Resource 여러 개화면은 하나, API 권한 검사는 Resource별로 유지
플랫폼 전체 설정기존 플랫폼 기능 사용; host Site Configuration registry를 App에서 가져오지 않음

업무 설정 Resource의 메뉴는 App 내부에 둡니다. 플랫폼 설정·비밀값은 위의 앱 설정 화면과 공개 SDK 계약을 사용합니다. 업무 설정 Resource로 비밀값 저장 기능을 중복 구현하지 마세요.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

원본 위치: docs/developers/content/ko/platform-extensions/add-settings.md