Download the PHP package turtlemilitia/laravel-featureflags without Composer

Laravel Feature Flags

A Laravel package for feature flag evaluation with local caching. Designed to work with the Turtle Militia feature flags dashboard.

Requirements: PHP 8.2+ and Laravel 11 or 12.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Usage
• Targeting Rules
• Percentage Rollouts
• Experiments
• Segments
• Webhooks
• Fallback Behavior
• Conversion Tracking
• Error Tracking
• Local Development & Testing
• Observability
• Performance
• GDPR Compliance

Features

• Local evaluation - Flags are evaluated locally, no API call per check
• Smart caching - Syncs flag configuration and caches locally
• Targeting rules - User-based targeting with flexible conditions
• Percentage rollouts - Gradual rollouts with sticky bucketing
• Experiments - A/B testing with automatic variant assignment
• Segments - Reusable user groups
• Telemetry - Evaluation tracking sent to dashboard
• Error tracking - Correlate errors with feature flags (Sentry, Bugsnag, Flare)
• Conversion tracking - Automatic attribution to flag variants
• Blade directives - @feature directive for templates
• Auto-context - Automatically resolves authenticated user context
• Cache warming - featureflags:warm command for deployments
• Events - Optional Laravel events for monitoring
• GDPR compliant - Hold telemetry until user consent

Installation

Quick Start

Add your API credentials to .env:

Check a flag:

Configuration

Publish the config file to customize settings:

Most settings work via environment variables:

Usage

In Blade templates:

Context

Context is resolved automatically from the authenticated user. Implement HasFeatureFlagContext on your User model:

Any model can implement the interface and be passed as context:

You can also pass context explicitly:

Nested Traits

Context supports nested arrays with dot notation in targeting rules. This is useful for targeting based on relationships:

Then target with dot notation in your rules: subscription.plan.name equals "pro" or subscription.status equals "active".

Targeting Rules

The dashboard supports these operators for targeting rules:

Example rule (configured in dashboard):

Version-Based Targeting

Semver operators are useful when your Laravel app serves as an API backend for mobile apps or versioned frontends. To use them, create a version resolver that provides version traits to the context.

Create a class implementing ResolvesVersion:

Register it in your config:

The resolved traits are automatically merged into every context, so you can create rules like app_version semver_gte "2.0.0" in your dashboard without passing the version explicitly.

Percentage Rollouts

Rollouts use sticky bucketing based on the flag key and context ID. The same context will always get the same result for a given flag.

Attribute-Based Rollouts

The percentage_of operator enables attribute-based percentage rollouts within targeting rules. Unlike global percentage rollouts, this lets you target a percentage of users based on any attribute:

This rule matches 50% of pro users:

• Sticky bucketing: Same user always gets the same result for the same flag
• Per-flag bucketing: Users may be in different buckets for different flags
• Combinable: Use with other conditions for precise targeting (e.g., "25% of enterprise users in Europe")

Experiments

Experiments enable A/B testing with automatic variant assignment. When you create an experiment on a flag in the dashboard, the package automatically assigns users to variants deterministically.

How It Works

1. Define variants on a flag in the dashboard (e.g., ["blue", "red", "green"] for a button color test)
2. Create an experiment on that flag with a goal event (e.g., purchase)
3. Start the experiment - the package now randomly assigns users to variants
4. Track conversions - conversions are automatically attributed to the variant each user saw

Variant Assignment

When an experiment is running, the package uses deterministic bucketing to assign users to variants:

The assignment is:

• Deterministic: Same user always gets the same variant for a given flag
• Even distribution: Users are split evenly across all variants
• Sticky: Assignment persists across sessions and requests

Evaluation Priority

Flags are evaluated in this order:

1. Disabled - Returns default value
2. Targeting rules - If user matches a rule, returns rule value (rules always win)
3. Experiment - If experiment is running, assigns user to a variant
4. Percentage rollout - If configured, applies rollout logic
5. Default value - Returns the flag's default

This means targeting rules take precedence over experiments. Use this to:

• Force specific users into a variant for QA testing
• Exclude certain users from experiments entirely

Traffic Percentage (Holdout Groups)

