Flag It Bundle Laravel Package

Product Decisions This Supports

• Feature, roadmap, and release strategy: Per-client flags let one codebase ship capabilities to a subset of tenants (design partners, beta cohorts, enterprise tiers) without long-lived branches or environment duplication — directly supports staged rollouts and progressive delivery decisions.
• Build vs. buy: This is a lightweight, self-hosted alternative to LaunchDarkly/Unleash/Flagsmith. Choose build-on-this when flag volume is modest, targeting rules are simple (global / per-client / default fallback), and keeping flag evaluation in-process (no network hop, no vendor data-processing agreement) is a product or compliance advantage.
• Multi-tenant / B2B SaaS decisions: The clients + defaults config model plus ClientContextInterface is the key capability — it makes per-tenant entitlement and "on/off per customer" gating a first-class concept rather than an ad-hoc if (tenant_id === ...) tangle.
• Operational and risk decisions: DefaultClientContext reading from env or a parameter means the active client is a deploy-time/runtime decision, not a hardcoded one — enabling safe canary tenants and instant kill-switches without a deploy.
• Extensibility decisions: Implementing ClientContextInterface allows custom resolution (subdomain, JWT claim, header, DB lookup) — a product decision about how tenancy is determined can be deferred, as long as the interface is implemented.

When to Consider This Package

Consider adoption when:

• You are a multi-tenant or B2B SaaS product where feature availability varies by customer/plan — the per-client config model is the primary justification.
• You want flag evaluation in-process with no external SaaS dependency, no per-seat flag billing, and full control over flag data.
• Your needs are simple: boolean/static flags with global → per-client → default fallback precedence. No percentage rollouts, no complex rule DSL, no targeting by user attributes beyond client identity.
• You are on PHP 8.1+ and Symfony 6.4/7.x (Laravel-compatible), and can pin to a specific beta tag.
• You need a small, auditable surface — flag logic you can read in an afternoon and debug without vendor support.

Look elsewhere when:

• You need percentage rollouts, A/B experiment assignment, or statistical analysis — this is a toggle manager, not an experimentation platform.
• You need user-level or attribute-based targeting (geo, plan, role) beyond client-level scoping; evaluate whether a custom ClientContextInterface implementation stretches the model too far.
• You require audit logs, approval workflows, scheduled flag changes, or a non-engineer UI — none are in scope.
• You need vendor SLAs, SOC 2, or 24/7 support — a v1.0.0-beta with no prior assessment has no operational track record.
• You have heavy flag sprawl (hundreds of flags, many owners) — config-file-driven flags get hard to govern without a management plane.

Adoption guardrails: treat beta status as a real risk. Wrap the package behind a thin internal interface, pin the exact version, and confirm the DefaultClientContext env/parameter resolution matches your tenancy model before rollout.

How to Pitch It (Stakeholders)

For executives: This is a small, self-hosted feature-flag library that lets us switch capabilities on or off per customer without redeploying. It's the mechanism that makes design-partner betas, tiered entitlements, and instant rollback of a bad feature cheap. The trade-off is build vs. buy: we avoid vendor per-seat flag costs and keep customer data in-house, but we forgo vendor SLAs, dashboards, and experimentation tooling. Recommendation: pilot on one non-critical rollout in a single tenant before broad adoption.

For engineering: v1.0.0-beta gives us a stable core flag manager plus multi-client configuration — clients/defaults config blocks, a ClientContextInterface we can implement for whatever tenancy signal we use (subdomain, header, JWT), and a DefaultClientContext reading from env or a parameter. Resolution precedence is global → per-client → default, which is predictable and easy to reason about. The beta also fixes service autowiring for array arguments, so container wiring should be clean. Requirements are PHP 8.1+ and Symfony 6.4/7.x. Action items: pin the version, wrap it behind an internal flag interface so we can swap it, and decide our ClientContextInterface implementation early since the package leaves that to us.