← 시작하기 · README로 돌아가기 · 즉시 로딩 →
설정 사용하기
같은 서비스가 기본값과 모델 값을 처리합니다. 진입점에 따라 읽거나 변경할 범위가 결정됩니다.
| 진입점 | 범위 |
|---|---|
(new User)->defaultSettings() | 저장된 User 모델이 공유하는 기본값 |
$user->settings() | 저장된 사용자 한 명의 최종 설정 |
공유 기본값
기본값은 같은 Eloquent morph 클래스를 사용하는 모든 저장된 모델에 적용됩니다.
$defaults = (new User)->defaultSettings();
$defaults->set('timezone', 'UTC');
$defaults->set('notifications', ['email' => true]);
같은 서비스를 통해 기본값을 읽거나 제거합니다.
$timezone = $defaults->get('timezone');
$all = $defaults->all();
$defaults->forget('timezone');
기본값은 모델 클래스마다 독립적입니다.
모델별 재정의 값
set()은 설정을 생성하거나 기존 값을 교체합니다.
$user->settings()->set('timezone', 'Europe/Paris');
$user->settings()->set('timezone', 'America/Toronto');
해당 모델의 설정만 변경됩니다. 다른 모델은 자체 재정의 값이나 공유 기본값을 계속 사용합니다.
get(), has(), all()은 같은 우선순위로 값을 결정합니다.
$timezone = $user->settings()->get('timezone');
$hasTimezone = $user->settings()->has('timezone');
$settings = $user->settings()->all();
all()은 설정 키로 인덱싱된 Illuminate\Support\Collection을 반환합니다.
get()은 키만 받습니다. 모델 재정의 값, 저장된 클래스 기본값, null 순서로 반환합니다. 호출자가 지정하는
대체값은 받지 않습니다. has()는 키가 없는 경우와 저장된 JSON null을 구분합니다.
if ($user->settings()->has('timezone')) {
$timezone = $user->settings()->get('timezone');
}
예를 들어 하나의 재정의 값은 일치하는 기본값만 교체합니다.
(new User)->defaultSettings()->set('timezone', 'UTC');
(new User)->defaultSettings()->set('locale', 'en');
$user->settings()->set('timezone', 'Europe/Paris');
assert($user->settings()->all()->sortKeys()->all() === [
'locale' => 'en',
'timezone' => 'Europe/Paris',
]);
값 제거
모델 재정의 값을 제거하면 기본값이 다시 사용됩니다.
(new User)->defaultSettings()->set('timezone', 'UTC');
$user->settings()->set('timezone', 'Europe/Paris');
$user->settings()->forget('timezone');
assert($user->settings()->get('timezone') === 'UTC');
기본값 자체를 제거하려면 defaultSettings()를 통해 forget()을 호출합니다.
(new User)->defaultSettings()->forget('timezone');
없는 키에 forget()을 호출해도 아무 변화가 없습니다.
일괄 변경
한 범위에서 여러 값을 변경할 때 setMany()와 forgetMany()를 사용합니다.
$user->settings()->setMany([
'timezone' => 'Europe/Paris',
'locale' => 'fr',
]);
$user->settings()->forgetMany(['timezone', 'locale']);
두 메서드는 모든 iterable을 받습니다. setMany()는 쓰기 전에 각 키를 정규화합니다. 여러 입력 키가 같은
저장 키로 정규화되면 마지막 값이 적용됩니다. 모든 값이 저장되며 행은 forget()과 forgetMany()만
삭제합니다.
비어 있지 않은 setMany() 일괄 작업은 트랜잭션 안에서 데이터베이스 네이티브 upsert 한 번을 사용합니다.
forgetMany()는 나열된 모든 키를 한 번의 삭제로 처리합니다. 쿼리 수는 키 수가 아니라 연산 유형에 따라
제한됩니다.
현재 범위 전체를 제거하려면 purge()를 사용합니다.
$user->settings()->purge();
settings()의 purge()는 해당 소유자의 재정의 값만 삭제하고 저장된 기본값을 다시 노출합니다.
defaultSettings()에서는 모델 재정의 값을 삭제하지 않고 해당 모델 클래스의 기본값을 삭제합니다. 세 일괄
메서드는 모두 void를 반환합니다.
JSON 값
set()과 setMany()는 JSON 값을 정확히 저장합니다.
| 값 | 결과 |
|---|---|
null | 저장 |
'' 또는 공백만 있는 문자열 | 저장 |
[] | 저장 |
0 | 저장 |
false | 저장 |
'0' | 저장 |
저장된 null은 존재하는 값으로 간주합니다. has($key)는 true를 반환하고 get($key)는 null을
반환합니다. 값이 null인 모델 재정의는 forget()으로 제거할 때까지 채워진 클래스 기본값도 숨깁니다.
설정 키
키는 문자열, 정수 또는 UnitEnum을 구현하는 PHP enum일 수 있습니다.
enum SettingKey: string
{
case Timezone = 'timezone';
}
$user->settings()->set(SettingKey::Timezone, 'Europe/Paris');
$timezone = $user->settings()->get(SettingKey::Timezone);
Laravel은 backed enum을 기반 값으로 저장하고 pure unit enum을 case 이름으로 저장합니다. 설정을 읽거나 교체하거나 제거할 때 같은 키 또는 enum case를 사용합니다.
빈 키와 공백만 있는 키는 DragonCode\LaravelModelSettings\Exceptions\InvalidSettingKey를 발생시킵니다.
정수와 enum을 저장 문자열로 정규화한 뒤 검증합니다. 예외 메시지에는 거부된 키나 설정 페이로드가 포함되지
않습니다.
점은 리터럴 문자입니다. mail.from.address는 하나의 불투명한 설정 키이며 중첩 경로를 뜻하지 않습니다.
$user->settings()->set('mail.from.address', '[email protected]');
$address = $user->settings()->get('mail.from.address');
모델 식별자
정수, 문자열, UUID, ULID 기본 키를 지원합니다.
모델별 설정을 변경하려면 키가 null이 아닌 저장된 소유자가 필요합니다. 저장되지 않은 모델에서 get()은
null, has()는 false를 반환하고 all()은 모델 재정의를 쿼리하지 않고 빈 컬렉션을 반환합니다.
set(), setMany(), forget(), forgetMany(), purge()는 저장소 쿼리나 iterable 소비 전에
InvalidSettingsOwnerException을 발생시킵니다.
정수 식별자 0 또는 문자열 '0'을 가진 저장된 모델은 다른 저장된 소유자와 동일한 읽기 및 변경 작업을
지원합니다. 범위 판별자가 재정의와 클래스 기본값을 분리하므로 두 행이 모두 item_id = '0'을 유지해도
충돌하지 않습니다. '00'을 포함한 다른 문자열 키는 계속 유효합니다.
설정은 모델의 현재 morph 클래스에 대해 저장됩니다. 설정을 기록한 후 morph map 별칭을 추가하거나 변경하면 기존
item_type 값을 업데이트해야 합니다.