Feature Flags Laravel Package

Technical Evaluation

Architecture fit

The package targets a real gap in the Laravel ecosystem. Laravel Pennant covers the mechanics of toggling features but stops short of the governance concerns this package advertises: typed flag definitions, ownership, expiry, and a telemetry boundary. Those are the features that typically push teams toward a commercial platform (LaunchDarkly, Unleash). If the implementation is clean, this is architecturally the right layer — a resolution service behind a facade, consumed by controllers, jobs, and Blade, with policy metadata adjacent to the flag definition rather than scattered across config files.

Fit depends on one structural question: is this a standalone Composer package or a nwidart/laravel-modules module? The module- repository naming suggests the latter. If it drags in a full module loader to evaluate a boolean, that is a meaningful cost for a team not already using that convention — it changes your service provider boot order, your autoload strategy, and your deploy artifact shape. Confirm before committing.

Integration feasibility

Mechanically trivial: MIT license, Composer install, package auto-discovery, no vendor lock-in and no licence negotiation. The blocker is not effort, it is confidence. Zero stars, zero dependents, and a single-vendor namespace (liberusoftware) is the signature of an internal extraction published for convenience rather than a supported product. The opportunity score (44.9) against an overall score of 19.8 tells the story: the problem space is valuable, the artifact is unproven.

The 2026-10-27 last-release date is a flag in itself. Either the metadata is wrong, the tag is misdated, or the package is being versioned ahead of reality. Any of those means your dependency resolver is consuming something with an unreliable release history, and you should read the git tags directly rather than trusting the index.

Technical risk

• Bus factor of one. No external contributors means no external bug reports. You will find the edge cases in production.
• No security review. Flag evaluation touches request context, tenant resolution, and potentially user identity. Nobody has audited the targeting path.
• Unvalidated semantics. Deterministic bucketing for stable rollout is easy to get subtly wrong — hash input composition, salt handling, and modulo bias all affect cohort stability. If the bucketing changes between versions, users flip in and out of a rollout.
• Expiry is a loaded gun. Automatic expiry is the package's most attractive feature and its most dangerous. A flag that silently evaluates to false after a date will turn off a feature in production with no deploy and no human in the loop.
• Low score is a signal, not a verdict. A 19.8 composite on a 0-star package mostly measures absence of evidence. Treat it as "unknown", not "bad", and spend the spike budget to convert unknown into known.

Key questions

1. What are the storage drivers, and is the flag store read on every evaluation or cached? What is the cache TTL and invalidation mechanism?
2. Is bucketing deterministic across processes and stable across package versions? How is the hash seeded?
3. What is the documented fail behaviour when the flag store is unreachable — open, closed, or per-flag default?
4. Does expiry hard-disable the flag, alert, or no-op? Is there a pre-expiry warning hook?
5. What Laravel and PHP version range is actually tested in CI, and does CI exist at all?
6. Is the package Octane-safe and queue-safe? How does actor targeting degrade when there is no HTTP request (workers, scheduler, CLI)?
7. What is the tenant resolution contract — does the package assume a resolver, or require you to bind one?
8. What does the "telemetry boundary" emit, where does it go, and does it carry actor or tenant identifiers that create GDPR scope?
9. Is ownership metadata enforced anywhere (CI check, artisan command) or purely documentary? Unowned flags rot.
10. What is the versioning and backwards-compatibility policy, and who is on the other end of an issue?

Integration Approach

Stack fit

Assume Laravel 10–12 and PHP 8.1+. The realistic decision is not "adopt or not" but "adopt as engine or adopt as reference". Two viable positions:

• Replace Pennant if the governance features (ownership, expiry, telemetry) are the actual driver and the code survives the spike.
• Wrap and defer — keep Pennant as the evaluation primitive and borrow this package's metadata model (typed definitions, owner, expiry, telemetry contract) as an internal convention. Lower risk, loses the ready-made implementation.

Do not run both engines over the same flag namespace. Duplicate resolution paths produce two sources of truth and a debugging nightmare during an incident.

Migration path

