PHPackages                             spatie/laravel-model-flags - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. spatie/laravel-model-flags

ActiveLibrary[Database & ORM](/categories/database)

spatie/laravel-model-flags
==========================

Add flags to Eloquent models

1.4.2(2mo ago)4301.1M↑22.7%21[1 PRs](https://github.com/spatie/laravel-model-flags/pulls)1MITPHPPHP ^8.1CI passing

Since Oct 20Pushed 1mo ago4 watchersCompare

[ Source](https://github.com/spatie/laravel-model-flags)[ Packagist](https://packagist.org/packages/spatie/laravel-model-flags)[ Docs](https://github.com/spatie/laravel-model-flags)[ RSS](/packages/spatie-laravel-model-flags/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (20)Versions (15)Used By (1)

[![Social Card of Laravel Model Flags](/art/socialcard.png)](/art/socialcard.png)

Add flags to Eloquent models
============================

[](#add-flags-to-eloquent-models)

[![Latest Version on Packagist](https://camo.githubusercontent.com/40d06171497e2639128759d1f22a0c7446989e1bffcb3440749f74888f974f12/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f6c61726176656c2d6d6f64656c2d666c6167732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-model-flags)[![Total Downloads](https://camo.githubusercontent.com/0ea8c26295e84a1f8a49c5d4d05a25766998aecc217db78c50a340b2af4a5de8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f6c61726176656c2d6d6f64656c2d666c6167732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-model-flags)

This package offers a trait that allows you to add flags to an Eloquent model. These can be used to quickly save the state of a process, update, migration, etc... to a model, without having to add an additional column using migrations.

```
$user->hasFlag('receivedMail'); // returns false

$user->flag('receivedMail'); // flag the user as having received the mail

$user->hasFlag('receivedMail'); // returns true
```

It also provides scopes to quickly query all models with a certain flag.

```
User::flagged('myFlag')->get(); // returns all models with the given flag
User::notFlagged('myFlag')->get(); // returns all models without the given flag
```

Though there are other usages, the primary use case of this package is to easily build idempotent (aka restartable) pieces of code. For example, when writing an Artisan command that sends a mail to each user. Using flags, you can make sure that when the command is cancelled (or fails) half-way through, in the second invocation, a mail will only be sent to users that haven't received one yet.

```
// in an Artisan command

User::notFlagged('wasSentPromotionMail')
    ->each(function(User $user) {
        Mail::to($user->email)->send(new PromotionMail())

        $user->flag('wasSentPromotionMail');
    });
});
```

No matter how many times you would execute this command, users would only get the mail once.

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/64d67ded82f82d48f0d4bde512d1d75dd9d3fa957e3e5a4324a8bd783f091f49/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f6c61726176656c2d6d6f64656c2d666c6167732e6a70673f743d31)](https://spatie.be/github-ad-click/laravel-model-flags)

We 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).

We 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).

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require spatie/laravel-model-flags
```

Behind the scenes, the flags and the relation to a model will be stored in the `flags` table.

To create that `flags` table, you must publish and run the migrations once with:

```
php artisan vendor:publish --tag="model-flags-migrations"
php artisan migrate
```

Optionally, you can publish the config file with:

```
php artisan vendor:publish --tag="model-flags-config"
```

This is the contents of the published config file:

```
return [
    /*
     * The model used as the flag model.
     */
    'flag_model' => Spatie\ModelFlags\Models\Flag::class,
];
```

Usage
-----

[](#usage)

To add flaggable behaviour to a model, simply make it use the `Spatie\ModelFlags\Models\Concerns\HasFlags` trait

```
use Illuminate\Database\Eloquent\Model;
use Spatie\ModelFlags\Models\Concerns\HasFlags;

class YourModel extends Model
{
    use HasFlags;
}
```

These functions will become available.

```
// add a flag
$model->flag('myFlag');

// returns true if the model has a flag with the given name
$model->hasFlag('myFlag');

// remove a flag
$model->unflag('myFlag');

 // returns an array with the name of all flags on the model
$model->flagNames();

// use the `flags` relation to delete all flags on a model
$user->flags()->delete();

// use the `flags` relation to delete a particular flag on a model
$user->flags()->where('name', 'myFlag')->delete();
```

A flag can only exist once for a model. When flagging a model with the same flag again, the `updated_at` attribute of the flag will be updated.

```
$model->flag('myFlag');

// after a while
$model->flag('myFlag'); // update_at will be updated
```

You can get the date of the last time a flag was used on a model.

```
$model->lastFlaggedAt(); // returns the update time of the lastly updated flag
$model->lastFlaggedAt('myFlag') // returns the updated_at of the `myFlag` flag on the model
$model->lastFlaggedAt('doesNotExist') // returns null if there is no flag with the given name
```

You'll also get these scopes:

```
// query all models that have a flag with the given name
YourModel::flagged('myFlag');

// query all models that have do not have a flag with the given name
YourModel::notFlagged('myFlag');
```

To remove a flag from all models in one go, you can delete the flag using the `Spatie\ModelFlags\Models\Flag` model.

```
use Spatie\ModelFlags\Models\Flag;

// remove myFlag from all models
Flag::where('name', 'myFlag')->delete();
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

And a special thanks to [Caneco](https://twitter.com/caneco) for the logo ✨

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance87

Actively maintained with recent releases

Popularity59

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 54.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~111 days

Recently: every ~278 days

Total

12

Last Release

80d ago

Major Versions

0.0.2 → 1.0.02022-10-21

PHP version history (2 changes)0.0.1PHP ^8.1

1.0.1PHP ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (74 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (20 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (16 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (6 commits)")[![grantholle](https://avatars.githubusercontent.com/u/1189456?v=4)](https://github.com/grantholle "grantholle (5 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (5 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (4 commits)")[![jafar-albadarneh](https://avatars.githubusercontent.com/u/21292175?v=4)](https://github.com/jafar-albadarneh "jafar-albadarneh (2 commits)")[![caneco](https://avatars.githubusercontent.com/u/502041?v=4)](https://github.com/caneco "caneco (1 commits)")[![raksbisht](https://avatars.githubusercontent.com/u/15016564?v=4)](https://github.com/raksbisht "raksbisht (1 commits)")[![ricventu](https://avatars.githubusercontent.com/u/3369838?v=4)](https://github.com/ricventu "ricventu (1 commits)")[![xiCO2k](https://avatars.githubusercontent.com/u/823088?v=4)](https://github.com/xiCO2k "xiCO2k (1 commits)")

---

Tags

eloquentflagslaravelmodelspatielaravellaravel-model-flags

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/spatie-laravel-model-flags/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-laravel-model-flags/health.svg)](https://phpackages.com/packages/spatie-laravel-model-flags)
```

###  Alternatives

[spatie/laravel-backup

A Laravel package to backup your application

6.0k21.8M191](/packages/spatie-laravel-backup)[spatie/laravel-sql-commenter

Add comments to SQL queries made by Laravel

1931.4M1](/packages/spatie-laravel-sql-commenter)[spatie/laravel-deleted-models

Automatically copy deleted records to a separate table

409109.8k4](/packages/spatie-laravel-deleted-models)[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

423715.4k1](/packages/clickbar-laravel-magellan)[wnx/laravel-backup-restore

A package to restore database backups made with spatie/laravel-backup.

203330.1k2](/packages/wnx-laravel-backup-restore)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)