Weave Code
Laravel Model Flags Laravel Package
spatie/laravel-model-flags
Add lightweight flags to Eloquent models without extra columns. Set and check flags, then query with handy flagged/notFlagged scopes. Ideal for idempotent, restartable jobs and commands (e.g., send a mail only once per user).
Add flags to Eloquent models
Frequently asked questions about Laravel Model Flags
- How do I add flags to an Eloquent model without running migrations?
- Use the `HasFlags` trait in your model. No migrations are needed—flags are stored as JSON in a single column (default: `flags`). Just add `use HasFlags;` to your model and start using methods like `$model->flag('name')` or `$model->hasFlag('name')`.
- Can I use this package with Laravel 10+? What about older versions?
- This package is officially tested with Laravel 10+. Check the `composer.json` constraints for exact version support. Older versions may work but aren’t guaranteed. Always verify compatibility before adopting.
- How do I query models with or without specific flags?
- Use built-in scopes: `Model::flagged('flagName')` returns models with the flag, while `Model::notFlagged('flagName')` returns those without it. These scopes work like Eloquent queries and can be chained with other conditions.
- Is this package suitable for high-write workloads (e.g., thousands of flag updates per second)?
- No. JSON column operations can become a bottleneck under heavy write loads. For high-volume use cases, consider a dedicated flags table or a key-value store like Redis. Test performance with your expected workload.
- How do I handle concurrent flag updates to avoid race conditions?
- Use database transactions or optimistic locking (e.g., `$model->increment('version')`). Wrap flag operations in a transaction to ensure atomicity. Example: `DB::transaction(fn() => $model->flag('name'))`.
- Can I archive or audit flag changes over time?
- No, flags are stored as JSON and aren’t versioned by default. To audit changes, log flag updates in a separate table or use model observers to track modifications. For archiving, consider splitting flags into normalized columns.
- Does this package work with PostgreSQL’s JSONB or MySQL’s JSON? Are there performance differences?
- Yes, it works with any Laravel-supported database. PostgreSQL’s JSONB is generally faster and more feature-rich than MySQL’s JSON for querying. Test your specific database to compare performance, especially for large datasets.
- How do I remove this package if I later decide to switch to a normalized flags table?
- Removing the package doesn’t delete flag data. You’ll need to manually migrate flag values into separate columns using a custom migration. Back up your database before making changes.
- Are there alternatives to this package for feature flags or workflow state management?
- For feature flags, consider `spatie/laravel-feature-flags`, which is optimized for dynamic toggles. For workflow state, a dedicated flags table or a state machine package like `spatie/laravel-state-machine` might be better.
- How do I test models with flags in PHPUnit? Should I mock the trait?
- You can mock the trait’s methods (e.g., `hasFlag`, `flag`) in unit tests. For integration tests, verify flag persistence by saving models and asserting flag values. Test edge cases like concurrent updates or malformed JSON.
Weaver
How can I help you explore Laravel packages today?