laravel model status

Atribuir status aos modelos Eloquent

Imagine que você deseja que um modelo Eloquent tenha um status. É facilmente resolvido apenas adicionando um campo status a esse modelo e pronto. Mas caso você precise de um histórico de alterações de status ou armazene algumas informações extras sobre o motivo da alteração de um status, apenas adicionar um único campo não será suficiente.

Este pacote fornece uma característica HasStatuses que, uma vez instalada em um modelo, permite que você faça coisas como isto:

 // set a status
$ model -> setStatus ( ' pending ' , ' needs verification ' );

// set another status
$ model -> setStatus ( ' accepted ' );

// specify a reason
$ model -> setStatus ( ' rejected ' , ' My rejection reason ' );

// get the current status
$ model -> status (); // returns an instance of SpatieModelStatusStatus

// get the previous status
$ latestPendingStatus = $ model -> latestStatus ( ' pending ' );

$ latestPendingStatus -> reason ; // returns 'needs verification' 

Apoie-nos

Investimos muitos recursos na criação dos melhores pacotes de código aberto. Você pode nos apoiar comprando um de nossos produtos pagos.

Agradecemos muito que você nos envie um cartão postal de sua cidade natal, mencionando qual(is) de nossos pacotes você está usando. Você encontrará nosso endereço em nossa página de contato. Publicamos todos os cartões postais recebidos em nosso mural virtual de cartões postais.

Instalação

Você pode instalar o pacote via compositor:

composer require spatie/laravel-model-status

Você deve publicar a migração com:

php artisan vendor:publish --provider= " SpatieModelStatusModelStatusServiceProvider " --tag= " migrations "

Migre a tabela statuses :

php artisan migrate

Opcionalmente, você pode publicar o arquivo de configuração com:

php artisan vendor:publish --provider= " SpatieModelStatusModelStatusServiceProvider " --tag= " config "

Este é o conteúdo do arquivo que será publicado em config/model-status.php

 return [

    /*
     * The class name of the status model that holds all statuses.
     *
     * The model must be or extend `SpatieModelStatus Status ` .
     */
    ' status_model ' => Spatie  ModelStatus Status::class,

    /*
     * The name of the column which holds the ID of the model related to the statuses .
     *
     * You can change this value if you have set a different name in the migration for the statuses table .
     */
    ' model_primary_key_attribute ' => ' model_id ' ,

];

Uso

Adicione a característica HasStatuses a um modelo no qual você gostaria de usar status.

 use Spatie  ModelStatus  HasStatuses ;

class YourEloquentModel extends Model
{
    use HasStatuses;
}

Defina um novo status

Você pode definir um novo status como este:

 $ model -> setStatus ( ' status-name ' );

Um motivo para a mudança de status pode ser passado como um segundo argumento.

 $ model -> setStatus ( ' status-name ' , ' optional reason ' );

Recuperando status

Você pode obter o status atual do modelo:

 $ model -> status ; // returns a string with the name of the latest status

$ model -> status (); // returns the latest instance of `SpatieModelStatusStatus`

$ model -> latestStatus (); // equivalent to `$model->status()`

Você também pode obter o status mais recente de um determinado nome:

 $ model -> latestStatus ( ' pending ' ); // returns an instance of `SpatieModelStatusStatus` that has the name `pending`

Obtenha todos os nomes de status disponíveis para o modelo.

 $ statusNames = $ model -> getStatusNames (); // returns a collection of all available status names.

Os exemplos a seguir retornarão status do tipo status 1 ou status 2 , o que for mais recente.

 $ lastStatus = $ model -> latestStatus ([ ' status 1 ' , ' status 2 ' ]);

// or alternatively...
$ lastStatus = $ model -> latestStatus ( ' status 1 ' , ' status 2 ' );

Todos os status associados de um modelo podem ser recuperados assim:

 $ allStatuses = $ model -> statuses ;

Isso verificará se o modelo tem status:

 $ model -> setStatus ( ' status1 ' );

$ isStatusExist = $ model -> hasStatus ( ' status1 ' ); // return true
$ isStatusExist = $ model -> hasStatus ( ' status2 ' ); // return false

