본문으로 건너뛰기
가이드

PHP SDK 사용하기

PHP SDK 사용하기

PHP SDK 사용하기

생성된 코드에서 시작하기

리소스를 만들면 모델·Controller·Policy·Resource Module이 생성됩니다. 전체를 새로 작성하기보다 필요한 필드와 업무 규칙을 추가하세요.

작업수정 위치
저장할 필드 추가migration, 모델
입력 검증·저장·응답Controller
조회·생성·수정 허용 조건Policy
리소스 이름·메뉴·권한 선언Resource Module

리소스 만들기와 칼럼 추가에 실제 수정 예제가 있습니다.

현재 사용자 식별하기

인증된 Laravel 요청에서는 $request->user()->getAuthIdentifier()를 사용합니다. SDK의 Nexia\Identity\Contracts\Actor를 받는 Policy나 서비스에서는 $actor->key()를 사용하세요. 인증이 필요한 경로는 생성된 인증 미들웨어를 유지합니다.

사용자 객체가 Core의 Eloquent 모델이라고 가정하여 getKey(), 모델 관계, Core 전용 메서드를 호출하지 마세요. 앱 소유 Eloquent 레코드의 getKey()는 그대로 사용할 수 있습니다. 이 계약은 앱 실행 경계를 넘어 사용자 식별 정보를 유지합니다.

사용자 공개 식별자는 $actor->publicId(), 연결된 Party 키는 $actor->partyKey()로 읽으세요. Party 키는 null일 수 있으므로 연결되지 않은 사용자는 본인 인사 기록이 없는 상태로 처리합니다. Resource Reference resolver에서도 $actor->party_id 등 호스트 모델 속성을 직접 읽지 마세요.

플랫폼 설정 읽기

앱 실행 중인 Backend에서 공개 인터페이스를 사용합니다.

코드 예시
PHP
use Nexia\Settings\Contracts\AppSettings;

$setting = app(AppSettings::class)->get('tenant', 'my-app.integration.api_key');
if (! $setting->configured) {
    // 앱에서 설정 누락을 처리합니다.
}

키는 앱이 선언한 키로 바꾸세요. app은 앱 공통, tenant는 현재 테넌트의 값입니다. 실제 값은 use() 콜백 안에서 소비하며 비밀값을 응답이나 로그로 출력하지 않습니다. 선언·등록 절차는 설정과 비밀값을 따르세요.

지켜야 할 규칙

  • 생성된 권한·테넌트 처리 코드를 유지하세요. 화면에서 버튼을 숨기는 것만으로 권한이 적용되지는 않습니다.
  • 다른 앱의 테이블이나 Core 내부 모델을 직접 조회하지 마세요.
  • 필요한 외부 기능은 공개 SDK 지원 여부를 확인한 뒤 사용하세요.
  • 로컬 검사 후 샌드박스에서 허용·거부 사용자와 실제 저장 결과를 확인하세요.

백엔드 동작 확인

허용·거부 사용자로 각각 동작을 확인하세요. 설정은 값이 있는 경우와 없는 경우를 모두 확인하고 API 응답과 로그에 비밀 값이 없는지 검사합니다. 저장은 레코드를 다시 열어 결과와 테넌트 격리를 확인하세요.

Core 테이블을 참조하는 관계는 Core 식별자를 외래키로 참조하기에서 허용 목록과 저장 전 검사를 확인하세요.

외부 프로그램에서 DB 데이터 입력받기

외부 DB 입력 계약으로 INSERT용 계정을 발급하고 접속 IP를 등록합니다. 발급·적용 대기·비밀번호 1회 표시·교체·접속 확인 절차는 외부 프로그램에서 DB 데이터 입력받기를 참고하세요.

현재 재직 상태와 회사 접근 종료

