Features Bundle Laravel Package

Getting Started

• Install via Composer: composer require serendipity_hq/features-bundle. This is a Symfony bundle, not a Laravel package — if you're coming from Laravel, expect Symfony conventions (service container, Doctrine entities, bundles.php registration).
• Register the bundle in config/bundles.php (or AppKernel on older Symfony) and make sure doctrine/orm is installed and configured — the bundle ships Doctrine entities for features, plans, feature–plan links, and subscriptions.
• Publish/merge the bundle config, then point it at your customer entity. Your User (or Customer) class must implement the bundle's CustomerInterface; the bundle uses this to resolve which subscription/plan applies.
• Generate the schema: run bin/console doctrine:schema:update --dump-sql first to inspect what tables the bundle adds, then apply via migrations. Check the created tables (feature, plan, feature_plan, subscription, and any usage/counter tables) before writing app code.
• Where to look first: the bundle's FeaturesManager service (the primary API), the entity classes, and the README's configuration example. Search the service container for serendipity_hq.features_manager to confirm the ID.
• First use case: gate a premium feature. Define a Feature with a stable code (e.g. export_csv), attach it to a Plan, create a Subscription for a customer on that plan, then call the manager's customer-has-feature check in a controller before allowing the action.

if (!$featuresManager->customerHasFeature($user, 'export_csv')) {
    throw $this->createAccessDeniedException('Upgrade your plan.');
}

Implementation Patterns

• Feature codes are your contract. Treat the code string as a stable API identifier used throughout your code (controllers, voters, templates). Define features and plans via fixtures or a seeder command rather than hand-editing rows, so environments stay reproducible.
• Wrap checks in a Voter. Rather than sprinkling customerHasFeature() calls, create a FeatureVoter that maps attribute => feature code and call denyAccessUnlessGranted('FEATURE_export_csv', $user). This keeps authorization idiomatic and testable with Symfony's security test helpers.
• Twig extension for UI gating. Expose {% if can_use('export_csv') %} via a small Twig extension that delegates to the manager, so templates stay clean and you can hide upgrade prompts consistently.
• Consumable features use the usage/counter path. Boolean features are simple yes/no; consumable features (API calls, exports, seats) require the manager's consume/decrement method and typically a per-subscription-period counter. Always check and consume in one flow to avoid race conditions.
• Subscription lifecycle. Create a Subscription on signup/checkout, update its plan on upgrade/downgrade, and mark it inactive on cancellation. Drive expiry with a scheduled console command (cron) rather than computing everything on read, and make isActive() date-range checks timezone-aware.
• Plan-driven configuration. Keep plan → feature mapping in the DB (FeaturePlan rows) so pricing/marketing changes don't require deploys. Seed a free and pro plan in fixtures and attach features there.
• Testing strategy. Because the manager is a container service, inject the interface and mock it in unit tests; use Doctrine fixtures + a test DB for integration tests of subscription and consumption logic.

Gotchas and Tips

• Symfony-only. There is no Laravel service provider; you cannot drop this into a Laravel app without significant adaptation. If you're a Laravel dev, budget time for the framework mismatch or consider a Laravel-native equivalent (Cashier + feature flags).
• Your CustomerInterface implementation is mandatory. A common first-run failure is forgetting to configure the customer class or not implementing the interface — the manager will throw when resolving subscriptions. Verify the config key and the class FQCN carefully.
• Schema ownership. The bundle's entities live inside vendor/. Don't edit them; extend or override via config where supported, and always regenerate migrations after upgrading the bundle.
• Consumable counters reset per period. Verify the reset logic tied to subscription start/end dates — off-by-one or timezone drift can silently zero out or leak quota. Add tests around period boundaries.
• Caching feature checks. Feature lookups hit the DB on each call. For hot paths, cache per-request (or per-user with short TTL) and invalidate on plan change; never cache across a subscription change without a clear invalidation strategy.
• Low-maintenance risk. With ~11 stars and no dependents, pin the exact version in composer.json, review the changelog between upgrades, and consider forking if you hit a bug. Keep a thin adapter service around FeaturesManager so you can swap implementations later.
• Debugging tips. Use the Symfony profiler's Doctrine panel to inspect subscription/feature queries; dump the resolved subscription for a user with bin/console debug:container serendipity_hq.features_manager; and log every customerHasFeature/consume decision during rollout to catch mapping mistakes.
• Extension points. Custom feature types, Doctrine event subscribers on Subscription, and service overrides via services.yaml are the safest ways to add behavior without patching vendor code. Use a compiler pass or alias to decorate the manager if you need cross-cutting concerns (logging, caching, metrics).