Shizuku Feature Flags Laravel Package

Product Decisions This Supports

• Iterative Development & Agile Rollouts: Enables canary releases, A/B testing, and gradual feature rollouts without code branching or environment-specific logic. Flags can be toggled per user segment, environment, or percentage-based rollouts (via custom logic built on top of the boolean flags).
• Risk Mitigation: Provides kill switches for critical features (e.g., payments, auth) to disable functionality in production if bugs emerge, reducing blast radius.
• Dark Launching: Deploy features invisibly to production and enable them later via flags, allowing for post-deployment validation (e.g., monitoring, user feedback) before full release.
• Environment-Specific Configuration: Toggle features per environment (dev/staging/prod) without redeploying, supporting feature gating for specific stages (e.g., disable analytics in dev).
• Roadmap & Prioritization: Aligns with strategic roadmaps by enabling features to be "ready" but disabled until the optimal time (e.g., marketing campaigns, seasonal promotions).
• Build vs. Buy Decision: Avoids reinventing feature flag infrastructure, leveraging a battle-tested Symfony bundle with Doctrine ORM integration, reducing development time and maintenance overhead.
• Technical Debt Reduction: Enforces a structured flag lifecycle (lock/delete workflows) to prevent orphaned flags, ensuring code cleanup and reducing long-term tech debt.
• Non-Functional Requirements:
  • Performance: Caching (300s TTL) minimizes database queries, critical for high-traffic applications.
  • Observability: Profiler integration highlights locked/unknown flags, improving visibility into flag usage and deprecated code.
  • Security: Locked flags prevent accidental toggling in production, adding a layer of safety for critical features.
  • Developer Experience: CLI-driven workflow with interactive prompts and Twig integration streamlines flag management for both backend and frontend teams.

When to Consider This Package

Adopt if:

• Your application is built on Symfony 7.4+/8.0+ with Doctrine ORM 3.x (PHP 8.2+), ensuring seamless integration.
• You need database-backed feature flags (not just config files, environment variables, or in-memory solutions).
• Your team prioritizes a structured flag lifecycle (create → toggle → lock → delete) to enforce cleanup and reduce technical debt.
• You require Twig integration for dynamic frontend feature toggling (e.g., {% if feature('new_ui') %}).
• Your use case involves console-driven management (CLI commands for flag creation, enabling/disabling, and locking).
• You want caching optimization (300s TTL) to reduce database load and improve performance.
• Your application benefits from Profiler integration to track flag usage, locked flags, and unknown flags (e.g., deprecated flags still referenced in code).

Look Elsewhere if:

• You’re not using Symfony/Doctrine: Consider Laravel-native solutions like Spatie Laravel Feature Flags or third-party SaaS tools like LaunchDarkly or Flagsmith.
• You need multi-tenant flag isolation: This package lacks built-in tenant-aware scoping; you’d need to implement custom logic or use a dedicated solution.
• Your flags require complex targeting (e.g., user segments, percentage rollouts, or advanced conditions) beyond simple boolean toggles. Solutions like LaunchDarkly or Flagsmith offer richer targeting capabilities.
• You need real-time flag updates: The 300s cache TTL may not suit high-frequency changes (e.g., dynamic user-specific flags). Consider a solution with pub/sub or event-driven invalidation.
• Your team prefers UI-based management: This package is CLI-first; if your team relies on admin dashboards or visual tools, consider alternatives like Flagsmith or Unleash.
• You’re using Laravel: While theoretically adaptable, the package is Symfony-specific, requiring significant abstraction or refactoring to fit Laravel’s ecosystem (e.g., Eloquent, Blade, Artisan).

How to Pitch It (Stakeholders)

For Executives:

*"Shizuku Feature Flags is a strategic tool to accelerate feature delivery while minimizing risk. Here’s how it drives value:

• Faster, Safer Releases: Deploy features invisibly to production and enable them later via flags, reducing the risk of breaking changes. For example, we can roll out a new payment processor to 5% of users, monitor for issues, and scale up only if successful.
• Kill Switches for Critical Features: If a bug emerges in production (e.g., a payment failure or auth issue), we can disable the feature instantly without redeploying, limiting downtime and customer impact.
• Reduced Merge Conflicts: Avoid environment-specific code branches by toggling features per environment (dev/staging/prod) via flags, simplifying deployments and reducing technical debt.
• Data-Driven Decisions: Use flags for A/B testing or canary releases to measure feature performance before full rollout, ensuring we invest in what users actually want.
• Long-Term Cost Savings: The structured lifecycle (lock/delete) forces cleanup of deprecated flags, reducing technical debt and saving dev time on maintenance.

Upfront Effort: ~1 hour to set up; ROI: Fewer production incidents, faster iterations, and cleaner code. Let’s pilot this with 2–3 high-risk features (e.g., payments, auth) to validate the workflow before full adoption."*

For Engineering:

*"This is a lightweight, Doctrine-backed feature flag solution tailored for Symfony, with key advantages for our stack: Pros:

• CLI-First Workflow: Manage flags via intuitive console commands (e.g., shizuku:flag:create --name=my_feature --enable), with interactive prompts for quick setup.
• Twig Integration: Toggle frontend features dynamically using {% if feature('dark_mode') %}, enabling responsive UI changes without backend roundtrips.
• Profiler Visibility: The Symfony Profiler highlights locked flags (needing code cleanup) and unknown flags (e.g., deprecated flags still in code), improving observability.
• Caching Optimization: Built-in Symfony Cache support (TTL=300s) reduces DB queries; easy to override for custom cache pools (e.g., Redis).
• Structured Lifecycle: Flags auto-disable after locking, forcing cleanup before deletion—reducing tech debt over time.

Tradeoffs:

• Symfony-Specific: Not native to Laravel, so integration would require abstraction (e.g., facade layer for services, Eloquent for Doctrine ORM).
• No Advanced Targeting: Limited to boolean toggles; for user segments or percentage rollouts, we’d need to build custom logic or use a SaaS like LaunchDarkly.
• Cache Invalidation: Direct DB edits bypass cache invalidation; console commands trigger immediate cache updates.

Recommendation:

• Pilot with 2–3 features (e.g., a new UI component or payment flow) to validate the CLI/Twig workflow.
• Assess Laravel integration effort: If adoption is critical, evaluate the cost of adapting this bundle or building a custom Laravel package.
• Complement with SaaS: For complex targeting (e.g., user-based flags), pair this with LaunchDarkly or Flagsmith for enterprise features.

Next Steps:

1. Set up the bundle in a staging environment and test flag lifecycle (create → toggle → lock → delete).
2. Integrate with Twig for frontend toggles and validate Profiler visibility.
3. Benchmark performance with/without caching to confirm DB query reduction."*

For Developers:

*"Here’s how you’ll use Shizuku Feature Flags in your daily workflow: Getting Started:

1. Install via Composer:

   composer require devexploris/shizuku-feature-flags
   

2. Register the bundle in config/bundles.php and run migrations:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

Key Commands:

• Create a flag interactively:

  php bin/console shizuku:flag:create
  

  Or with options:

  php bin/console shizuku:flag:create --name=new_ui --description="Dark mode toggle" --enable
  

• Toggle flags:

  php bin/console shizuku:flag:enable --name=new_ui
  php bin/console shizuku:flag:disable --name=old_feature
  

• Lock a flag (prevents further toggling):

  php bin/console shizuku:flag:lock --name=deprecated_api
  

• List flags with filters:

  php bin/console shizuku:list Enabled
  

In Code: Inject FeatureFlagService and check flags:

use Devexploris\ShizukuFeatureFlags\Service\FeatureFlagService;

class MyController {
    public function __construct(private FeatureFlagService $flags) {}

    public function index() {
        if ($this->flags->isEnabled('new_ui')) {
            return $this->render('ui/new.html.twig');
        }
        return $this->