README

想象一下，你想让Eloquent模型持有一个状态。通过只需在该模型中添加一个status字段即可轻松解决。但是，如果你需要状态变更的历史记录或需要存储一些额外信息，以说明状态变更的原因，仅添加单个字段是不够的。

此包提供了一个HasStatuses特性，一旦安装到模型上，就可以让你执行此类操作

// 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 \Spatie\ModelStatus\Status

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

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

支持我们

我们投入了大量资源来创建最好的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，并说明您正在使用我们哪个包。您可以在我们的联系页面上找到我们的地址。我们将在我们的虚拟明信片墙上发布所有收到的明信片。

安装

您可以通过Composer安装此包

composer require spatie/laravel-model-status

您必须使用以下命令发布迁移

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="migrations"

迁移statuses表

php artisan migrate

可选地，您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="config"

以下是将在config/model-status.php中发布的文件的正文

return [

    /*
     * The class name of the status model that holds all statuses.
     *
     * The model must be or extend `Spatie\ModelStatus\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',

];

使用

将HasStatuses特性添加到您想要使用状态的模型中。

use Spatie\ModelStatus\HasStatuses;

class YourEloquentModel extends Model
{
    use HasStatuses;
}

设置新的状态

您可以通过这种方式设置新的状态

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

状态变更的原因可以作为第二个参数传递。

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

检索状态

您可以得到模型当前的状态

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

$model->status(); // returns the latest instance of `Spatie\ModelStatus\Status`

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

您还可以获取给定名称的最新状态

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

获取模型的所有可用状态名称。

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

以下示例将返回类型为status 1或status 2的状态，取最新者。

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

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

可以像这样检索模型的关联状态

$allStatuses = $model->statuses;

这将检查模型是否有状态

$model->setStatus('status1');

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

检索具有给定最新状态的模式

currentStatus作用域将返回具有给定名称状态的模型。

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

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

检索没有给定状态的模式

otherCurrentStatus作用域将返回所有没有给定名称状态的模型，包括任何没有关联任何状态的模式。

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

您还可以提供要排除的数组中的状态名称。

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

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

在设置状态之前验证状态

您可以通过覆盖isValidStatus方法来添加设置状态时的自定义验证

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

    if (! $condition) {
        return false;
    }

    return true;
}

如果isValidStatus返回false，则将抛出Spatie\ModelStatus\Exceptions\InvalidStatus异常。

您可以使用forceSetStatus方法绕过验证

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

检查状态是否已分配

您可以通过使用hasEverHadStatus方法在任何时候检查模型上是否已设置特定状态。

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

检查状态是否从未分配

您可以通过使用hasNeverHadStatus方法在任何时候检查模型上是否从未设置特定状态。

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

从模型中删除状态

您可以通过使用deleteStatus方法在任何时候删除已设置在模型上的任何给定状态。

从模型中删除单个状态

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

一次性从模型中删除多个状态

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

事件

当状态更新时，将触发Spatie\ModelStatus\Events\StatusUpdated事件。

namespace Spatie\ModelStatus\Events;

use Illuminate\Database\Eloquent\Model;
use Spatie\ModelStatus\Status;

class StatusUpdated
{
    /** @var \Spatie\ModelStatus\Status|null */
    public $oldStatus;

    /** @var \Spatie\ModelStatus\Status */
    public $newStatus;

    /** @var \Illuminate\Database\Eloquent\Model */
    public $model;

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

        $this->newStatus = $newStatus;

        $this->model = $model;
    }
}

自定义模型和迁移

您可以通过在model-status配置文件的status_model键中指定类名来更改模型。

当您使用自定义迁移更改了该列名时，您可以更改状态表中使用的列名（默认为model_id）。在这种情况下，只需更改model-status配置文件中的model_primary_key_attribute键即可。

测试

此包包含由orchestral/testbench提供支持的集成测试。

您可以使用以下命令运行所有测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现了关于安全性的错误，请通过security@spatie.be发送邮件，而不是使用问题跟踪器。

鸣谢

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

spatie / laravel-model-status

维护者

详细信息