리소스 소유 앱은 ResourceDescriptor.searchSchema.person_status_filter.options에 value와 번역 키 label 쌍을 공개할 수 있습니다. 호스트는 조회 권한이 있는 제공자 하나를 발견한 경우에만 문서 내역에 상신자 현재 재직 상태 필터를 표시합니다. 제공자가 없으면 필터를 표시하지 않습니다. 페이지 단위 참조 검색의 purpose는 core.person-status-filter, 범위는 선택한 회사, asOf는 현재 시각, 조건은 filters.person_status입니다. 소유 앱은 허용된 사람만 반환하며 fields.person_party_public_id를 제공합니다. Core는 이 Party와 기존 상신자를 연결하며 과거 문서를 변경하지 않습니다. 선택한 필터의 제공자가 사라지면 필터를 무시하지 않고 오류를 반환합니다. 계정 활성 상태와 재직 상태는 다릅니다.

Nexia\Identity\Contracts\PersonLegalEntityAccess::end(actor, personPartyPublicId, legalEntityKey, sourceReference)는 사용자 정보·과거 기록·다른 회사 접근을 보존하며 해당 회사 참여와 회사 범위 권한을 종료합니다. 실행자는 해당 회사의 legal_entity.member.remove와 authorization.legal_entity_grant.update 권한이 모두 필요합니다. 런타임은 Party 조회 권한과 소유 앱 접두사가 있는 출처도 검사합니다. 결과는 completed, unlinked, review_required이며, 전체 회사에 걸친 권한은 자동 변경하지 않고 검토 대상으로 남깁니다. 소유 앱은 같은 회사의 다른 유효 고용 관계를 먼저 확인하고 성공 결과를 보존하며, 실패한 접근 처리는 이미 효력이 발생한 퇴직과 별도로 재시도해야 합니다. 소비 앱은 접근 처리가 미확정이면 최종 완료로 안내하면 안 됩니다.

회사 접근 종료는 PHP SDK 0.10.13·Core 0.8.159·Manager 0.1.0-alpha.83 이상과 대응 앱 런타임이 필요합니다. 앱 소스 수정만으로 기존 런타임이 갱신되지는 않습니다. 사용자 삭제나 전체 계정 비활성화를 의미하지 않습니다.

선택적 커스텀 조회 선언

표준 Resource 목록·단건 조회 경로는 자동으로 발견됩니다. Nexia\AppRuntime\BatchableRead를 지원하는 PHP SDK와 관리형 런타임에서는 읽기 전용 JSON GET 컨트롤러 메서드에 호스트의 묶음 조회 참여를 선언할 수 있습니다.

코드 예시
PHP
#[\Nexia\AppRuntime\BatchableRead]
public function index(Request $request): JsonResponse
{
    // 기존 권한 및 조직 범위 검사를 유지합니다.
}

완료되는 읽기 전용 JSON 응답에만 선언하세요. 변경 작업, 다운로드, 스트리밍에는 붙이지 않습니다. 런타임이 실제 등록된 경로를 발견하므로 클라이언트 API 변경이나 수동 경로 목록은 필요하지 않습니다. 속성이 포함된 PHP SDK 릴리스로 앱 의존성을 올린 뒤 사용하고, 일반적인 개발 소스 갱신 또는 빌드·배포 절차로 앱을 갱신하세요. PHP SDK 0.10.14·Core 0.8.161·Manager 0.1.0-alpha.85 이상과 대응 앱 런타임이 필요합니다.

갱신한 화면의 브라우저 Network에서 확인하세요. 함께 실행되는 호환 조회는 read-batch로 묶일 수 있고, 선행 결과가 필요하거나 조직 범위가 다른 조회는 분리될 수 있습니다. 호스트가 8개 초과 그룹을 자동 분할하고 각 조회의 권한 검사를 유지하며, 묶을 수 없으면 개별 조회로 전환합니다. 묶음 적용이 화면 완료 시간 단축을 보장하지는 않습니다.

대응하는 호스트·CLI에서는 [NEXIA_READ_BATCH_INFO] 개발 안내가 브라우저 콘솔과 연결된 CLI에 표시됩니다. 이는 정보이며 빌드·제출·배포를 막는 조건이 아닙니다. nexia check만으로 런타임의 경로 등록 여부를 판정할 수는 없습니다. 속성이 없는 기존 앱의 커스텀 조회는 계속 개별 실행됩니다.

권한을 확인하는 프로필 이력 조회

