Weave Code
Laravel Model Flags Laravel Package
spatie/laravel-model-flags
Add lightweight “flags” to Eloquent models via a trait—store process state without extra columns. Check, set, and clear flags, and query with flagged/notFlagged scopes. Ideal for idempotent, restartable jobs like one-time emails or migrations.
Add flags to Eloquent models
Frequently asked questions about Laravel Model Flags
- How do I add flags to an Eloquent model in Laravel using this package?
- Use the `HasFlags` trait in your model. Add `use HasFlags;` at the top of your model file, then call methods like `$model->flag('name')` to set a flag or `$model->hasFlag('name')` to check it. No migrations are needed for the flags themselves—the package handles a dedicated `flags` table automatically.
- Can I use this package with Laravel 13 or 11? What about PHP 8.0?
- Yes, the package is actively maintained for Laravel 11–13 and supports PHP 8.0+. Check the [release notes](https://github.com/spatie/laravel-model-flags/releases) for version-specific changes. Always test in a staging environment before upgrading in production.
- Will flags slow down my application if I check them frequently (e.g., per request)?
- Each flag check (`hasFlag()`) triggers a database query, which can add overhead in high-frequency scenarios. Mitigate this by caching flag results (e.g., with Redis) or batching operations. For read-heavy workloads, consider denormalizing critical flags into boolean columns.
- How do I query models with or without specific flags in Laravel?
- Use the built-in scopes: `Model::flagged('flag_name')->get()` retrieves models with the flag, while `Model::notFlagged('flag_name')->get()` excludes them. These scopes work seamlessly with Eloquent’s query builder and can be chained with other conditions like `where()` or `with()`.
- Can I use this package for tracking temporal state (e.g., 'lastFlaggedAt') or only binary flags?
- The package is designed for binary state (true/false flags), but you can extend it to track timestamps by adding a `flagged_at` column to the `flags` table and updating it manually. For temporal tracking, consider a dedicated `statuses` table or Laravel’s `activity_log` packages instead.
- What happens if I have thousands of flags per model? Will the flags table bloat?
- Unbounded flags can inflate the `flags` table. Mitigate this by implementing flag expiration (e.g., soft-deleting old flags) or using Laravel’s soft deletes. For high-volume scenarios, evaluate alternatives like a JSON column for flags or a dedicated state table.
- How do I test models with flags in PHPUnit or Pest?
- Mock the `HasFlags` trait in unit tests by stubbing the `flags()` method. For example: `$model->shouldReceive('flags')->andReturn(new FlagCollection());`. For integration tests, use the actual trait but reset the `flags` table between tests to avoid state pollution.
- Is there a way to bulk-set or clear flags for multiple models at once?
- Yes, use the `flag()` or `unflag()` methods in a loop or with `each()`. For bulk operations, leverage Eloquent’s query builder: e.g., `Model::where(...)->get()->each(fn($m) => $m->flag('name'))`. For large datasets, consider chunking or database transactions to avoid timeouts.
- Does this package work with PostgreSQL, SQLite, or only MySQL?
- The package is database-agnostic and supports all Laravel-supported databases (MySQL, PostgreSQL, SQLite, etc.). Test migrations in your target environment, especially for PostgreSQL’s JSON/JSONB handling or SQLite’s case sensitivity. The core functionality remains identical across databases.
- Are there alternatives to this package for managing model state in Laravel?
- Alternatives include custom boolean columns, Laravel’s `status` packages (e.g., `spatie/laravel-status`), or serialized JSON columns for flags. For complex workflows, consider `spatie/laravel-activitylog` or `spatie/laravel-permission` for role-based state. Choose based on your need for simplicity (flags) vs. auditability (activity logs).
Weaver
How can I help you explore Laravel packages today?