← Conversões de payload · Voltar ao README · Desenvolvimento →

Referência da API

Trait HasSettings

Método	Retorna	Finalidade
settings()	SettingsService	Acessar as configurações efetivas deste modelo
defaultSettings()	SettingsService	Acessar os valores padrão compartilhados desta classe de modelo
modelSettings()	Relation do Eloquent	Carregar valores padrão e sobrescritas como uma relação

Use a relação modelSettings somente com with(), load() ou loadMissing() e como a propriedade carregada resultante. Não use a consulta da relação como uma API alternativa de leitura ou CRUD. Use os dois métodos de serviço para ler ou alterar valores. Em tempo de execução, a relação é uma SettingsRelation do pacote, baseada na relação MorphMany do Laravel.

SettingsService

Método	Retorna	Comportamento
all()	Collection	Retorna os valores padrão combinados com as sobrescritas do modelo
get(int|string|UnitEnum $key)	mixed	Retorna uma sobrescrita, seu valor padrão ou null
has(int|string|UnitEnum $key)	bool	Informa se uma chave efetiva existe, inclusive com null armazenado
set(int|string|UnitEnum $key, mixed $value)	void	Cria ou substitui uma configuração com o valor JSON exato
setMany(iterable $values)	void	Faz upsert de todos os valores em um lote transacional limitado
forget(int|string|UnitEnum $key)	void	Remove uma configuração se ela existir
forgetMany(iterable $keys)	void	Remove as chaves informadas do escopo atual
purge()	void	Remove todas as configurações armazenadas no escopo atual

Os métodos com chave aceitam backed enums e pure unit enums. O Laravel converte backed enums para seu valor subjacente e pure unit enums para o nome do case.

SettingsService não tem um parâmetro de valor alternativo fornecido pelo chamador em get(). Use has($key) para distinguir uma chave efetiva ausente de um JSON null armazenado.

Matriz de resolução

Sobrescrita do modelo	Padrão da classe	Resultado de get()	Resultado de has()	Incluído em all()
Presente	Presente	Sobrescrita, inclusive null	true	Sobrescrita
Presente	Ausente	Sobrescrita, inclusive null	true	Sobrescrita
Ausente	Presente	Padrão, inclusive null	true	Padrão
Ausente	Ausente	null	false	Nenhuma entrada

Para um modelo não persistido, get() retorna null, has() retorna false e all() retorna uma coleção vazia. Somente modelos persistidos herdam os valores padrão da classe.

all

$settings = $user->settings()->all();

$timezone = $settings->get('timezone');

O resultado é uma Illuminate\Support\Collection indexada pela chave da configuração. Para configurações de modelo, as sobrescritas substituem os valores padrão com a mesma chave.

get

$timezone = $user->settings()->get('timezone');

O resultado é o valor efetivo decodificado ou convertido. Quando a sobrescrita não existe, o valor padrão é usado. Se nem a sobrescrita nem o padrão existirem, o resultado será null. A assinatura intencionalmente não aceita um segundo argumento de valor alternativo.

has

$hasTimezone = $user->settings()->has('timezone');

O método retorna true quando existe uma sobrescrita do modelo ou uma linha de valor padrão da classe. Um JSON null armazenado retorna true; uma chave ausente retorna false. Os serviços com carregamento preguiçoso e antecipado usam a mesma precedência, e o caminho antecipado não executa outra consulta de configurações.

set

$user->settings()->set('timezone', 'Europe/Paris');

O método valida o proprietário e a chave normalizada, então executa uma operação update-or-create para o tipo do modelo, o identificador, o discriminador de escopo e a chave. Todos os valores JSON são armazenados, incluindo null, strings vazias, strings de espaços, arrays vazios, zero e false. Depois de uma escrita bem-sucedida, a relação modelSettings carregada é limpa para que a próxima leitura não reutilize dados desatualizados.

setMany

$user->settings()->setMany([
    'timezone' => 'Europe/Paris',
    'locale' => 'fr',
    'obsolete' => null,
]);

