Bundle Features Laravel Package

Getting Started

• Confirm the framework mismatch first. This is a Symfony bundle (serendipity_hq/bundle-features), not a Laravel package. If you are working in Laravel, stop here and evaluate Laravel Pennant, spatie/laravel-feature-flags, or a simple plans/quotas table instead. If you are in Symfony, continue.
• Check compatibility before installing. The package has ~11 stars, 0 dependents, and a modest score, so read composer.json for PHP, Symfony, and Doctrine ORM constraints. Install with composer require serendipity_hq/bundle-features, then register the bundle in config/bundles.php (Flex likely has no recipe).
• Configure the bundle. Look for the bundle's DependencyInjection/Configuration.php to find the exact root config key (likely serendipity_hq_features). Create the corresponding YAML file under config/packages/.
• Handle the schema manually. The bundle ships Doctrine entities (features, plans, plan-feature links, consumption records). Run bin/console doctrine:migrations:diff to generate a migration, or explicitly map the entities if the bundle does not auto-map them. Inspect src/Entity/ first.
• Look in this order: README.md, src/Entity/, the manager/service class (likely FeaturesManager or similar), src/Command/, and tests/. With a package this small, the tests are often better documentation than the README.
• First use case: gate a UI/API action by plan. Define a feature (boolean flag or consumable quota), define a plan, attach the feature to the plan with a quota, assign that plan to a user/account, and check it in a controller or service. Keep this first integration behind one wrapper service so you can replace the bundle later if needed.

Implementation Patterns

• Wrap the bundle behind your own service. Create an application-level FeatureGate/PlanService that delegates to the bundle's manager. This isolates your domain from a low-adoption dependency and makes swapping implementations feasible.
• Check features at clear boundaries. Do plan/feature checks in controllers, security voters, or a kernel listener rather than deep inside domain entities. This keeps business logic testable and avoids coupling entities to the bundle.
• Use voters for access control. For Symfony security integration, implement a voter that asks the wrapper whether the current user's plan includes a feature. This combines cleanly with is_granted() in controllers and Twig.
• Treat consumables as transactional. For quota features (e.g. SMS credits, API calls), perform check-and-consume inside a single transaction. Assume the bundle does not guarantee atomic decrement under concurrency and add database-level safeguards or pessimistic locking where it matters.
• Manage plan transitions explicitly. When a user upgrades, downgrades, or cancels, update the assigned plan and invalidate any cached feature resolution. Do not let stale plan data leak across requests.
• Seed features/plans as code. Prefer fixtures or a custom console command to create features and plans reproducibly. Avoid hand-editing production rows; use the bundle's commands if they exist, otherwise write a small seeder around the manager.
• Cache resolved features per request. Feature resolution likely hits the database. Add a request-scoped cache in your wrapper, and a Symfony cache pool if needed, with explicit invalidation on plan changes.
• Test with in-memory SQLite and fixtures. Build integration tests that create plans/features and assert gate behavior. For unit tests, fake your wrapper service rather than the bundle internals.

Gotchas and Tips

• No Laravel path. There is no Laravel service provider, facade, or config publishing here. A Laravel team should not adopt this package; use native Laravel tooling instead.
• Low adoption risk. With 11 stars, 0 dependents, and a single-maintainer profile, pin an exact version in composer.json and be prepared to fork. Budget maintenance time and avoid depending on undocumented internals.
• Verify the DI alias yourself. Documentation may be stale or sparse. Use bin/console debug:container | grep -i feature and debug:config to discover actual service IDs and configuration keys.
• Doctrine ownership is ambiguous. Confirm whether the bundle auto-registers entity mappings or expects you to import them. Migration ownership matters; if the bundle updates its entities, your generated migrations can drift.
• Quota consumption can race. Check-then-decrement is a classic race condition. Wrap it in a transaction, add unique constraints or row locks, and test concurrent consumption explicitly.
• Caching staleness is the most likely production bug. After a plan change, ensure cached feature checks are cleared. Prefer conservative TTLs and per-request caching over long-lived caches.
• Debug with the standard Symfony stack. Enable Doctrine SQL logging to confirm feature lookups, use the profiler to inspect queries per request, and check the bundle's commands for state inspection.
• Extend by decoration, not forking. If the bundle exposes consumption strategies or events, prefer a custom strategy or event subscriber. Otherwise decorate the manager service. Fork only if the package is abandoned or a required fix is unmergeable.
• Evaluate alternatives before committing. For simple flag toggles, a small custom table plus a Symfony cache is often cheaper than adopting a low-adoption bundle. Use this package only if you genuinely need its plans/features/consumption model.