Flag It Bundle Laravel Package

Getting Started

1. Confirm runtime compatibility. The package requires PHP >= 8.1 and Symfony 6.4 or 7.x components. In a Laravel app, check composer show symfony/* before installing to avoid dependency conflicts.
2. Install and publish config. Require the package, then publish its config (typically php artisan vendor:publish --tag=feature-flags-config). The file to inspect first is the feature flag config containing clients and defaults.
3. Understand the three configuration layers. The package resolves flags from:
   • Global flags (top-level configuration)
   • Per-client overrides under clients
   • Fallback values under defaults
4. Wire up client resolution. Bind ClientContextInterface in a service provider. The provided DefaultClientContext reads the current client from an environment variable or a container parameter. For multi-tenant apps, replace it with your own context implementation.
5. First use case. Inject FeatureFlagManager into a controller or service and check a flag:

   if ($this->featureFlags->isEnabled('new-checkout')) {
       // new flow
   }
   

   Start with a single flag in defaults, override it for one client, and verify the fallback behavior.

Implementation Patterns

• Multi-client configuration. Structure config around defaults for safe fallbacks and clients for targeted rollouts:

  return [
      'defaults' => [
          'new-checkout' => false,
      ],
      'clients' => [
          'acme' => [
              'new-checkout' => true,
          ],
      ],
  ];
  

  Use global flags for application-wide defaults and per-client entries only where behavior must differ.

• Context-based resolution. Implement ClientContextInterface to resolve the client from the current request, authenticated tenant, subdomain, or header. Bind it early in the request lifecycle so the manager has a stable client before any flag checks.

• Per-request middleware. If the client varies per request, set or refresh the context in middleware. Avoid resolving the client in a singleton that is constructed before the request is available.

• Fallback-aware checks. Rely on the manager’s global → per-client → default resolution rather than duplicating fallback logic in application code. This keeps rollout rules in one place.

• Testing. Swap the ClientContextInterface binding with a test implementation that returns a known client. This is more reliable than mutating environment variables or container parameters between tests.

• Service overrides. The release fixes autowiring for array arguments by defining parameters explicitly. If you decorate or replace FeatureFlagManager, pass the clients and defaults arrays explicitly in your service definition.

• Extension point. Decorate FeatureFlagManager or ClientContextInterface to add logging, metrics, or audit trails around flag resolution without changing the package internals.

Gotchas and Tips

• Beta stability. This is a 1.0.0-beta release. Pin the exact version in composer.json and review changelogs before upgrading.
• Symfony constraint. The package targets Symfony 6.4/7.x. Laravel apps on older Symfony component versions may hit Composer conflicts; resolve those before adopting the package.
• Default context source. DefaultClientContext reads from an environment variable or parameter. Confirm the exact variable/parameter name in the package config and set it consistently across local, staging, and production.
• Context timing. Resolve the client before the first flag check. Resolving too early in a service provider can lock in the wrong client for the request.
• Fallback precedence. Verify the documented precedence for global, per-client, and default values. Do not assume per-client overrides always win without checking the package’s resolution order.
• Array autowiring. The explicit parameter fix helps standard usage, but custom service definitions that replace or extend the manager must still provide the clients and defaults array arguments.
• Configuration caching. If flags are config-driven, remember that Laravel’s config cache will freeze flag values until cleared. Plan deploys and flag changes accordingly.
• No persistence implied. The release notes describe configuration-based flags, not database-backed flags. Treat flag changes as deploy-time configuration unless the package documents additional storage.