Recuperando modelos com um determinado estado mais recente

O escopo currentStatus retornará modelos que possuem um status com o nome fornecido.

 $ allPendingModels = Model:: currentStatus ( ' pending ' );

//or array of statuses
$ allPendingModels = Model:: currentStatus ([ ' pending ' , ' initiated ' ]);
$ allPendingModels = Model:: currentStatus ( ' pending ' , ' initiated ' );

Recuperando modelos sem um determinado estado

O escopo otherCurrentStatus retornará todos os modelos que não possuem um status com o nome fornecido, incluindo qualquer modelo que não possua nenhum status associado a eles.

 $ allNonPendingModels = Model:: otherCurrentStatus ( ' pending ' );

Você também pode fornecer uma série de nomes de status para excluir da consulta.

 $ allNonInitiatedOrPendingModels = Model:: otherCurrentStatus ([ ' initiated ' , ' pending ' ]);

// or alternatively...
$ allNonInitiatedOrPendingModels = Model:: otherCurrentStatus ( ' initiated ' , ' pending ' );

Validando um status antes de defini-lo

Você pode adicionar validação personalizada ao definir um status substituindo o método isValidStatus :

 public function isValidStatus ( string $ name , ? string $ reason = null ): bool
{
    . . .

    if (! $ condition ) {
        return false ;
    }

    return true ;
}

Se isValidStatus retornar false uma exceção SpatieModelStatusExceptionsInvalidStatus será lançada.

Você pode ignorar a validação com o método forceSetStatus :

 $ model -> forceSetStatus ( ' invalid-status-name ' );

Verifique se o status foi atribuído

Você pode verificar se um status específico foi definido no modelo a qualquer momento usando o método hasEverHadStatus :

 $ model -> hasEverHadStatus ( ' status 1 ' );

Verifique se o status nunca foi atribuído

Você pode verificar se um status específico nunca foi definido no modelo a qualquer momento usando o método hasNeverHadStatus :

 $ model -> hasNeverHadStatus ( ' status 1 ' );

Excluir status do modelo

Você pode excluir qualquer status definido no modelo a qualquer momento usando o método deleteStatus :

Exclua o status único do modelo:

 $ model -> deleteStatus ( ' status 1 ' );

Exclua vários status do modelo de uma só vez:

 $ model -> deleteStatus ([ ' status 1 ' , ' status 2 ' ]);

Eventos

O evento SpatieModelStatusEventsStatusUpdated será despachado quando o status for atualizado.

 namespace Spatie  ModelStatus  Events ;

use Illuminate  Database  Eloquent  Model ;
use Spatie  ModelStatus  Status ;

class StatusUpdated
{
    /** @var SpatieModelStatus Status | null */
    public $ oldStatus ;

    / ** @var SpatieModelStatus Status */
    public $ newStatus ;

    / ** @var IlluminateDatabaseEloquent Model */
    public $ model ;

    public function __construct (? Status $ oldStatus , Status $ newStatus , Model $ model )
    {
        $ this -> oldStatus = $ oldStatus ;

        $ this -> newStatus = $ newStatus ;

        $ this -> model = $ model ;
    }
}

Modelo personalizado e migração

Você pode alterar o modelo usado especificando um nome de classe na chave status_model do arquivo de configuração model-status .

Você pode alterar o nome da coluna usada na tabela de status ( model_id por padrão) ao usar uma migração personalizada onde você alterou isso. Nesse caso, basta alterar a chave model_primary_key_attribute do arquivo de configuração model-status .

Teste

Este pacote contém testes de integração desenvolvidos por orquestral/testbench.

Você pode executar todos os testes com:

composer test

Registro de alterações

Consulte CHANGELOG para obter mais informações sobre o que mudou recentemente.

Contribuindo

Consulte CONTRIBUINDO para obter detalhes.

Segurança

Se você encontrou um bug relacionado à segurança, envie um email para [email protected] em vez de usar o rastreador de problemas.

Créditos

• Thomas Verhelst
• Freek Van der Herten
• Todos os colaboradores

Licença

A licença MIT (MIT). Consulte Arquivo de licença para obter mais informações.