As chaves do iterable usam a mesma normalização de set(). Se várias chaves de entrada forem normalizadas para a mesma string, o último valor vence. Todos os valores usam um único upsert nativo do banco dentro de uma transação. O método valida o proprietário antes de consumir o iterable e limpa modelSettings uma vez depois do sucesso. Use forgetMany() para exclusão.

forget

$user->settings()->forget('timezone');

Para um proprietário válido, o método é seguro quando a chave não existe. Remover uma sobrescrita não remove seu valor padrão compartilhado. A relação carregada é limpa depois da exclusão.

forgetMany

$user->settings()->forgetMany(['timezone', 'locale']);

O método normaliza e elimina duplicatas do iterable, então remove somente essas chaves do escopo atual com uma exclusão. Chaves ausentes não têm efeito. Ele retorna void e limpa a relação carregada depois de uma chamada bem-sucedida, inclusive quando o iterable está vazio.

purge

$user->settings()->purge();

Em settings(), o método exclui todas as sobrescritas pertencentes ao proprietário persistido. Ele nunca exclui valores padrão da classe nem sobrescritas de outro proprietário. Em defaultSettings(), exclui todos os valores padrão dessa classe de modelo e mantém as sobrescritas dos modelos. Ele retorna void e limpa uma relação carregada depois do sucesso.

defaultSettings

O serviço retornado por defaultSettings() tem os mesmos oito métodos:

$defaults = (new User)->defaultSettings();

$defaults->set('timezone', 'UTC');
$defaults->setMany(['timezone' => 'UTC', 'locale' => 'en']);
$timezone = $defaults->get('timezone');
$hasTimezone = $defaults->has('timezone');
$all = $defaults->all();
$defaults->forget('timezone');
$defaults->forgetMany(['timezone', 'locale']);
$defaults->purge();

Exceções

DragonCode\LaravelModelSettings\Exceptions\InvalidSettingsOwnerException estende a classe PHP DomainException. Toda alteração por meio de settings() lança essa exceção antes de uma consulta ao armazenamento quando o modelo proprietário não foi persistido, inclusive quando recebeu uma chave antecipadamente.

Essa validação também ocorre antes do consumo de um iterable em lote. Alterações por meio de defaultSettings() continuam válidas porque esse serviço seleciona explicitamente o escopo dos valores padrão da classe. A leitura permanece determinística: um proprietário não persistido retorna null ou uma coleção vazia sem consultar sobrescritas, e has() retorna false. Um proprietário persistido com chave inteira 0 ou string '0' pode ler e alterar suas sobrescritas; is_default mantém essas linhas separadas dos padrões da classe.

DragonCode\LaravelModelSettings\Exceptions\InvalidPayloadCast é lançada quando uma conversão configurada para todo o modelo ou por chave está ausente, tem um tipo inválido, não implementa um contrato compatível ou não pode ser resolvida pelo container do Laravel. Sua mensagem pode identificar o modelo pai, a chave da configuração e a classe da conversão, mas nunca o payload.

DragonCode\LaravelModelSettings\Exceptions\InvalidSettingKey é lançada depois da normalização quando uma chave está vazia ou contém apenas espaços. Sua mensagem nunca inclui a chave rejeitada nem o payload da configuração.

DragonCode\LaravelModelSettings\Exceptions\BulkMutationException estende a classe PHP RuntimeException. Essa exceção encapsula falhas inesperadas ao consumir um iterable, serializar dados e acessar o armazenamento em setMany(), forgetMany() e purge(). Sua mensagem identifica a operação, a classe do proprietário e o escopo model ou default, sem expor chaves nem payloads das configurações. A exceção original está disponível por meio de getPrevious().

As exceções existentes do pacote InvalidSettingsOwnerException, InvalidPayloadCast e InvalidSettingKey não são encapsuladas. Se uma operação não vazia de setMany() falhar, a transação reverte o lote e a relação modelSettings já carregada não é limpa.

Veja também

• Trabalhando com configurações — entenda o comportamento de cada operação.
• Carregamento antecipado — use modelSettings sem consultas N+1.
• Conversões de payload — controle os valores retornados por get() e all().