Experiments support traffic percentage for holdout groups:

Users in the holdout group are excluded from the experiment entirely and always see the default value.

Conversion Attribution

Conversions are automatically linked to the flags evaluated in the same request:

The package tracks all flag evaluations during a request and includes them when sending conversion events. No manual attribution needed.

Segments

Segments are reusable user groups defined in the dashboard:

Segments support all the same operators as regular trait conditions.

Webhooks

Configure your dashboard to send webhooks to /webhooks/feature-flags. The package automatically invalidates and refreshes the cache when flags change.

Set FEATUREFLAGS_WEBHOOK_SECRET in your .env for signature verification. The secret is required - requests are rejected with 401 if unset.

To sync manually:

Or programmatically:

Fallback Behavior

When the API is unavailable:

• cache (default): Use cached flags, fail silently
• default: Return configured default value for unknown flags
• exception: Throw FlagSyncException

Configure in config/featureflags.php:

Conversion Tracking

Track conversions for A/B test analysis:

Automatic Flag Attribution

Every conversion automatically includes all flags evaluated during the current request. The dashboard uses this to:

• Attribute conversions to experiment variants
• Calculate conversion rates per variant
• Determine statistical significance

No manual flag specification needed - the package handles attribution automatically.

Explicit Attribution

For cases where you need to attribute a conversion to a specific flag (e.g., async jobs, webhooks):

Error Tracking

Errors are automatically correlated with evaluated feature flags, helping identify if a new feature is causing issues. Requires FEATUREFLAGS_TELEMETRY_ENABLED=true.

Setup

Register the service provider:

Once registered:

1. Every flag evaluation is tracked during the request
2. When an exception occurs, all evaluated flags are attached
3. Third-party error trackers (Sentry, Bugsnag, Flare) receive the flag context via Laravel's Context facade
4. Your dashboard shows error rates correlated by flag value

What Gets Tracked

Monitor Wrapper

For critical code paths:

If the callback throws, the error is tracked with the exact flag value before global exception handling.

Manual Tracking

Configuration

Supported Error Trackers

Automatic integration requires Laravel 11+ (uses the Context facade). On Laravel 10, use Feature::getEvaluatedFlags() to wire up your error tracker manually.

Local Development & Testing

Enable local mode for offline development and testing:

Define flags in config/featureflags.php under local.flags:

Export current flags from the API for offline work:

Mocking the Facade

For unit tests, mock specific flag checks:

Testing with Context

To test that rules evaluate correctly for different contexts:

Testing Percentage Rollouts

Rollouts are deterministic - the same context ID always gets the same result for a given flag:

Observability

Events

Optional Laravel events for monitoring. Disabled by default.

Or per-event in config/featureflags.php:

Performance

Cache Warming

Pre-warm the cache on deployment:

Sampling

Reduce telemetry volume for high-traffic sites:

Flush Rate Limiting

Queue telemetry flushes to avoid hitting your plan's rate limit:

Async Mode (Recommended)

By default, telemetry is sent synchronously at the end of each request. Enable async mode to dispatch telemetry to a queue job instead, preventing API latency from affecting response times.

Or in config:

Requirements:

• A configured queue driver (Redis, database, SQS, etc.)
• A running queue worker (php artisan queue:work)

Benefits:

• Telemetry API calls don't block your response
• Failed sends are automatically retried (up to 3 times with 5-second backoff)
• Queue workers can handle load spikes better than inline HTTP calls

GDPR Compliance

For GDPR-compliant telemetry, enable "hold until consent" mode. Feature flag evaluation works immediately, but telemetry is queued until the user consents.

Usage

How It Works

1. First visit: Device ID cookie (ff_device_id) is set for consistent bucketing
2. Flag checks: Evaluation works normally, telemetry events are queued
3. User consents: grantConsent() flushes queued events and sets consent cookie (ff_telemetry_consent)
4. Subsequent visits: Consent cookie is detected, telemetry flows normally

Configuration

After consent_ttl_days, the consent cookie expires and the user will need to re-consent.

License

MIT

Support

• Dashboard & docs: https://turtlemilitia.com
• Issues: https://github.com/turtlemilitia/laravel-featureflags/issues