PHP SDK 0.10.15는 PersonProfileHistory::pageForAuthorizedHr(actor, partyKey, legalEntityKey, cursor, limit, authorizationResource)의 마지막 선택 인자 ?ResourceRef $authorizationResource = null을 추가합니다. 이 인터페이스를 직접 구현하는 앱은 선택 인자를 추가해야 합니다. 인자를 생략한 기존 호출에는 디렉터리 권한이 계속 필요합니다. Core 0.8.173과 대응 앱 런타임에서 이 계약을 지원합니다.

ResourceRef는 소유 레코드의 식별자이며 권한 자체가 아닙니다. 소유 앱의 descriptor는 fieldSchema.person_profile_history.read_permission에 활성화된 앱 소유 법인 권한을 선언하고, resolver는 fields.person_profile_history에 party_key·legal_entity_key를 반환합니다. Core는 {app}.person-profile-history 용도로 참조를 해석하고 정확한 레코드·사용자·법인·허용 대상을 검사합니다. 브라우저가 보낸 참조를 권한으로 믿거나 조회를 통과시키려고 범위를 넓히지 마세요.

프로필 이력 계약, 회사 접근 종료 계약, 조회 선언의 제한을 확인하세요. 기능을 활성화하기 전에 허용·거부할 소유 레코드와 소유자 인자 없는 호출을 점검합니다.

메일 발송 없이 사람의 로그인 계정 준비

Nexia\Identity\Contracts\PersonLoginAccounts::ensure(actor, email, personPartyPublicId, legalEntityKey, accessProfile, operatingUnitPublicIds)는 해당 사람의 계정을 준비하거나 재사용합니다. 초대 메일을 보내지 않고 기존 비밀번호를 유지합니다. 운영자가 초대를 요청할 때 별도의 PersonLoginInvitations 서비스를 호출하세요.

실행자는 선택한 법인에서 tenant.user.create 권한이 필요합니다. 활성 상태의 사람과 이메일이 일치해야 하며 다른 사람의 계정을 재연결할 수 없습니다. 접근 프로필이 null이면 소속 없는 비활성 계정을 생성하고 기존 계정은 변경하지 않습니다. LegalEntityMemberSelfService는 법인 참여와 본인 업무 권한을 추가하지만 비활성 계정을 재활성화하지 않습니다. 선택적인 운영 조직 공개 ID는 해당 법인 소속이어야 합니다. 기존 소속과 역할은 유지됩니다.

앱에서 사용하기 전에 이 계약이 포함된 PHP SDK와 대응하는 Core 구현·관리형 런타임 콜백을 함께 반영하세요. 릴리스 버전은 아직 정해지지 않았습니다. 반복 실행, 메일 미발송, 비밀번호 보존, 이메일 충돌, 과거·비활성 계정, 권한 없는 실행자와 다른 법인 운영 조직 거부를 검증하세요. 초대 메일 전달은 별도로 확인합니다. 공개 Identity 계약 소스도 참고하세요.

조직 소속 이동 (미출시)

PersonOperatingUnitMemberships::move는 계정을 생성하거나 역할을 부여하지 않고, 기존 사용자의 동일 법인 내 조직 소속을 옮깁니다. 호출자는 변경되지 않는 요청 참조를 전달하고 동일한 인자로 재시도해야 합니다. 호스트는 정확한 조직 대상을 기준으로 이전 소속 제거·새 소속 추가·요청 시 새 조직의 주 소속 지정 권한을 확인합니다. 정지된 소속이나 활성 법인 참여가 없으면 review_required, 연결된 계정이 없으면 unlinked를 반환합니다. 다른 조직 소속은 유지합니다.

사용하려면 대응하는 Core 테넌트 마이그레이션과 네이티브 Runtime 어댑터가 필요합니다. 기존 출시 SDK 패키지에서는 사용할 수 없습니다. 업무 결과와 재시도 가능한 연동 상태를 별도로 저장해야 하며, 앱 트랜잭션이 이미 완료된 호스트 변경을 되돌린다고 가정하면 안 됩니다.

원본 위치: docs/developers/content/ko/app-sdk/sdk-contracts.md