1. Spike (2–3 days, timeboxed). Branch install, three flags, one tenant-scoped, one actor-targeted, one with a near-future expiry. Verify determinism by evaluating the same actor across a restart and across a cache flush. Verify expiry behaviour deliberately. Exit criteria: you can state the fail mode of every branch.
2. Inventory. Enumerate existing config() and env() flags, Laravel Pennant usage, and hardcoded conditionals. Most teams find 20–60 implicit flags. You will not migrate them all; pick the ones with blast radius.
3. Vendor decision. If the spike surfaces gaps you can patch in a day, fork under your org namespace and own it. If it surfaces architectural mismatches, stop — the wrap-and-defer path is cheaper.
4. Shadow mode. Run the package alongside the current mechanism for the top three flags, log divergences, resolve, then cut over.
5. Flags-as-code. Move high-risk flags into version-controlled definitions so changes go through review.

Compatibility

Confirm database support for your production engine and for SQLite in tests — packages that only test MySQL often break the test suite for everyone else. Confirm Octane compatibility (no mutable static state in the resolver). Confirm behaviour under php artisan and queue workers where no authenticated actor exists. Confirm the package does not assume a specific tenancy package; if it hard-codes one, that is a fork-level change.

Sequencing

Spike → ADR recording the fail-mode policy and the fork decision → fork if needed → shadow mode on three flags → telemetry wiring → ownership and expiry as required metadata enforced in CI. Do not enable expiry until you have alerting on approaching expiries; the feature's value is inversely proportional to your visibility into it.

Operational Impact

Maintenance

Plan to own this. A 0-star, 0-dependent package with a single vendor namespace has no maintenance community to inherit. Budget roughly 0.1–0.2 FTE for the first two quarters, mostly review time and small patches, dropping after that if the surface area stays small. A fork under your own namespace is the honest default — it makes the ownership explicit and removes the ambiguity about whether upstream will fix something.

Support

There is no support channel. Your on-call rotation is the support channel. That is acceptable for a flag evaluation library — it is not acceptable for something that gates production features unless you have written the runbook yourself. Write it during the spike, while you still have questions.

Scaling

Evaluation is cheap if flag definitions are cached; it is a per-request database read if they are not. Confirm the caching story before rollout, because flag checks accumulate — a mature codebase ends up with dozens per request. Watch for cache stampede at deploy time when the cache is cold and traffic is at peak; a short TTL plus a jittered warm-up is usually enough. Bucketing itself is O(1). The scaling risk is not compute, it is consistency: stale caches after a rollout change produce cohorts that disagree with each other for the length of the TTL.

Failure modes

• Flag store unavailable. Define fail-open vs fail-closed per flag, not globally. A kill switch should fail open (keep the feature on) only if the feature is safe; a risky feature should fail closed.
• Expiry fires in production. The most likely self-inflicted incident. Mitigate with pre-expiry alerting (30/7/1 days), a policy that expiry requires an owner acknowledgement, and a dry-run mode that reports what would be disabled.
• Missing actor context. Queue workers, scheduled jobs, and CLI commands have no actor. Ensure the fallback is explicit and logged, not silent.
• Stale ownership. Teams reorganise; flags outlive their owners. Run a quarterly unowned-flag report or the governance layer becomes decoration.
• Bucketing drift. A patch release changing hash composition silently reshuffles cohorts mid-rollout. Pin the version and test cohort stability on upgrade.

Ramp-up

Low for any Laravel developer — the concepts are familiar from Pennant and the API is small. The real ramp-up cost is organisational: getting teams to declare an owner and an expiry on every flag, and to accept that expiry means the flag will be removed. That is a process change, not a technical one, and it is where most feature-flag rollouts quietly fail. Budget for a short internal write-up and one example PR per team.

Verdict

Pilot, do not standardise. The problem framing is strong and the feature set is the right shape for a governed flag system, but zero adoption, a single maintainer, and an anomalous release date mean you are evaluating an artifact, not a product. A timeboxed spike plus a deliberate fork decision converts this from an unknown-risk dependency into a known one — and either outcome is a better position than adopting on the strength of the description alone.