Gift Voucher Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

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

2. Configure the Bundle Add to config/bundles.php:

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

3. Publish Config & Assets

   php artisan vendor:publish --tag=gift-voucher-config
   php artisan vendor:publish --tag=gift-voucher-assets
   

4. Configure Stripe & Terms of Sale Update .env with Stripe keys and set the gift_voucher.terms_of_sale_url in config/gift_voucher.php.

5. First Use Case: Create a Voucher Request Form Use the provided Twig template (gift_voucher/request_form.html.twig) or extend it:

   {{ render(controller('C975LGiftVoucherBundle:GiftVoucher:requestForm')) }}
   

Implementation Patterns

Workflow: Voucher Creation & Redemption

1. Frontend Integration

   • Embed the request form in your checkout or dedicated page.
   • Use Select2 for recipient selection (optional but recommended):

     $('.gift-voucher-recipient').select2();
     

2. Backend Processing

   • Handle form submission via the bundle’s controller:

     use C975L\GiftVoucherBundle\Controller\GiftVoucherController;
     
     // In your routes:
     $router->mountPrefix('/gift-voucher', GiftVoucherController::class)
         ->add('request', 'request')
         ->add('redeem', 'redeem');
     

3. Payment Integration

   • Configure Stripe in config/payment.php and link it to the voucher:

     // Example: After form submission
     $voucher = $this->get('gift_voucher.manager')->createVoucher($data);
     $payment = $this->get('payment.manager')->createPayment($voucher->getId(), $amount);
     

4. Redemption Flow

   • Generate a QR code on-the-fly during redemption:

     $qrCode = $this->get('gift_voucher.manager')->generateQrCode($voucher->getSecretCode());
     $pdf = $this->get('gift_voucher.manager')->generatePdf($voucher);
     

5. Email Automation

   • Customize the email template (gift_voucher/email/voucher_email.html.twig) to include:
     • Voucher details (ID, expiry, value).
     • Attached PDF and QR code (auto-generated).
     • Terms of sale (embedded via URL).

Integration Tips

• Toolbar Integration Use c975LToolbarBundle to add voucher management to your admin panel:

  // In your toolbar config
  $toolbar->addItem('Gift Vouchers', 'gift_voucher_dashboard', 'fa-gift');
  

• Dynamic PDFs Extend the PDF generation by overriding the GiftVoucherPdfGenerator service:

  # config/services.yaml
  services:
      App\Service\CustomGiftVoucherPdfGenerator:
          decorates: 'gift_voucher.pdf_generator'
          arguments: ['@gift_voucher.pdf_generator.inner']
  

• Validation Logic Validate QR codes in your redemption controller:

  public function redeemAction(Request $request) {
      $secretCode = $request->get('secret_code');
      $isValid = $this->get('gift_voucher.manager')->validateVoucher($secretCode);
      if (!$isValid) {
          throw $this->createNotFoundException('Invalid voucher');
      }
  }
  

Gotchas and Tips

Pitfalls

1. Missing Stripe Configuration

   • Error: Stripe\Exception\InvalidRequestException if keys are misconfigured.
   • Fix: Double-check .env and config/payment.php for STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY.

2. Terms of Sale URL Unreachable

   • Error: PDF generation fails silently if the URL returns 404.
   • Fix: Use c975LSiteBundle to generate a PDF route or ensure your URL is publicly accessible.

3. QR Code Security

   • Risk: Secret codes may be exposed in logs or browser history.
   • Fix: Use HTTPS and sanitize logs. Avoid logging $voucher->getSecretCode().

4. PDF Generation Overhead

   • Issue: On-the-fly PDF generation can slow down redemption.
   • Fix: Cache the PDF template or pre-generate it during voucher creation.

Debugging

• Enable Debug Mode Set GIFT_VOUCHER_DEBUG: true in .env to log QR codes and secret codes (for testing only).

• Check Stripe Webhooks Ensure your Stripe webhook endpoint (configured in config/payment.php) is reachable:

  php artisan payment:webhook-test
  

Extension Points

1. Custom Voucher Fields Extend the GiftVoucher entity:

   // src/Entity/GiftVoucher.php
   use C975L\GiftVoucherBundle\Entity\GiftVoucher as BaseVoucher;
   
   class GiftVoucher extends BaseVoucher {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $customField;
   }
   

2. Override Email Templates Copy the default template to templates/gift_voucher/email/ and customize:

   {# templates/gift_voucher/email/custom_voucher_email.html.twig #}
   {% extends 'gift_voucher/email/voucher_email.html.twig' %}
   {% block subject %}Custom Voucher Subject{% endblock %}
   

3. Add Recipient Validation Hook into the gift_voucher.pre_redeem event:

   // src/EventListener/VoucherValidationListener.php
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   use C975L\GiftVoucherBundle\Event\PreRedeemEvent;
   
   class VoucherValidationListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'gift_voucher.pre_redeem' => 'validateRecipient',
           ];
       }
   
       public function validateRecipient(PreRedeemEvent $event) {
           $recipient = $event->getRecipient();
           if ($recipient->isBlacklisted()) {
               $event->stopPropagation();
           }
       }
   }
   

Config Quirks

• Secret Code Length Default is 4 letters (configurable via gift_voucher.secret_code_length). Increase for higher security (e.g., gift_voucher.secret_code_length: 6).

• Expiry Logic Vouchers expire after gift_voucher.expiry_days (default: 365). Set to 0 for no expiry.

• QR Code Size Adjust via gift_voucher.qr_code_size (default: 200). Larger sizes improve readability but increase file size.