Laravel Eloquent Flag Laravel Package

Product Decisions This Supports

• Build vs. buy for "flag" plumbing. Every content, subscription, or moderation feature re-implements the same trio: a boolean/timestamp column, an isX() check, a publish()/unpublish() mutator, and a query scope that hides inactive rows. This package collapses that into use HasPublishedFlag; — roughly 4 files and a test suite per flag you don't write. Decision: standardize on the package instead of a homegrown HasStatus trait, unless your flags need cross-entity logic.
• Feature scoping for state-based workflows. Directly supports roadmaps for publishing/drafting, moderation (Approved/Rejected), account lifecycle (Active/Suspended), trial and license expiry (timestamp flags), and archival (Kept). If a roadmap item is "let editors unpublish without deleting," this is a same-day feature, not a sprint.
• Schema and data-model decisions. The Boolean vs. Timestamp dimension is an explicit PM-visible trade-off: booleans are simple but lose the "when"; timestamp flags (published_at, expired_at) give you scheduling and expiry for free and remain queryable. Push engineering to default to timestamp flags for anything user-facing where "when did this happen" will eventually be asked in a report.
• Default-visibility decisions (Classic vs. Inverse). This is the product-defining choice: Classic hides flagged-false rows by default (a storefront shows only published items); Inverse hides flagged-true rows by default (an inbox shows only unread). Getting this wrong produces silent "where did my records go?" tickets, so it's worth an explicit sign-off per entity.
• Scope-application policy. Scopes only filter when the model implements shouldApplyXxxScope(): bool. That makes "safe by default" vs. "explicit opt-in" a deliberate, per-model product decision rather than a framework accident — useful when admin tooling must see all rows while the public API must not.
• De-risking dependency choice. MIT, no service provider, pure traits, supports Laravel 9–13 / PHP 8.0–8.5, and a release as recent as 2026-03-01. Low lock-in: the code is small enough to vendor or fork in an afternoon if maintenance stalls. Treat it as a utility dependency, not a strategic bet — a 134-star, low-opportunity-score package is leverage, not a platform.

When to Consider This Package

Adopt when:

• Three or more models share the same flag semantics (published, active, approved, verified, expired), and you're copying the same trait/scope/helper code between them.
• The team wants consistent naming and events (published, publishedUndone) across features so listeners, notifications, and search indexing hook in predictably.
• Your "state" is genuinely binary or date-driven. Most content and account states are.
• You want the flag behavior to live on the model (testable, portable) rather than smeared across controllers, form requests, and repository queries.
• You're on a supported Laravel/PHP combination and already comfortable with global scopes.

Look elsewhere when:

• You need a real state machine — multi-state transitions with allowed-path validation, guards, and transition side effects. Use spatie/laravel-model-states; stacking both is a smell.
• You need a per-record audit trail of who flipped the flag and when. This package fires events (good hooks for spatie/laravel-activitylog), but it does not store history itself.
• Flags drive money or access control at scale and transitions must be race-safe. Trait mutators are not a substitute for transactional/locked updates; plan that work explicitly.
• The team is unfamiliar with global scopes, or the codebase is heavy on raw Query Builder / reporting SQL where implicit filters become a debugging hazard.
• Your flags are really derived facts (e.g., "active" = starts_at <= now < ends_at). Storing a duplicated boolean creates drift; compute it.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT), actively maintained library that removes a recurring category of boilerplate from our Laravel codebase. It lets us ship publishing, moderation, and account-status features faster and with fewer inconsistencies, because every flag behaves the same way and emits the same events. The risk profile is low: no runtime service, no vendor account, no data migration, and the code is small enough to fork if it ever stops being maintained. It is not a differentiator — it's cost avoidance. Expect it to save roughly a day of engineering per flag we'd otherwise hand-roll, plus the ongoing cost of keeping near-duplicate traits in sync.

To engineering: Trait-composable, declare(strict_types=1), final scope classes, tested across PHP 8.1–8.5 with Orchestra Testbench. You get isPublished() / publish() / undoPublish(), query macros (withNotPublished(), onlyNotPublished()), attribute casting handled in initialize*Helpers(), and model events for side effects. Global scopes are opt-in via shouldApplyXxxScope(), so nothing filters silently unless you ask it to. No service provider, no config to publish, no bootstrapping. Two caveats to own deliberately: choose Classic vs. Inverse scope direction per model as an explicit decision, and don't use this where a proper state machine or audit log is required — it composes with those tools, it doesn't replace them.