Weave Code
Laravel Model Flags Laravel Package
spatie/laravel-model-flags
A Laravel trait that adds flags to Eloquent models without migrations, plus scopes to query flagged models. Useful for tracking process state and building idempotent, restartable code like Artisan commands.
Add flags to Eloquent models
Frequently asked questions about Laravel Model Flags
- How do I install spatie/laravel-model-flags in a Laravel application?
- Install it with composer require spatie/laravel-model-flags, then publish and run the package migration to create the polymorphic flags table. Optionally publish the config file, which exposes only the flag_model key. Finally, add the HasFlags trait to each Eloquent model you want to flag. Integration is additive and touches no existing tables or columns.
- Does laravel-model-flags require extra columns or migrations on my existing tables?
- No. The package stores flags in a single separate polymorphic table keyed by flaggable type and id, so your existing models and schema stay untouched. You publish and run one migration for that table, which keeps adoption additive and low risk. Because all flags live in one shared table, plan for its growth over time.
- Which Laravel and PHP versions does spatie/laravel-model-flags support?
- The changelog shows an unbroken compatibility ladder: Laravel 11 support landed in 1.3.0, Laravel 12 in 1.4.1, and Laravel 13 in 1.4.2. PHP 8.0 and above has been supported since 1.0.1. Check the release notes before upgrading a major Laravel version, and pin a version in composer.json for production apps.
- How do I make an Artisan command idempotent or restartable using model flags?
- Query with the notFlagged scope, perform the work, then call flag() on each model, as in User::notFlagged('wasSentPromotionMail')->each(...). If the command is cancelled or fails halfway, the next run skips records that were already flagged, so users only get the mail once. This check-then-act pattern is safe for a single sequential command. It is not safe if two workers process the same model at the same time.
- Is the notFlagged plus flag pattern safe with multiple queue workers running concurrently?
- No, not on its own. The documented idempotency pattern is check-then-act, so two workers can both read a model as not flagged before either writes, and both will perform the work. Treat the package as a convenience layer over a has-many relation, not as workflow or locking infrastructure. For concurrent workers, add an external lock, a database advisory lock, or a job-level idempotency key.
- Does the flags table have a unique index so duplicate flags cannot be created?
- The README does not document a unique constraint on flaggable_type, flaggable_id and name, and the write semantics of a repeated flag() call are not spelled out, so verify the shipped migration before relying on it. If you need strict single-flag guarantees under concurrency, add your own unique index and confirm whether flag() upserts or plain inserts. For sequential use this rarely matters, but for parallel processing it does.
- Can calling hasFlag on many models cause N+1 queries?
- Yes. Unless the flags relation is already loaded, hasFlag() will hit the relation per call, which becomes an N+1 in loops over collections. Eager load the flags relation when iterating so flag checks resolve from memory. Prefer the flagged and notFlagged query scopes when filtering in the database rather than looping in PHP.
- How do I query all models that have a certain flag with laravel-model-flags?
- Use the provided scopes: User::flagged('myFlag')->get() returns models with the flag and User::notFlagged('myFlag')->get() returns those without it. These are almost certainly whereHas and whereDoesntHave subqueries, so their cost scales with the shared flags table across all flaggable models. Make sure the flaggable columns and name are indexed in your own migration if the table grows large.
- Can I customize the Flag model, use enums for flag names, or purge old flags?
- Yes for customization. The published config exposes only flag_model, and extending Spatie\ModelFlags\Models\Flag is the supported extension point for casts, observers, or retention logic. Enum support arrived in 1.4.0, so mandate backed enums instead of string literals to avoid typos and flag name drift. There is no built-in retention story, so you own purging the monotonically growing flags table.
- Is laravel-model-flags a good fit for state machines, workflows, or high-volume event data?
- No. It has no transition rules or ordering guarantees, so anything state-machine-like belongs elsewhere. High-cardinality event data is also a poor fit because each flag is a row per model with no retention policy. It is best used for lightweight per-record markers, one-time backfills, and progress checkpoints in Artisan commands and jobs.
Weaver
How can I help you explore Laravel packages today?