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 spatie/laravel-model-flags?
- Use the `HasFlags` trait on your model and call `flag('name')` to set a flag or `hasFlag('name')` to check it. No migrations are needed—the package creates a `flags` table automatically. Example: `use HasFlags; class User extends Model { use HasFlags; }` then `$user->flag('processed');`.
- Does spatie/laravel-model-flags work with Laravel 11/12/13?
- Yes, the package officially supports Laravel 11, 12, and 13. Check the [release notes](https://github.com/spatie/laravel-model-flags/releases) for version-specific updates, as Spatie occasionally aligns with Laravel’s minor releases.
- Can I query models with or without specific flags efficiently?
- Absolutely. Use the built-in scopes: `Model::flagged('flagName')->get()` or `Model::notFlagged('flagName')->get()`. These scopes optimize queries with joins to the `flags` table, but performance may degrade with high flag cardinality.
- What’s the best way to handle idempotent Laravel jobs or Artisan commands with this package?
- Use `notFlagged()` to filter unprocessed records, then flag them after completion. Example: `User::notFlagged('sent_email')->each(fn($user) => Mail::to($user)->send(new Email()) && $user->flag('sent_email'))`. This ensures retries only process unflagged items.
- Will this package slow down my application if I have thousands of flags per model?
- Potential performance impact exists due to joins on the `flags` table. For high-volume use cases, add a composite index on `(model_id, name)` and benchmark queries. Consider alternatives like JSON columns if flags are sparse or low-volume.
- How do I delete flags when a model is deleted? Can I soft-delete them instead?
- Flags are hard-deleted by default when the model is deleted. To soft-delete flags, set `deleteFlagsOnModelDelete` to `false` in the config and manually handle flag cleanup. For soft-deleted models, use `withTrashed()` with flag queries.
- Can I store additional metadata (e.g., timestamps, user IDs) with flags?
- Yes, extend the `Flag` model to add custom columns like `created_by` or `metadata`. Use `Flag::create(['name' => 'flag', 'model_id' => $model->id, 'created_by' => auth()->id()])` for manual control. For enums, use `Flag::enum('status', ['pending', 'completed'])`.
- Is there a way to bulk-add or remove flags for many models at once?
- Yes, use `Flag::insert()` for bulk creation or `Flag::where('name', 'flag')->delete()` for bulk removal. For model-specific bulk operations, chain with Eloquent: `Model::where(...)->get()->each(fn($m) => $m->flag('name'))`.
- How do I test flag functionality in Laravel Pest or PHPUnit?
- Mock the `HasFlags` trait or use the package’s built-in methods directly. Example: `$user = new User(); $user->flag('test'); $this->assertTrue($user->hasFlag('test'))`. For database tests, refresh the `flags` table after each test or use transactions.
- What are the alternatives to spatie/laravel-model-flags for simple flagging needs?
- For lightweight needs, consider Eloquent accessors (e.g., `$model->flags = json_encode(['flag' => true])`) or a JSON column. For complex workflows, evaluate `spatie/laravel-activitylog` or Laravel Nova resources. This package excels for idempotency and query scopes.
Weaver
How can I help you explore Laravel packages today?