Getting Started

Minimal Steps

Installation Add the bundle via Composer:

composer require dzangocart/subscription-bundle:dev-master

Dzangocart\SubscriptionBundle\DzangocartSubscriptionBundle::class => ['all' => true],

Load Fixtures Import essential fixtures (units, periods) for subscription management:
```
php bin/console doctrine:fixtures:load --fixtures=DzangocartSubscriptionBundle:Fixtures
```
(Note: Replace doctrine with propel if using Propel ORM as per the README.)

Declare Subscription Entities Annotate your product entity to mark it as subscription-capable:

use Dzangocart\SubscriptionBundle\Annotation\Subscription;

/**
 * @Subscription()
 */
class Product {}

First Use Case: Display a Pricing Page Use the bundle’s built-in Twig templates to render a pricing table:
```
{{ render(controller('DzangocartSubscriptionBundle:Plan:pricing')) }}
```

Implementation Patterns

Core Workflows

Defining Plans Create pricing plans via Doctrine entities (or Propel models) with annotations:
```
use Dzangocart\SubscriptionBundle\Entity\Plan;

class MyPlan extends Plan {
    // Customize plan properties (e.g., name, price, features)
}
```
Load plans via fixtures or manually via the admin interface (if implemented).

Linking to DzangoCart Integrate with DzangoCart’s API for payment processing:

$subscription = $this->get('dzangocart.subscription.manager')->createSubscription(
    $planId,
    $customerEmail,
    $dzangoCartCustomerId
);

Feature Management Attach features to plans (e.g., "Premium Support") using the Feature entity:

$plan->addFeature($featureEntity);
$entityManager->persist($plan);
$entityManager->flush();

Subscription Lifecycle
- Activation: Triggered via DzangoCart webhooks or manual calls.
- Cancellation: Use the bundle’s SubscriptionManager:
```
$this->get('dzangocart.subscription.manager')->cancelSubscription($subscriptionId);
```
- Renewal: Automate via cron jobs or DzangoCart’s renewal hooks.

Twig Integration Display subscription status or plans in templates:

{% for plan in plans %}
    <div class="plan">
        <h3>{{ plan.name }}</h3>
        <p>{{ plan.price }} {{ plan.period.unit }}</p>
        <a href="{{ path('dzangocart_subscription_subscribe', {'id': plan.id}) }}">Subscribe</a>
    </div>
{% endfor %}

Integration Tips

Symfony Forms: Use the bundle’s PlanType for plan selection forms.
Events: Listen to dzangocart.subscription.created or dzangocart.subscription.cancelled events for custom logic.
API: Expose subscription endpoints via FOSRestBundle or API Platform for headless setups.

Gotchas and Tips

Pitfalls

ORM Dependency
- The bundle assumes Doctrine ORM by default but mentions Propel in the README. Ensure your config/packages/doctrine.yaml is properly set up if using Doctrine.
- Fix: Override the bundle’s Resources/config/doctrine/ if using Propel or custom ORM.
Fixtures Overwrite
- Running propel:fixtures:load or doctrine:fixtures:load multiple times may duplicate data (e.g., units like "month").
- Tip: Use --append flag or clean fixtures before loading:
```
php bin/console doctrine:fixtures:load --append --fixtures=DzangocartSubscriptionBundle:Fixtures
```
DzangoCart API Credentials
- The bundle requires DzangoCart API keys for subscription management. Hardcoding credentials in config.yml is insecure.
- Tip: Use Symfony’s parameter_bag or environment variables:
```
# config/packages/dzangocart_subscription.yaml
dzangocart_subscription:
    api_key: '%env(DZANGO_CART_API_KEY)%'
```
Missing Configuration
- The README states "TODO" for configuration. Critical settings (e.g., currency, default period) may be missing.
- Workaround: Check DzangocartSubscriptionBundle/Resources/config/services.yaml for default parameters or extend the bundle’s configuration.
Twig Template Overrides
- The bundle’s templates (e.g., pricing.html.twig) are not documented for customization.
- Tip: Override templates in templates/bundles/dzangocartsubscription/:
```
mkdir -p templates/bundles/dzangocartsubscription
cp vendor/dzangocart/subscription-bundle/Resources/views/Plan/pricing.html.twig templates/bundles/dzangocartsubscription/
```

Debugging

Subscription Not Saving:
- Verify the @Subscription annotation is on the correct entity.
- Check if the SubscriptionManager service is properly bound in services.yaml:
```
Dzangocart\SubscriptionBundle\Manager\SubscriptionManager: ~
```
DzangoCart API Errors:
- Enable debug mode and check logs for API response errors. The bundle may not expose detailed error messages.
- Tip: Wrap API calls in a try-catch block for granular error handling.

Extension Points

Custom Plan Logic Extend the Plan entity or override the PlanType form to add custom fields (e.g., trial period):

class CustomPlanType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('trialDays', IntegerType::class);
    }
}

Webhook Handling Implement a custom subscriber for DzangoCart webhooks (e.g., subscription.activated):

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DzangoCartWebhookSubscriber implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            'dzangocart.subscription.activated' => 'onSubscriptionActivated',
        ];
    }

    public function onSubscriptionActivated(SubscriptionEvent $event) {
        // Custom logic (e.g., send welcome email)
    }
}

Multi-Currency Support Override the bundle’s PriceCalculator service to support dynamic currencies:

# config/services.yaml
Dzangocart\SubscriptionBundle\Calculator\PriceCalculator:
    arguments:
        $currencyService: '@app.custom_currency_service'

Subscription Bundle Laravel Package