Laravel Bitflags Laravel Package

Product Decisions This Supports

• Data modeling for bounded flag sets. This package is the deciding tool when a product feature is "a fixed, small set of on/off attributes on a record" — notification channels per user, per-tenant feature toggles, weekday/recurrence selection, permission or capability masks, content visibility combinations. It lets you ship that as one integer column instead of a pivot table or a dozen boolean columns, which keeps schema and migrations cheap.
• Build vs. buy on a small utility. A bitmask cast is something an engineer could hand-roll in under an hour. The buy case here is narrow but real: a typed CastsAttributes implementation that matches current Laravel contracts, correct null → [] handling (the decbin(null) deprecation is exactly the kind of thing that bites in production on a PHP upgrade), plus helpers and query macros so filtering happens in SQL with bitwise operators rather than in PHP after loading rows.
• Roadmap scoping for flag-heavy features. Committing to this package is a decision to keep flag sets static and code-defined. It supports roadmap items like "add a fifth notification channel" (a constant plus a migration if you need a new column) and argues against roadmap items like "let admins define their own flags" — that's a different data model.
• Platform upgrade planning. v1.0.0 requires PHP 8.2+ and Laravel 11/12/13. This release is a forcing function: if the app is still on Laravel 8–10, the dependency decision is "pin ^0.1 and track it as tech debt," and it should be sequenced with the framework upgrade rather than after it.
• Query-path decisions. Because the package exposes query macros, it supports the choice to push flag filtering into the database (e.g. "all users subscribed to email + SMS") instead of in-memory filtering — a meaningful decision for tables that grow.

When to Consider This Package

Adopt when most of these hold:

• The flag set is small and stable — realistically a handful of flags, well inside the integer bit width, and defined in code rather than by end users.
• Flags are read often, written rarely, and are almost always consumed as a group ("which channels is this user on?") rather than individually audited.
• You need SQL-level filtering on combinations of flags and want macros instead of repeating whereRaw('flags & ? = ?', ...) in every repository.
• You are on Laravel 11+ and PHP 8.2+, or planning to be within the same release cycle.
• You want a stable, semver-committed API — the 1.0 tag matters here; pre-1.0 dependencies are a real friction point in a security or platform review.

Look elsewhere when:

• Flags are user-defined or unbounded, or you need per-flag metadata (who set it, when, why). Use a pivot table or a JSON column with a proper schema.
• You need per-flag audit trails, per-flag timestamps, or per-flag permissions — bitmasks erase that.
• Ad-hoc SQL and BI tooling are a first-class consumer. flags = 13 is opaque to analysts; document the mapping or expose a view.
• You are on Laravel 8–10 or PHP < 8.2 — you can pin ^0.1, but treat it as a stopgap, not an adoption.
• Your team is small and the flag set is one or two booleans — plain columns are clearer and cost nothing.

How to Pitch It (Stakeholders)

For executives: This is a small, single-purpose open-source utility, not a platform bet. It removes one category of schema sprawl — the "we added eight boolean columns and a pivot table to track notification preferences" problem — and it just reached a 1.0 stable release, which means the API is committed and it isn't going to churn under us. Zero vendor lock-in: it's a thin cast over an integer column, so if we ever drop it we keep the data and delete a dependency.

For engineering: v1.0.0 is the first stable tag. It types the Bitflags cast to Laravel's current CastsAttributes contract, fixes null columns casting to [] (avoiding PHP's decbin(null) deprecation), and promotes illuminate/database and illuminate/contracts to explicit dependencies so installs are predictable. Breaking change: it requires PHP 8.2+ and Laravel 11–13; Laravel 8–10 and older PHP must stay on v0.1. No application code changes are needed for existing users of the cast, helpers, or query macros — the upgrade is composer require aw-studio/laravel-bitflags:^1.0. The tradeoff to document internally: bitmask columns are unreadable in raw SQL and in BI tools, so the flag-to-bit mapping belongs in the README and in code constants, not tribal knowledge.