Download the PHP package zenmanage/zenmanage-laravel without Composer

Zenmanage Laravel SDK

Add feature flags to your Laravel application in minutes. Control feature rollouts, A/B test, and manage configurations without deploying code.

Why Zenmanage?

• 🚀 Fast: Rules cached locally - ~1ms evaluation time
• 🎯 Targeted: Roll out features to specific users, organizations, or segments
• 🛡️ Safe: Graceful fallbacks and error handling built-in
• 📊 Insightful: Automatic usage tracking (optional)
• 🧪 Testable: Easy to mock in tests
• 🔧 Laravel Native: Service provider, facade, and artisan commands included

Installation

Requirements: Laravel 11+, PHP 8.1+

Key Compatibility

• Supported: case-sensitive server keys prefixed with srv_
• Not supported in Laravel SDK: client keys (cli_) and mobile keys (mob_) (initialization fails fast)

The service provider will be auto-discovered. If you need to manually publish the config:

Get Started in 60 Seconds

1. Get your server key (srv_...) from zenmanage.com

2. Set your token in .env:

3. Check a feature flag:

That's it! 🎉

Configuration

The only required configuration is the Environment Token (server key prefixed with srv_). Configuration values are set in config/zenmanage.php:

• environment_token - Your Zenmanage server key (srv_...) (required)
• cache_ttl - Cache duration in seconds (default: 3600)
• cache_backend - Cache strategy: 'memory' or 'filesystem' (default: 'memory')
• cache_directory - Directory for filesystem cache (optional)
• enable_usage_reporting - Enable automatic usage tracking (default: false)
• api_endpoint - API endpoint URL (default: https://api.zenmanage.com)
• webhook.enabled - Register the built-in webhook route (default: false, see Webhooks)
• webhook.path - Route path for the webhook endpoint (default: zenmanage/webhook)
• webhook.secret - Signing secret used to verify incoming webhook requests

The SDK client metadata is set automatically and is not configurable via environment:

• client_agent is hard-coded to zenmanage-laravel
• sdk_version is read from this package's Composer version metadata

Common Use Cases

Roll Out a Feature Gradually

A/B Testing

Percentage Rollouts

Gradually roll out features to a percentage of your users. The SDK handles bucketing automatically using a deterministic CRC32B hash — no manual bucket logic needed.

How it works:

• Configure the rollout percentage (0–100%) and a unique salt in the Zenmanage dashboard
• The SDK hashes salt:contextIdentifier to deterministically assign each user to a bucket (0–99)
• Users whose bucket is below the percentage get the rollout value; others get the fallback
• The same user always gets the same result (deterministic), and increasing the percentage never removes previously included users
• Rollout rules can further refine targeting within the rollout group (e.g., only US users in the rollout)

Note: A context identifier is required for bucketing. Without one, the user always receives the fallback value.

Feature Toggles by Organization

Configuration Values

Kill Switch for Problem Features

Working with Contexts

Contexts let you target flags to specific users, organizations, or any custom attributes. This is how you do gradual rollouts, A/B tests, and targeted features.

Simple Context (One Attribute)

Rich Context (Multiple Attributes)

What you get:

• type: Context type (user, organization, etc.)
• identifier: Unique identifier for targeting
• name: Human-readable display name
• attributes: Array of additional attributes for advanced targeting (plan, role, country, etc.)

When to use contexts:

• Rolling out to specific users (beta testers)
• Organization-based features (enterprise vs. free)
• Regional features (different countries)
• Role-based access (admins, moderators)
• Plan-based features (pro vs. basic)

Safe Defaults - Never Break Your App

Always provide defaults for critical features. The SDK will use them if:

• Flag doesn't exist yet
• API is unreachable
• Network issues occur

Inline Defaults (Recommended)

Default Collections (For Multiple Flags)

Priority Order

When retrieving a flag, the SDK checks in this order:

1. API Value - If flag exists in Zenmanage
2. Inline Default - Value passed to single('flag', default)
3. Collection Default - From DefaultsCollection
4. Exception - If none of the above

Retrieving Feature Flags

Using the Facade (Recommended)

Using Dependency Injection

Getting Flag Values

All Flags

Single Flag

Reporting Feature Flag Usage

When your application uses a feature flag, it can notify Zenmanage of the usage. This helps Zenmanage determine which flags are active and which may have been abandoned. Note that single() automatically reports usage, so you typically don't need to call this manually.

Refreshing Rules

You can manually refresh the flag rules from the API:

Webhooks

Instead of waiting for cache_ttl to lapse, the package can register a webhook endpoint that a Zenmanage environment webhook calls to immediately refresh cached flag rules. This is disabled by default — you opt in with a config flag:

When webhook.enabled is true, the package registers POST /zenmanage/webhook (customize the path with webhook.path / ZENMANAGE_WEBHOOK_PATH). Requests are rejected with a 401 unless they carry a valid X-Zenmanage-Signature header, verified against webhook.secret — so webhook.secret must be set for the endpoint to accept any requests.

To wire it up:

1. Publish the config if you haven't already: php artisan vendor:publish --tag=config.
2. Set ZENMANAGE_WEBHOOK_ENABLED=true and ZENMANAGE_WEBHOOK_SECRET in your .env.
3. In your Zenmanage dashboard, create an environment webhook pointing at https://your-app.com/zenmanage/webhook, and copy its signing secret (prefixed whsec_) into ZENMANAGE_WEBHOOK_SECRET.

On every verified request, the endpoint calls the same refreshRules() used above, so your app picks up flag changes immediately instead of on the next cache expiry.

Note: The webhook route is registered on its own, outside routes/web.php, so it isn't part of Laravel's web middleware group (and its CSRF protection) by default. If your application applies CSRF verification globally, exclude the webhook path explicitly:

Testing

Mock the Zenmanage facade in your tests:

Or use ::fake() to disable actual API calls:

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/zenmanage/zenmanage-laravel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The library is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Zenmanage's code bases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

What is Zenmanage?

Zenmanage allows you to control which features and settings are enabled in your application giving you better flexibility to deploy code and release features.

Zenmanage was started in 2024 as an alternative to highly complex feature flag tools. Learn more about us.