Getting Started

Minimal Setup Steps

Install Dependencies

composer require c975l/giftvoucher-bundle
composer require c975l/payment-bundle stripe/stripe-php endroid/qr-code

Configure Bundle Add to config/bundles.php:

return [
    // ...
    C975L\GiftVoucherBundle\GiftVoucherBundle::class => ['all' => true],
    C975L\PaymentBundle\PaymentBundle::class => ['all' => true],
];

Stripe & Secret Key Setup Configure .env:

STRIPE_SECRET_KEY=your_stripe_key
GIFT_VOUCHER_SECRET_CODE_LENGTH=4  # Default: 4-letter code

Terms of Sale PDF Route Define a route (e.g., /terms-of-sale) returning a PDF (e.g., via c975LSiteBundle or custom controller).
First Use Case: Create a Voucher Form Use the provided Twig form (giftvoucher_form.html.twig) or extend it:
```
{{ render(controller('GiftVoucherBundle:GiftVoucher:form')) }}
```

Where to Look First

Bundle Docs: Check src/Resources/doc/ for usage examples.
Controllers: GiftVoucherController.php for core logic (e.g., createAction, redeemAction).
Entities: GiftVoucher.php and GiftVoucherTransaction.php for database structure.
Services: GiftVoucherManager for voucher generation/validation.

Implementation Patterns

Core Workflow: Voucher Creation

Form Submission Submit a form with recipient details (name, email) and amount.

// Example in a custom controller
$form = $this->createForm(GiftVoucherType::class);
if ($form->isSubmitted() && $form->isValid()) {
    $giftVoucher = $this->get('gift_voucher.manager')->create($form->getData());
}

Payment Processing Use c975LPaymentBundle to handle Stripe payment:

$payment = $this->get('payment.manager')->createPayment(
    $giftVoucher,
    $form->get('amount')->getData()
);
$payment->process(); // Redirects to Stripe checkout

Post-Payment Hook After successful payment, trigger voucher generation:
```
$this->get('gift_voucher.manager')->generateVoucher($giftVoucher);
```

Integration Tips

Customizing the Voucher PDF Override the Twig template (giftvoucher_pdf.html.twig) in your theme:

{# Extend base template #}
{% extends 'GiftVoucherBundle:GiftVoucher:pdf.html.twig' %}
{% block voucher_content %}
    {{ parent() }}
    {# Add custom content here #}
{% endblock %}

QR Code Customization Configure QR code settings in config/packages/gift_voucher.yaml:

gift_voucher:
    qr_code:
        size: 200
        error_correction: 'H'  # High error correction

Email Templates Extend the email template (giftvoucher_email.html.twig) to match your branding:

{% extends 'GiftVoucherBundle:GiftVoucher:email.html.twig' %}
{% block subject %}{{ 'Custom Subject'|trans }}{% endblock %}

Validation Logic Use the validateVoucher() method in your controller:

$isValid = $this->get('gift_voucher.manager')->validateVoucher(
    $qrCodeData['secret_code'],
    $qrCodeData['voucher_id']
);

Toolbar Integration Add a voucher management tab to c975LToolbarBundle:

// In a service or controller
$this->get('toolbar.manager')->addTab(
    'gift_vouchers',
    'fa-gift',
    route('gift_voucher_index')
);

Advanced Patterns

Batch Voucher Generation Use the GiftVoucherManager to generate vouchers programmatically:

$vouchers = [];
for ($i = 0; $i < 10; $i++) {
    $voucher = $this->get('gift_voucher.manager')->create([
        'recipient_name' => 'Customer ' . $i,
        'recipient_email' => 'customer@example.com',
        'amount' => 50.00,
    ]);
    $vouchers[] = $voucher;
}

Webhook Handling Handle Stripe webhooks to update voucher status:

// In a Stripe webhook controller
$event = \Stripe\Webhook::constructEvent(
    $payload,
    $sigHeader,
    'your_webhook_secret'
);
if ($event->type === 'payment_intent.succeeded') {
    $paymentIntent = $event->data->object;
    $this->get('gift_voucher.manager')->markAsPaid($paymentIntent->metadata->voucher_id);
}

Select2 Integration Enhance the form with Select2 for recipient selection:

// In your form initialization
$('.gift-voucher-recipient').select2({
    ajax: {
        url: route('gift_voucher_autocomplete'),
        dataType: 'json',
    }
});

Gotchas and Tips

Pitfalls

Missing SSL
- Issue: QR codes and PDFs are generated on-the-fly but require HTTPS for security.
- Fix: Ensure your site uses SSL (e.g., via Let’s Encrypt). Test locally with https://localhost.
Terms of Sale PDF Route
- Issue: The bundle expects a route for the Terms of Sale PDF. Without it, emails will fail.
- Fix: Use c975LSiteBundle or create a custom route:
```
# config/routes.yaml
terms_of_sale:
    path: /terms-of-sale
    controller: App\Controller\TermsController::pdf
```
Stripe Dependencies
- Issue: The bundle assumes Stripe is configured in c975LPaymentBundle.
- Fix: Verify STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY are set in .env.
Secret Code Length
- Issue: Default 4-letter code may be too short for security.
- Fix: Increase length in .env:
```
GIFT_VOUCHER_SECRET_CODE_LENGTH=6
```
QR Code Scanning
- Issue: Mobile users may struggle to scan QR codes if the PDF is too large.
- Fix: Optimize QR code size in config:
```
gift_voucher:
    qr_code:
        size: 150  # Smaller for mobile
```

Debugging Tips

Log Voucher Generation Enable debug mode and check logs for errors:

// In a controller
$this->get('gift_voucher.manager')->generateVoucher($giftVoucher, true); // Enable debug

Validate QR Codes Test QR code validation manually:

$result = $this->get('gift_voucher.manager')->validateVoucher('ABCD', $voucherId);
dump($result); // Should return voucher data or false

Check Email Delivery
- Use a local SMTP server (e.g., MailHog) to test emails:
```
MAILER_DSN=localhost
MAILER_FROM=no-reply@example.com
```
PDF Generation Issues
- Ensure dompdf or wkhtmltopdf is installed:
```
composer require dompdf/dompdf
```

Extension Points

Custom Voucher Types Extend the GiftVoucher entity to add fields (e.g., expiry_date):

// src/Entity/GiftVoucher.php
/**
 * @ORM\Column(type="datetime", nullable=true)
 */
private $expiryDate;

Override Voucher Manager Create a custom service to extend functionality:

# config/services.yaml
services:
    App\Service\CustomGiftVoucherManager:

Giftvoucher Bundle Laravel Package