Download the PHP package zenmanage/zenmanage-php without Composer

Zenmanage PHP SDK

Add feature flags to your PHP 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

Installation

Upgrading

See UPGRADING.md for details on breaking changes and migration steps.

Requirements: PHP 8.0+

Key Compatibility

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

Get Started in 60 Seconds

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

2. Initialize the SDK:

3. Check a feature flag:

That's it! 🎉

Common Use Cases

Roll Out a New Feature Gradually

Note: Call withContext() on the flag manager to ensure context is sent to the API when loading rules.

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

Setup for Your Application

Laravel Integration

[!TIP] There is an official Laravel integration on GitHub: zenmanage/zenmanage-laravel. Use it to plug Zenmanage directly into your Laravel app with minimal setup.

Create a service provider to make Zenmanage available throughout your app:

Then use dependency injection anywhere:

Symfony Integration

Standalone PHP Application

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)

How Rule Evaluation Works

The SDK supports three types of rule selectors for targeting:

1. Segment Selector

Matches against a list of specific context identifiers:

If a rule value omits type (or sets it to null), only the identifier is compared.

2. Context Selector

Same as segment - matches against context type and identifier:

If a rule value omits type (or sets it to null), only the identifier is compared.

3. Attribute Selector

Matches against additional context attributes (plan, country, role, etc.):

Supported operators for all selectors:

• equal - Exact match (most common)
• contains - Value contains the comparison string
• starts_with - Value starts with the comparison string
• ends_with - Value ends with the comparison string
• regex - Value matches regex pattern
• greater_than, less_than, in, etc. (see OperatorEvaluator for full list)

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

Performance - Caching Rules

The SDK caches flag rules to minimize API calls. Rules are fetched once, then served from cache.

Default Setup (In-Memory)

Out of the box, flags are cached in memory for the request duration. Zero configuration needed:

Good for: Most web applications, simple scripts

File System Cache (Persist Between Requests)

Cache rules to disk for faster performance across multiple requests:

Good for: High-traffic sites, long-running processes, CLI applications

When to use:

• Production websites (cache between page loads)
• Background jobs (avoid repeated API calls)
• CLI tools (faster execution)

Cache Duration

Control how long rules are cached:

Recommendation: Start with 5-10 minutes in production. Increase once flags are stable.

Disable Cache (Testing Only)

Manually Refresh Rules

Force a fresh fetch from the API:

Logging & Debugging

Get visibility into what the SDK is doing by providing a PSR-3 logger:

What gets logged:

• API requests and responses
• Cache hits and misses
• Rule evaluation results
• Errors and exceptions

Example with Monolog:

Error Handling in Production

The SDK is designed for graceful degradation. Your app should never break because of feature flags.

Always Use Defaults for Critical Features

Handle API Failures

If the API is unreachable, the SDK will:

1. Use cached rules (if available)
2. Fall back to default values (if provided)
3. Throw exception (if no defaults)

Recommended pattern:

Retry Logic

The SDK automatically retries failed API calls (3 attempts with exponential backoff). You don't need to handle this.

Testing Your Feature Flags

Test your feature-flagged code without hitting the Zenmanage API.

Use Defaults in Tests

Mock the Flag Manager

Test Different Flag States

Requirements

• PHP 8.0 or higher
• Composer
• Guzzle HTTP client (automatically installed)

Installation

Development

Run tests:

Run static analysis:

License

MIT

Support

• Documentation: https://github.com/zenmanage/zenmanage-php
• Issues: https://github.com/zenmanage/zenmanage-php/issues
• Email: [email protected]