{"id":13828595,"url":"https://github.com/spatie/laravel-model-status","last_synced_at":"2025-05-14T17:02:29.173Z","repository":{"id":46047136,"uuid":"119671555","full_name":"spatie/laravel-model-status","owner":"spatie","description":"Easily add statuses to your models","archived":false,"fork":false,"pushed_at":"2025-02-21T13:25:25.000Z","size":271,"stargazers_count":992,"open_issues_count":1,"forks_count":85,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-14T03:58:27.377Z","etag":null,"topics":["eloquent","laravel","model","php","status"],"latest_commit_sha":null,"homepage":"https://freek.dev/973-a-package-to-assign-statuses-to-eloquent-models","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://spatie.be/open-source/support-us"}},"created_at":"2018-01-31T10:20:27.000Z","updated_at":"2025-04-04T04:40:56.000Z","dependencies_parsed_at":"2024-04-24T15:32:27.781Z","dependency_job_id":"c850ddf4-8039-4ab1-97c5-333bb841021f","html_url":"https://github.com/spatie/laravel-model-status","commit_stats":{"total_commits":213,"total_committers":32,"mean_commits":6.65625,"dds":0.6525821596244131,"last_synced_commit":"10f27d8c9915cda2a58ab5b49fe0c4cc83ab961d"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-model-status","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-model-status/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-model-status/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-model-status/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/laravel-model-status/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190366,"owners_count":22029629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eloquent","laravel","model","php","status"],"created_at":"2024-08-04T09:02:54.204Z","updated_at":"2025-05-14T17:02:29.100Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://spatie.be/open-source/support-us"],"categories":["PHP"],"sub_categories":[],"readme":"# Assign statuses to Eloquent models\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/laravel-model-status.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-model-status)\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/spatie/laravel-model-status/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)\n![Check \u0026 fix styling](https://github.com/spatie/laravel-model-status/workflows/Check%20\u0026%20fix%20styling/badge.svg)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-model-status.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-model-status)\n\nImagine you want to have an Eloquent model hold a status. It's easily solved by just adding a `status` field to that model and be done with it. But in case you need a history of status changes or need to store some extra info on why a status changed, just adding a single field won't cut it.\n\nThis package provides a `HasStatuses` trait that, once installed on a model, allows you to do things like this:\n\n```php\n// set a status\n$model-\u003esetStatus('pending', 'needs verification');\n\n// set another status\n$model-\u003esetStatus('accepted');\n\n// specify a reason\n$model-\u003esetStatus('rejected', 'My rejection reason');\n\n// get the current status\n$model-\u003estatus(); // returns an instance of \\Spatie\\ModelStatus\\Status\n\n// get the previous status\n$latestPendingStatus = $model-\u003elatestStatus('pending');\n\n$latestPendingStatus-\u003ereason; // returns 'needs verification'\n```\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/laravel-model-status.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/laravel-model-status)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/laravel-model-status\n```\n\nYou must publish the migration with:\n```bash\nphp artisan vendor:publish --provider=\"Spatie\\ModelStatus\\ModelStatusServiceProvider\" --tag=\"migrations\"\n```\n\nMigrate the `statuses` table:\n\n```bash\nphp artisan migrate\n```\n\nOptionally you can publish the config-file with:\n```bash\nphp artisan vendor:publish --provider=\"Spatie\\ModelStatus\\ModelStatusServiceProvider\" --tag=\"config\"\n```\n\nThis is the contents of the file which will be published at `config/model-status.php`\n\n```php\nreturn [\n\n    /*\n     * The class name of the status model that holds all statuses.\n     *\n     * The model must be or extend `Spatie\\ModelStatus\\Status`.\n     */\n    'status_model' =\u003e Spatie\\ModelStatus\\Status::class,\n\n    /*\n     * The name of the column which holds the ID of the model related to the statuses.\n     *\n     * You can change this value if you have set a different name in the migration for the statuses table.\n     */\n    'model_primary_key_attribute' =\u003e 'model_id',\n\n];\n```\n\n## Usage\n\nAdd the `HasStatuses` trait to a model you like to use statuses on.\n\n```php\nuse Spatie\\ModelStatus\\HasStatuses;\n\nclass YourEloquentModel extends Model\n{\n    use HasStatuses;\n}\n```\n\n### Set a new status\n\nYou can set a new status like this:\n\n```php\n$model-\u003esetStatus('status-name');\n```\n\nA reason for the status change can be passed as a second argument.\n\n```php\n$model-\u003esetStatus('status-name', 'optional reason');\n```\n\n### Retrieving statuses\n\nYou can get the current status of model:\n\n```php\n$model-\u003estatus; // returns a string with the name of the latest status\n\n$model-\u003estatus(); // returns the latest instance of `Spatie\\ModelStatus\\Status`\n\n$model-\u003elatestStatus(); // equivalent to `$model-\u003estatus()`\n```\n\nYou can also get latest status of a given name:\n\n```php\n$model-\u003elatestStatus('pending'); // returns an instance of `Spatie\\ModelStatus\\Status` that has the name `pending`\n```\nGet all available status names for the model.\n\n```php\n$statusNames = $model-\u003egetStatusNames(); // returns a collection of all available status names.\n```\n\nThe following examples will return statusses of type `status 1` or `status 2`, whichever is latest.\n\n```php\n$lastStatus = $model-\u003elatestStatus(['status 1', 'status 2']);\n\n// or alternatively...\n$lastStatus = $model-\u003elatestStatus('status 1', 'status 2');\n```\n\nAll associated statuses of a model can be retrieved like this:\n\n```php\n$allStatuses = $model-\u003estatuses;\n```\nThis will check if the model has status:\n\n```php\n$model-\u003esetStatus('status1');\n\n$isStatusExist = $model-\u003ehasStatus('status1'); // return true\n$isStatusExist = $model-\u003ehasStatus('status2'); // return false\n```\n### Retrieving models with a given latest state\n\nThe `currentStatus` scope will return models that have a status with the given name.\n\n```php\n$allPendingModels = Model::currentStatus('pending');\n\n//or array of statuses\n$allPendingModels = Model::currentStatus(['pending', 'initiated']);\n$allPendingModels = Model::currentStatus('pending', 'initiated');\n```\n\n### Retrieving models without a given state\n\nThe `otherCurrentStatus` scope will return all models that do not have a status with the given name, including any model that does not have any statuses associated with them.\n\n```php\n$allNonPendingModels = Model::otherCurrentStatus('pending');\n```\n\nYou can also provide an array of status names to exclude from the query.\n```php\n$allNonInitiatedOrPendingModels = Model::otherCurrentStatus(['initiated', 'pending']);\n\n// or alternatively...\n$allNonInitiatedOrPendingModels = Model::otherCurrentStatus('initiated', 'pending');\n```\n\n### Validating a status before setting it\n\nYou can add custom validation when setting a status by overwriting the `isValidStatus` method:\n\n```php\npublic function isValidStatus(string $name, ?string $reason = null): bool\n{\n    ...\n\n    if (! $condition) {\n        return false;\n    }\n\n    return true;\n}\n```\n\nIf `isValidStatus` returns `false` a `Spatie\\ModelStatus\\Exceptions\\InvalidStatus` exception will be thrown.\n\nYou may bypass validation with the `forceSetStatus` method:\n\n```php\n$model-\u003eforceSetStatus('invalid-status-name');\n```\n\n### Check if status has been assigned\n\nYou can check if a specific status has been set on the model at any time by using the `hasEverHadStatus` method:\n\n```php\n$model-\u003ehasEverHadStatus('status 1');\n```\n\n### Check if status has never been assigned\n\nYou can check if a specific status has never been set on the model at any time by using the `hasNeverHadStatus` method:\n\n```php\n$model-\u003ehasNeverHadStatus('status 1');\n```\n\n### Delete status from model\n\nYou can delete any given status that has been set on the model at any time by using the `deleteStatus` method:\n\nDelete single status from model:\n\n```php\n$model-\u003edeleteStatus('status 1');\n```\n\nDelete multiple statuses from model at once:\n\n```php\n$model-\u003edeleteStatus(['status 1', 'status 2']);\n```\n\n### Events\n\nThe`Spatie\\ModelStatus\\Events\\StatusUpdated`  event will be dispatched when the status is updated.\n\n```php\nnamespace Spatie\\ModelStatus\\Events;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Spatie\\ModelStatus\\Status;\n\nclass StatusUpdated\n{\n    /** @var \\Spatie\\ModelStatus\\Status|null */\n    public $oldStatus;\n\n    /** @var \\Spatie\\ModelStatus\\Status */\n    public $newStatus;\n\n    /** @var \\Illuminate\\Database\\Eloquent\\Model */\n    public $model;\n\n    public function __construct(?Status $oldStatus, Status $newStatus, Model $model)\n    {\n        $this-\u003eoldStatus = $oldStatus;\n\n        $this-\u003enewStatus = $newStatus;\n\n        $this-\u003emodel = $model;\n    }\n}\n```\n\n### Custom model and migration\n\nYou can change the model used by specifying a class name in the `status_model` key of the `model-status` config file.\n\nYou can change the column name used in the status table (`model_id` by default) when using a custom migration where you changed\nthat. In that case, simply change the `model_primary_key_attribute` key of the `model-status` config file.\n\n### Testing\n\nThis package contains integration tests that are powered by [orchestral/testbench](https://github.com/orchestral/testbench).\n\nYou can run all tests with:\n\n```bash\ncomposer test\n```\n\n### Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n### Security\n\nIf you've found a bug regarding security please mail [security@spatie.be](mailto:security@spatie.be) instead of using the issue tracker.\n\n## Credits\n\n- [Thomas Verhelst](https://github.com/TVke)\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-model-status","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Flaravel-model-status","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-model-status/lists"}