### Creating a Gift Voucher (Admin - GET Request)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Demonstrates the initial GET request to the create endpoint, which displays the form for creating a new gift voucher.

```http
GET /gift-voucher/create
```

--------------------------------

### Example Configuration YAML

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

This YAML snippet shows a complete example of the minimum required configuration for the Gift Voucher Bundle in a Symfony project. It includes settings for terms of service PDF, live mode, VAT, default and proposed currencies, required roles, and GDPR compliance.

```yaml
# config/packages/c975l_gift_voucher.yaml

# Minimum required configuration
c975l_gift_voucher:
    tosPdf: https://mysite.com/pdf/terms-of-sales.pdf
    live: true
    vat: 0.20
    defaultCurrency: EUR
    proposedCurrencies:
      - EUR
      - USD
    roleNeeded: ROLE_ADMIN
    gdpr: true
```

--------------------------------

### Install GiftVoucherBundle with Composer

Source: https://github.com/975l/giftvoucherbundle/blob/master/README.md

Use Composer to install the GiftVoucherBundle. This command is for v3.x which works with Symfony 4.x. Use v2.x for Symfony 3.x.

```bash
composer require c975l/giftvoucher-bundle
```

--------------------------------

### GiftVoucherPurchasedType Options Example

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/forms.md

Example of how to configure the GiftVoucherPurchasedType with options, specifically to enable the GDPR consent checkbox.

```php
$options = [
    'config' => [
        'gdpr' => true  // whether to show GDPR checkbox
    ]
];
```

--------------------------------

### Public Offer Page (No Access Control)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/security.md

An example of a public-facing offer page that does not require specific user permissions.

```php
// Anyone can view offer page
public function offer(GiftVoucherAvailable $voucher) {
    // No denyAccessUnlessGranted() - public access
    return $this->render('offer.html.twig');
}
```

--------------------------------

### GET /gift-voucher/help

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Retrieves HTML help page for gift voucher functionality. Requires specific authorization role.

```APIDOC
## GET /gift-voucher/help

### Description
Retrieves an HTML help page detailing gift voucher functionalities. This endpoint requires the `c975LGiftVoucher-help` role for authorization.

### Method
GET

### Endpoint
/gift-voucher/help

### Authorization
Requires `c975LGiftVoucher-help` role
```

--------------------------------

### Create and Configure Purchased Voucher

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Example demonstrating how to create a purchased voucher from an available one, set its details, and then register it for processing. This involves fetching an available voucher, creating a purchased instance, setting sender, recipient, message, and email, and finally registering the purchase.

```php
// Create a purchased voucher from an available voucher
$available = $giftVoucherAvailableService->getAll()[0];
$purchased = $giftVoucherPurchasedService->create($available);

$purchased
    ->setOfferedBy('Alice')
    ->setOfferedTo('Bob')
    ->setMessage('Happy Birthday!')
    ->setSendToEmail('bob@example.com');

// Register and process payment
$giftVoucherPurchasedService->register($purchased, true);
```

--------------------------------

### Purchasing a Gift Voucher (Customer - GET Request)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Illustrates the GET request to the offer page, which displays the form for purchasing a gift voucher, pre-filled with relevant details.

```http
GET /gift-voucher/offer/premium-weekend-package/5
```

--------------------------------

### Accessing Configuration Parameters in Services

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

This PHP code illustrates how to inject and use the `ConfigServiceInterface` in your services to retrieve configuration parameters. It shows how to get parameters like 'live' status and 'tosPdf' URL, and how to specify a bundle context for parameter retrieval.

```php
use c975L\ConfigBundle\Service\ConfigServiceInterface;

class MyService {
    public function __construct(ConfigServiceInterface $configService) {
        $this->configService = $configService;
    }
    
    public function doSomething() {
        $isLive = $this->configService->getParameter('c975LGiftVoucher.live');
        $tosUrl = $this->configService->getParameter('c975LGiftVoucher.tosPdf');
        $roleNeeded = $this->configService->getParameter('c975LGiftVoucher.roleNeeded', 'c975l/giftvoucher-bundle');
        
        if ($isLive) {
            // Live mode logic
        }
    }
}
```

--------------------------------

### GET /gift-voucher/use/{identifier}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Provides an interface to confirm the usage of a gift voucher. Requires specific authorization.

```APIDOC
## GET /gift-voucher/use/{identifier}

### Description
This endpoint displays an HTML page with a confirmation button to mark a gift voucher as used. It requires specific authorization to ensure only permitted users can initiate the voucher's utilization.

### Method
GET

### Endpoint
/gift-voucher/use/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - 16-character identifier

### Authorization
Requires `c975LGiftVoucher-utilisation` with entity

### Response
HTML page with "Use" confirmation button

### Exceptions
- 404 NotFoundHttpException: Identifier not found
- 403 AccessDeniedException: User lacks utilisation permission
```

--------------------------------

### GET|POST /gift-voucher/config

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Manages gift voucher configuration settings. A GET request displays the configuration form, and a POST request submits the updated settings.

```APIDOC
## GET|POST /gift-voucher/config

### Description
Manages gift voucher configuration settings. A GET request displays the configuration form, and a POST request submits the updated settings.

### Method
GET, POST

### Endpoint
/gift-voucher/config

### Parameters
#### POST Parameters
Configuration fields managed by ConfigBundle

### Response
#### Success Response (200)
- GET: HTML configuration form
- POST success: Redirect to `/gift-voucher/dashboard`

### Configuration Parameters
- c975LGiftVoucher.tosPdf: URL to terms of sales PDF
- c975LGiftVoucher.live: Live mode enabled
- c975LGiftVoucher.vat: VAT rate
- c975LGiftVoucher.gdpr: GDPR checkbox enabled
- c975LGiftVoucher.defaultCurrency: Default currency code
- c975LGiftVoucher.proposedCurrencies: Array of currency codes
- c975LGiftVoucher.roleNeeded: Admin role for access
```

--------------------------------

### GET|POST /gift-voucher/create

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Handles the creation of new gift vouchers. A GET request displays the creation form, while a POST request submits the form data to create the voucher.

```APIDOC
## GET|POST /gift-voucher/create

### Description
Handles the creation of new gift vouchers. A GET request displays the creation form, while a POST request submits the form data to create the voucher.

### Method
GET, POST

### Endpoint
/gift-voucher/create

### Parameters
#### POST Parameters
Form data (see GiftVoucherAvailableType fields)

### Response
#### Success Response (200)
- GET: HTML form
- POST success: Redirect to `/gift-voucher/display/{id}`
- POST invalid: Re-display form with errors

### Request Example
```bash
GET /gift-voucher/create
POST /gift-voucher/create
  object=Premium Weekend Package
  slug=premium-weekend-package
  description=Includes hotel stay and meals
  valid[years]=1
  amount=5000
  currency=EUR
```
```

--------------------------------

### GET|POST /gift-voucher/offer/{slug}/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Displays the gift voucher purchase form (GET) or processes the purchase submission (POST). Publicly accessible.

```APIDOC
## GET|POST /gift-voucher/offer/{slug}/{id}

### Description
This endpoint allows users to view the gift voucher purchase form via a GET request or submit the form via a POST request. It performs URL validation against the provided slug and ID. Publicly accessible.

### Method
GET, POST

### Endpoint
/gift-voucher/offer/{slug}/{id}

### Parameters
#### Path Parameters
- **slug** (string) - Required - Semantic URL slug (validates against stored slug)
- **id** (int) - Required - Voucher ID

#### Request Body (for POST)
- **offeredTo** (string) - Yes - Recipient name
- **offeredBy** (string) - Yes - Offerer name
- **message** (string) - Yes - Personal message
- **sendToEmail** (string) - Yes - Recipient email
- **gdpr** (bool) - Conditional - GDPR consent if enabled

### Response
- GET: HTML purchase form
- POST success: Redirect to `/payment/form` (PaymentBundle)
- POST invalid: Re-display form with validation errors

### URL Validation
If slug doesn't match stored slug, redirects to correct URL for SEO purposes.

### Exceptions
- 404 NotFoundHttpException: Voucher not found
```

--------------------------------

### Doctrine Type Mapping Examples

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/types.md

Illustrates the mapping of various database column types to Doctrine entity types. This includes primary keys, booleans, strings with length constraints, text fields, date intervals, datetimes, integers, and specific identifiers.

```php
id                  → integer (auto_increment, primary key)
suppressed          → boolean
object              → string(128)
slug                → string(128)
description         → text(65000)
valid (available)   → dateinterval
valid (purchased)   → datetime
amount              → integer
currency            → string(3)
identifier          → string(12)
secret              → string(4)
offeredBy           → string(128)
offeredTo           → string(128)
message             → text(65000)
sendToEmail         → string(128)
purchase            → datetime
orderId             → string(48)
used                → datetime
userIp              → string(48)
```

--------------------------------

### GET /gift-voucher/{identifier}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Displays the purchased gift voucher details. Publicly accessible with a valid identifier.

```APIDOC
## GET /gift-voucher/{identifier}

### Description
Displays the details of a purchased gift voucher using its unique identifier. The display mode varies based on user privileges (admin vs. basic public access). Publicly accessible if a valid identifier is provided.

### Method
GET

### Endpoint
/gift-voucher/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - 16-character identifier (12 public + 4 secret), uppercase letters only

### Response
HTML page displaying the gift voucher

### Display Modes
- Admin (with `c975LGiftVoucher.roleNeeded`): Shows "Use" button and full details
- Basic (public): Shows voucher info only

### ParamConverter
Resolves `GiftVoucherPurchased` via `findOneBasedOnIdentifier(identifier)`

### Exceptions
- 404 NotFoundHttpException: Identifier not found (invalid or not yet purchased)

### Example
```
GET /gift-voucher/ABCDEFGHIJKLTMNP
```
```

--------------------------------

### GET /gift-voucher/display/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Displays the details of a specific gift voucher identified by its ID. Requires appropriate permissions.

```APIDOC
## GET /gift-voucher/display/{id}

### Description
Displays the details of a specific gift voucher identified by its ID. Requires appropriate permissions.

### Method
GET

### Endpoint
/gift-voucher/display/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Gift voucher ID

### Response
#### Success Response (200)
HTML page displaying the gift voucher details

### Exceptions
- 404 NotFoundHttpException: Voucher not found
- 403 AccessDeniedException: User lacks display permission

### Request Example
```
GET /gift-voucher/display/5
```
```

--------------------------------

### Accessing Configuration Web Interface

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

The configuration form can be accessed via a GET request to the specified URL. Users require a specific role to access it. POST requests to the same URL save changes, and success redirects to the dashboard.

```http
GET /gift-voucher/config
```

--------------------------------

### Payment Action Field Example

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Illustrates the structure of the 'Payment action' field used for integrating with Stripe, specifically for validating a gift voucher.

```json
{
    "validateGiftVoucher": 5  // GiftVoucherPurchased ID
}
```

--------------------------------

### GET /gift-voucher/payment-done/{orderId}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Callback endpoint for payment completion. Handles success or failure redirects and initiates post-payment side effects.

```APIDOC
## GET /gift-voucher/payment-done/{orderId}

### Description
This endpoint acts as a callback from the PaymentBundle to handle the completion of a gift voucher payment. It redirects the user based on payment success or failure and triggers several side effects, including email notifications and payment status updates.

### Method
GET

### Endpoint
/gift-voucher/payment-done/{orderId}

### Parameters
#### Path Parameters
- **orderId** (string) - Required - Payment order identifier

### Response
- Success: Redirect to `/gift-voucher/{full_identifier}`
- Failure: Redirect to `/payment/display/{orderId}` with error

### Side Effects
- Generates unique identifier and secret code
- Sends email with PDF and terms of sales
- Creates flash message
- Marks payment as finished

### ParamConverter
Resolves `Payment` entity from orderId
```

--------------------------------

### Override GiftVoucherBundle Layout Template

Source: https://github.com/975l/giftvoucherbundle/blob/master/README.md

Create a custom layout file to integrate the bundle with your site's design. This example shows how to extend your base layout and define content blocks.

```twig
{% extends 'layout.html.twig' %}

{% block content %}
    {% block giftVoucher_content %}
    {% endblock %}
{% endblock %}
```

--------------------------------

### Gift Voucher Twig Template Functions

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Provides examples of using Twig functions to render offer buttons, links, display all vouchers, format identifiers, and create select dropdowns.

```twig
{# Render offer button #}
{{ gv_offer_button(voucher.id) }}

{# Render offer link #}
{{ gv_offer_link(voucher.id) }}

{# Display all vouchers #}
{{ gv_view_all() }}
{{ gv_view_all(5, 'amount') }}

{# Format identifier #}
{{ purchased.identifier | gv_identifier }}

{# Render select dropdown #}
{{ gv_select() }}
{{ gv_select(preselectedId) }}
```

--------------------------------

### GET|POST /gift-voucher/duplicate/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Duplicates an existing gift voucher. A GET request shows a form with original data, and a POST request creates a new voucher based on the provided data.

```APIDOC
## GET|POST /gift-voucher/duplicate/{id}

### Description
Duplicates an existing gift voucher. A GET request shows a form with original data, and a POST request creates a new voucher based on the provided data.

### Method
GET, POST

### Endpoint
/gift-voucher/duplicate/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Voucher ID to duplicate
#### POST Parameters
Form data (object and slug should be new values)

### Response
#### Success Response (200)
- GET: HTML form with values from original, cleared object/slug
- POST success: Redirect to `/gift-voucher/display/{new_id}`
- POST invalid: Re-display form with errors

### Side Effects
Creates new database record, leaves original intact
```

--------------------------------

### GET|POST /gift-voucher/modify/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Allows modification of an existing gift voucher. A GET request displays the pre-filled form for editing, and a POST request submits the changes.

```APIDOC
## GET|POST /gift-voucher/modify/{id}

### Description
Allows modification of an existing gift voucher. A GET request displays the pre-filled form for editing, and a POST request submits the changes.

### Method
GET, POST

### Endpoint
/gift-voucher/modify/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Voucher ID to modify
#### POST Parameters
Form data with changes

### Response
#### Success Response (200)
- GET: HTML form pre-filled with current data
- POST success: Redirect to `/gift-voucher/display/{id}`
- POST invalid: Re-display form with errors

### Exceptions
- 404 NotFoundHttpException: Voucher not found
- 403 AccessDeniedException: User lacks modify permission
```

--------------------------------

### GET|POST /gift-voucher/delete/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Handles the deletion of a gift voucher. A GET request displays a confirmation form, and a POST request confirms and performs the deletion (soft delete).

```APIDOC
## GET|POST /gift-voucher/delete/{id}

### Description
Handles the deletion of a gift voucher. A GET request displays a confirmation form, and a POST request confirms and performs the deletion (soft delete).

### Method
GET, POST

### Endpoint
/gift-voucher/delete/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Voucher ID to delete

### Response
#### Success Response (200)
- GET: HTML confirmation form (fields read-only)
- POST success: Redirect to `/gift-voucher/dashboard`
- POST invalid: Re-display form with errors

### Side Effects
Marks voucher as suppressed (soft delete)
```

--------------------------------

### create

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Creates a new purchased voucher instance from an available template. Copies properties and captures client IP.

```APIDOC
## create

### Description
Creates a new purchased voucher instance from an available template. Copies properties and captures client IP.

### Method
[Method signature: create(GiftVoucherAvailable $giftVoucherAvailable): GiftVoucherPurchased]

### Parameters
#### Path Parameters
- **$giftVoucherAvailable** (GiftVoucherAvailable) - Required - The template to create from

### Response
#### Success Response
- Returns: New `GiftVoucherPurchased` instance (not yet persisted)

### Example
```php
$available = $service->getAll()[0];
$purchased = $service->create($available);
// purchased.object, amount, currency, valid, userIp are set
```
```

--------------------------------

### Environment Variables for Configuration

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

This section shows how to set configuration parameters using environment variables. These variables can then be referenced in the main configuration YAML file, allowing for flexible environment-specific settings.

```bash
export C975L_GIFT_VOUCHER_LIVE=true
export C975L_GIFT_VOUCHER_VAT=0.20
export C975L_GIFT_VOUCHER_DEFAULT_CURRENCY=USD
export C975L_GIFT_VOUCHER_ROLE_NEEDED=ROLE_GIFT_VOUCHER_ADMIN
export C975L_GIFT_VOUCHER_GDPR=1
export C975L_GIFT_VOUCHER_TOS_PDF=https://mysite.com/terms.pdf
```

```yaml
# config/packages/c975l_gift_voucher.yaml
c975l_gift_voucher:
    tosPdf: '%env(C975L_GIFT_VOUCHER_TOS_PDF)%'
    live: '%env(bool:C975L_GIFT_VOUCHER_LIVE)%'
    vat: '%env(float:C975L_GIFT_VOUCHER_VAT)%'
    defaultCurrency: '%env(C975L_GIFT_VOUCHER_DEFAULT_CURRENCY)%'
    roleNeeded: '%env(C975L_GIFT_VOUCHER_ROLE_NEEDED)%'
    gdpr: '%env(bool:C975L_GIFT_VOUCHER_GDPR)%'
```

--------------------------------

### Doctrine Configuration

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Sets up the database connection and ORM mapping for Doctrine.

```yaml
doctrine:
    dbal:
        driver: pdo_mysql
        host: '%env(DATABASE_HOST)%'
        dbname: '%env(DATABASE_NAME)%'
        user: '%env(DATABASE_USER)%'
        password: '%env(DATABASE_PASSWORD)%'
    orm:
        auto_generate_proxy_classes: '%kernel.debug%'
        mapping:
            c975LGiftVoucherBundle:
                type: annotation
```

--------------------------------

### Get All Gift Vouchers

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Retrieves all gift vouchers that have not been suppressed. Returns an array of GiftVoucherAvailable entities.

```php
$vouchers = $service->getAll();
foreach ($vouchers as $voucher) {
    echo $voucher->getObject();
}
```

--------------------------------

### Creating a Gift Voucher (Admin - POST Request)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Shows the POST request with sample data used to create a new gift voucher, including details like object name, validity, and amount.

```http
POST /gift-voucher/create with data:
   - object: "Premium Weekend Package"
   - slug: "premium-weekend-package"
   - description: "Includes hotel and meals"
   - valid: P1Y (1 year validity)
   - amount: 50000 (€500)
   - currency: EUR
```

--------------------------------

### GET /gift-voucher/offer/{id}

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Redirects to a specific gift voucher offer page using its ID. Publicly accessible.

```APIDOC
## GET /gift-voucher/offer/{id}

### Description
Retrieves a specific gift voucher offer by its ID and redirects to its detailed page, which includes a slug for SEO. This endpoint is publicly accessible.

### Method
GET

### Endpoint
/gift-voucher/offer/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Voucher ID (numeric)

### Response
Redirects to `/gift-voucher/offer/{slug}/{id}`

### Example
```
GET /gift-voucher/offer/5
→ Redirect to /gift-voucher/offer/premium-weekend-package/5
```
```

--------------------------------

### Configure Proposed Currencies (All)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Leave the proposed currencies array empty or omit it to allow all ISO 4217 currencies to be available for gift voucher purchases.

```yaml
# All currencies available (empty or omitted)
c975LGiftVoucher.proposedCurrencies: []
```

--------------------------------

### Using Gift Voucher Repositories

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Shows how to retrieve available and purchased gift vouchers using Doctrine repositories within the bundle.

```php
$em = $this->getDoctrine();

// Available vouchers
$available = $em->getRepository('c975LGiftVoucherBundle:GiftVoucherAvailable')
    ->findNotSuppressed();

// Purchased vouchers
$purchased = $em->getRepository('c975LGiftVoucherBundle:GiftVoucherPurchased')
    ->findOneBasedOnIdentifier('ABCDEFGHIJKLMNOP');
```

--------------------------------

### Configure GDPR Consent Form Field

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Example of how to conditionally add a GDPR consent checkbox to a Symfony form based on configuration.

```php
// In GiftVoucherPurchasedType
if ($options['config']['gdpr']) {
    $builder->add('gdpr', CheckboxType::class, [
        'label' => 'text.gdpr',
        'required' => true,
        'mapped' => false,
    ]);
}
```

--------------------------------

### Enable GiftVoucherBundle Routes

Source: https://github.com/975l/giftvoucherbundle/blob/master/README.md

Add these lines to your project's /config/routes.yaml file to enable the bundle's routes.

```yaml
c975_l_giftvoucher:
    resource: "@c975LGiftVoucherBundle/Controller/"
    type: annotation
    prefix: /
    #Multilingual website use the following
    #prefix: /{_locale}
    #defaults:   { _locale: '%locale%' }
    #requirements:
    #    _locale: en|fr|es
```

--------------------------------

### KnpPaginator Configuration

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Configures default pagination settings for KnpPaginator.

```yaml
knp_paginator:
    page_range: 5
    default_pagination: 15
```

--------------------------------

### Get Gift Voucher Dashboard

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Retrieves a paginated HTML page of gift vouchers, either 'available' or 'purchased'. Supports pagination.

```http
GET /gift-voucher/dashboard?v=available&p=1
GET /gift-voucher/dashboard?v=purchased&p=2
```

--------------------------------

### Create GiftVoucherPurchased Instance

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Creates a new purchased voucher from an available template, copying properties and capturing the client's IP address. This method returns a new GiftVoucherPurchased instance that is not yet persisted.

```php
$available = $service->getAll()[0];
$purchased = $service->create($available);
// purchased.object, amount, currency, valid, userIp are set
```

--------------------------------

### Troubleshooting Access Denied Errors

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/security.md

Provides debugging steps for 'AccessDeniedException', including checking roles, attributes, and configuration.

```php
// In controller
$user = $this->getUser();
$authChecker = $this->container->get('security.authorization_checker');

// Debug: Check if user has role
$hasRole = $authChecker->isGranted('ROLE_ADMIN');

// Debug: Try to grant attribute
try {
    $this->denyAccessUnlessGranted('c975LGiftVoucher-dashboard', null);
    // If we get here, access granted
} catch (AccessDeniedException $e) {
    // Access denied - check configuration
    $roleNeeded = $configService->getParameter('c975LGiftVoucher.roleNeeded');
}
```

--------------------------------

### Get Gift Voucher ID

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Retrieves the unique identifier for a gift voucher available template. This is useful for referencing specific voucher definitions.

```php
$voucher = $giftVoucherAvailableService->getAll()[0];
$id = $voucher->getId();
```

--------------------------------

### Database Table Creation SQL

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

This SQL script defines the necessary table structures for the Gift Voucher Bundle: `gift_voucher_available` and `gift_voucher_purchased`. These tables store information about available gift vouchers and purchased/used vouchers, respectively.

```sql
-- Using resources/sql/gift-voucher.sql
CREATE TABLE IF NOT EXISTS `gift_voucher_available` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `suppressed` tinyint(1) NOT NULL,
  `object` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `slug` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `description` longtext COLLATE utf8mb4_unicode_ci,
  `valid` varchar(12) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `amount` int(11) DEFAULT NULL,
  `currency` varchar(3) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `object` (`object`),
  KEY `slug` (`slug`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE IF NOT EXISTS `gift_voucher_purchased` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `identifier` varchar(12) COLLATE utf8mb4_unicode_ci NOT NULL,
  `secret` varchar(4) COLLATE utf8mb4_unicode_ci NOT NULL,
  `object` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `description` longtext COLLATE utf8mb4_unicode_ci,
  `offered_by` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `offered_to` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `message` longtext COLLATE utf8mb4_unicode_ci,
  `send_to_email` varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `purchase` datetime DEFAULT NULL,
  `valid` datetime DEFAULT NULL,
  `amount` int(11) DEFAULT NULL,
  `currency` varchar(3) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `order_id` varchar(48) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `used` datetime DEFAULT NULL,
  `user_ip` varchar(48) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `identifier_secret` (`identifier`, `secret`),
  KEY `used` (`used`),
  KEY `identifier` (`identifier`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

--------------------------------

### PHP Controller for Configuration

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

This PHP code demonstrates a controller action for handling the gift voucher configuration form. It ensures the user has the necessary role, creates the form, handles submission and validation, saves the configuration, and renders the form view.

```php
// In AvailableController
public function config(Request $request, ConfigServiceInterface $configService) {
    $this->denyAccessUnlessGranted('c975LGiftVoucher-config', null);
    
    $form = $configService->createForm('c975l/giftvoucher-bundle');
    $form->handleRequest($request);
    
    if ($form->isSubmitted() && $form->isValid()) {
        $configService->setConfig($form);
        return $this->redirectToRoute('giftvoucher_dashboard');
    }
    
    return $this->render('@c975LConfig/forms/config.html.twig', [
        'form' => $form->createView(),
        'toolbar' => '@c975LGiftVoucher',
    ]);
}
```

--------------------------------

### GET /gift-voucher/dashboard

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Retrieves the gift voucher dashboard, which displays a paginated list of gift vouchers. Supports filtering by view mode ('available' or 'purchased') and pagination.

```APIDOC
## GET /gift-voucher/dashboard

### Description
Retrieves the gift voucher dashboard, which displays a paginated list of gift vouchers. Supports filtering by view mode ('available' or 'purchased') and pagination.

### Method
GET

### Endpoint
/gift-voucher/dashboard

### Parameters
#### Query Parameters
- **v** (string) - Optional - View mode: 'available' or 'purchased'
- **p** (int) - Optional - Page number for pagination

### Response
#### Success Response (200)
HTML page with table of gift vouchers (paginated, 15 per page)

### Request Example
```
GET /gift-voucher/dashboard?v=available&p=1
GET /gift-voucher/dashboard?v=purchased&p=2
```
```

--------------------------------

### Enable Live Mode

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Controls whether the gift voucher system operates in live payment mode or test mode. In test mode, a (TEST) prefix is added to the voucher object name.

```yaml
c975LGiftVoucher.live: true
```

--------------------------------

### Get Purchased Gift Voucher ID

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Retrieves the unique identifier for a specific purchased gift voucher instance. This is useful for looking up individual voucher redemptions.

```php
$purchased = $repository->findOneById(1);
$id = $purchased->getId();
```

--------------------------------

### Set Valid Expiration Date

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Sets the expiration datetime for the voucher. The example shows how to set it to one year from the current date. Returns the object for method chaining.

```php
 $valid = new DateTime();
 $valid->add(new DateInterval('P1Y'));
 $purchased->setValid($valid);
```

--------------------------------

### Configure Proposed Currencies (Multiple)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Define a list of allowed currencies for gift voucher purchases. This will present a dropdown selection to the user.

```yaml
# Multiple currencies (dropdown selection)
c975LGiftVoucher.proposedCurrencies:
  - EUR
  - USD
  - GBP
```

--------------------------------

### Display All Gift Vouchers View

Source: https://github.com/975l/giftvoucherbundle/blob/master/README.md

Use `gv_view_all()` to create a view of available gift vouchers. You can specify the number of vouchers to display and the ordering field.

```twig
{{ gv_view_all() }}
```

```twig
{{ gv_view_all(NUMBER_OF_GIFTVOUCHERS_TO_DISPLAY) }}
```

```twig
{{ gv_view_all(NUMBER_OF_GIFTVOUCHERS_TO_DISPLAY, ORDERED_FIELD) }}
```

--------------------------------

### Custom QueryBuilder Usage with Repositories

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/repositories.md

Shows how to extend the QueryBuilder from repository methods to apply custom filters and retrieve specific results, such as counting unused vouchers or filtering by currency.

```php
$qb = $repository->findAll()
    ->andWhere('v.currency = :currency')
    ->setParameter('currency', 'EUR')
    ->getQuery()
    ->getResult();

$countUnused = $repository->findAll()
    ->select('COUNT(v.id)')
    ->getQuery()
    ->getSingleScalarResult();
```

--------------------------------

### Get Specific Gift Voucher Offer

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Redirects to a specific gift voucher's offer page using its numeric ID. The redirect includes a slug for SEO purposes.

```http
GET /gift-voucher/offer/5
→ Redirect to /gift-voucher/offer/premium-weekend-package/5
```

--------------------------------

### getDescription

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Retrieves the description of the voucher.

```APIDOC
## getDescription(): ?string

### Description
Returns the description.

### Method
GET

### Endpoint
/purchased/{identifier}
```

--------------------------------

### Retrieve User IP Address

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/security.md

Shows how to access the IP address associated with a gift voucher purchase for fraud detection.

```php
$purchased->getUserIp();  # e.g., "192.168.1.1"
```

--------------------------------

### Display or Purchase Gift Voucher

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Allows displaying the purchase form for a specific gift voucher via GET or submitting a purchase via POST. Requires slug and ID for identification.

```http
GET|POST /gift-voucher/offer/{slug}/{id}
```

--------------------------------

### getHtml

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Renders the gift voucher as HTML suitable for PDF conversion. Returns Twig-rendered content with `display=pdf`.

```APIDOC
## getHtml

### Description
Renders the gift voucher as HTML suitable for PDF conversion. Returns Twig-rendered content with `display=pdf`.

### Method
[Method signature: getHtml(GiftVoucherPurchased $giftVoucherPurchased): string]

### Parameters
#### Path Parameters
- **$giftVoucherPurchased** (GiftVoucherPurchased) - Required - The voucher to render

### Response
#### Success Response
- Returns: HTML string

### Example
```php
$html = $service->getHtml($purchased);
$pdf = $pdfService->html2Pdf('voucher.pdf', $html);
```
```

--------------------------------

### Create or Modify Gift Voucher

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Handles both GET requests to display a form for creating or modifying a gift voucher, and POST requests to submit the form data. Handles form validation errors.

```http
GET /gift-voucher/create
POST /gift-voucher/create
  object=Premium Weekend Package
  slug=premium-weekend-package
  description=Includes hotel stay and meals
  valid[years]=1
  amount=5000
  currency=EUR
```

```http
GET /gift-voucher/modify/1
```

--------------------------------

### getAll

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Retrieves all purchased but not-yet-used gift vouchers with valid identifiers.

```APIDOC
## getAll

### Description
Retrieves all purchased but not-yet-used gift vouchers with valid identifiers.

### Method
[Method signature: getAll(): array|QueryBuilder]

### Response
#### Success Response
- Returns: Array or Doctrine QueryBuilder of `GiftVoucherPurchased` entities

### Example
```php
$unused = $service->getAll();
foreach ($unused as $purchased) {
    echo $purchased->getIdentifier();
}
```
```

--------------------------------

### Role Hierarchy Configuration

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/security.md

Sets up a hierarchy of roles, granting broader permissions to higher roles.

```yaml
# config/packages/security.yaml
security:
    role_hierarchy:
        ROLE_GIFT_VOUCHER_ADMIN: [ROLE_USER]
        ROLE_ADMIN: [ROLE_GIFT_VOUCHER_ADMIN]
```

--------------------------------

### GiftVoucherService Constructor

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

The constructor injects several dependencies required for the service's operation, including entity management, email services, form factories, utility services, request handling, and environment rendering.

```php
public function __construct(
    EntityManagerInterface $em,
    GiftVoucherEmailInterface $giftVoucherEmail,
    GiftVoucherFormFactoryInterface $giftVoucherFormFactory,
    ServiceToolsInterface $serviceTools,
    RequestStack $requestStack,
    Environment $environment
)
```

--------------------------------

### gv_view_all()

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/twig-extensions.md

Displays a complete view of all gift vouchers, including descriptions and offer buttons. It can optionally limit the number of vouchers displayed and specify the sorting order.

```APIDOC
## gv_view_all()

### Description
Displays a complete view of all gift vouchers with descriptions and offer buttons.

### Parameters
#### Path Parameters
- **number** (int) - Optional - Maximum number of vouchers to display (null = all). Defaults to null.
- **order** (string) - Optional - Field to sort by: 'object', 'id', 'slug', 'amount'. Defaults to 'object'.

### Usage Examples
```twig
{# Display all vouchers #}
{{ gv_view_all() }}

{# Display top 3 vouchers by name (default) #}
{{ gv_view_all(3) }}

{# Display top 5 vouchers by amount (price) #}
{{ gv_view_all(5, 'amount') }}

{# Display top 10 vouchers by ID #}
{{ gv_view_all(10, 'id') }}

{# Display top 3 by slug #}
{{ gv_view_all(3, 'slug') }}
```
```

--------------------------------

### GET|POST /gift-voucher/offer

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/endpoints.md

Lists all available gift vouchers or handles their purchase form submission. Publicly accessible.

```APIDOC
## GET|POST /gift-voucher/offer

### Description
This endpoint serves two purposes: a GET request displays an HTML page listing all available gift vouchers, while a POST request can be used to submit a gift voucher purchase form. It is publicly accessible.

### Method
GET, POST

### Endpoint
/gift-voucher/offer

### Authorization
Public (no auth required)

### Response
- GET: HTML page listing all available gift vouchers
- POST: Typically redirects to a payment form upon successful submission.
```

--------------------------------

### register

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Persists a purchased voucher to the database. Optionally marks as test data.

```APIDOC
## register

### Description
Persists a purchased voucher to the database. Optionally marks as test data.

### Method
[Method signature: register(GiftVoucherPurchased $giftVoucherPurchased, bool $test): void]

### Parameters
#### Path Parameters
- **$giftVoucherPurchased** (GiftVoucherPurchased) - Required - The voucher to persist
- **$test** (bool) - Required - If false, prepends '(TEST)' to object name

### Response
#### Success Response
- Returns: void

### Example
```php
$purchased = $service->create($available);
// ... fill in form data ...
$service->register($purchased, true); // live mode
```
```

--------------------------------

### Create Gift Voucher Forms

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/forms.md

Instantiate the GiftVoucherFormFactory and use it to create forms for available and purchased gift vouchers.

```php
public function __construct(
    ConfigServiceInterface $configService,
    FormFactoryInterface $formFactory
)
```

```php
$factory = new GiftVoucherFormFactory($configService, $formFactory);
$availableForm = $factory->create('create', new GiftVoucherAvailable());
$purchaseForm = $factory->create('offer', new GiftVoucherPurchased());
```

--------------------------------

### getOfferedBy

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Retrieves the name of the person who offered the voucher.

```APIDOC
## getOfferedBy(): ?string

### Description
Returns the name of the offerer.

### Method
GET

### Endpoint
/purchased/{identifier}
```

--------------------------------

### View Modes

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/types.md

Enum-like values for controlling the display of purchased vouchers.

```plaintext
'admin'     - Shows use/redemption button
'basic'     - Public view, no redemption options
'pdf'       - For PDF export (no styling)
```

--------------------------------

### GiftVoucherEmailInterface Method

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/types.md

Defines the contract for sending gift voucher-related emails.

```php
public function send(GiftVoucherPurchased $giftVoucherPurchased, string $giftVoucherHtml, string $identifierFormatted): void
```

--------------------------------

### Service Injection in Controller

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Demonstrates how to inject GiftVoucherBundle services into a controller's constructor for use in your application.

```php
class MyController {
    public function __construct(
        GiftVoucherAvailableServiceInterface $availableService,
        GiftVoucherPurchasedServiceInterface $purchasedService,
        GiftVoucherEmailInterface $emailService,
        GiftVoucherPaymentInterface $paymentService
    ) { }
}
```

--------------------------------

### Using GiftVoucherPurchased Repository in a Controller (ParamConverter)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/repositories.md

Demonstrates how a GiftVoucherPurchased entity can be automatically resolved and injected into a controller action using Doctrine's ParamConverter, leveraging the findOneBasedOnIdentifier method.

```php
// In PurchasedController
public function display(GiftVoucherPurchased $giftVoucherPurchased) {
    // $giftVoucherPurchased resolved via ParamConverter:
    // Uses findOneBasedOnIdentifier automatically
    return $this->render('display.html.twig', [
        'giftVoucher' => $giftVoucherPurchased
    ]);
}

// Manual query:
$repository = $this->getDoctrine()->getRepository(GiftVoucherPurchased::class);
$purchased = $repository->findOneBasedOnIdentifier('ABCDEFGHIJKLTMNP');
```

--------------------------------

### Configure TOS PDF URL

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/configuration.md

Set the URL or route name for the Terms of Sales PDF document. This is attached to every gift voucher purchase email.

```yaml
c975LGiftVoucher.tosPdf: https://mysite.com/terms-of-sales.pdf
```

--------------------------------

### Render Gift Voucher as HTML

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/services.md

Renders a specific gift voucher as HTML, suitable for conversion to PDF. It uses Twig templating and sets the display parameter to 'pdf'.

```php
$html = $service->getHtml($purchased);
$pdf = $pdfService->html2Pdf('voucher.pdf', $html);
```

--------------------------------

### setDescription

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Sets a copy of the description for the voucher. This method supports method chaining.

```APIDOC
## setDescription(?string $description): self

### Description
Sets a copy of the description.

### Method
POST

### Endpoint
/purchased

### Parameters
#### Request Body
- **description** (string) - Required - The description of the voucher.
```

--------------------------------

### Set Offered By

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/entities.md

Sets the name of the person offering the voucher. Returns the object for method chaining.

```php
$purchased->setOfferedBy('John Doe');
```

--------------------------------

### Explicit Voter Check for Deletion

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/security.md

Demonstrates the correct way to check for delete permissions using denyAccessUnlessGranted. Avoid direct service calls without access control.

```php
// Good: Explicit voter check
$this->denyAccessUnlessGranted('c975LGiftVoucher-delete', $voucher);

// Bad: No access control
$service->delete($voucher);
```

--------------------------------

### GiftVoucherPaymentInterface Method

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/types.md

Defines the contract for processing gift voucher payments.

```php
public function payment(GiftVoucherPurchased $giftVoucherPurchased, $user): void
```

--------------------------------

### Create a Gift Voucher (Admin Workflow)

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/README.md

Workflow for administrators to create new available gift voucher types.

```APIDOC
## Create a Gift Voucher (Admin Workflow)

### Step 1: Display Creation Form
- **Method**: GET
- **Endpoint**: `/gift-voucher/create`
- **Description**: Displays the form for creating a new `GiftVoucherAvailable`.

### Step 2: Submit Voucher Data
- **Method**: POST
- **Endpoint**: `/gift-voucher/create`
- **Description**: Submits the data for a new `GiftVoucherAvailable`.
- **Request Body Example**:
```json
{
  "object": "Premium Weekend Package",
  "slug": "premium-weekend-package",
  "description": "Includes hotel and meals",
  "valid": "P1Y",
  "amount": 50000,
  "currency": "EUR"
}
```

### Step 3: Confirmation
- **Action**: Service validates and saves the voucher to the database.
- **Redirect**: Redirects to `/gift-voucher/display/{id}`.
```

--------------------------------

### Create and Handle Gift Voucher Purchase Form

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/forms.md

Use this snippet to create a form for purchasing gift vouchers, handle the incoming request, and validate the submitted data. It includes logic for checking GDPR consent if the field is present.

```php
$purchased = $giftVoucherPurchasedService->create($available);
$form = $formFactory->create('offer', $purchased, [
    'config' => ['gdpr' => true]
]);

$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
    // Check GDPR consent if applicable
    if ($form->get('gdpr')) {
        // User accepted GDPR terms
    }
    $giftVoucherPurchasedService->register($purchased, $isLive);
}
```

--------------------------------

### gv_offer_button()

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/twig-extensions.md

Displays a button linking to the gift voucher offer page. It accepts a gift voucher ID and an optional CSS class for styling.

```APIDOC
## gv_offer_button()

### Description
Displays a button linking to the gift voucher offer page.

### Parameters
#### Path Parameters
- **id** (int) - Required - Gift voucher ID
- **style** (string) - Optional - CSS class(es) for button styling. Defaults to 'btn btn-lg btn-block btn-primary'.

### Usage Examples
```twig
{# Display with default style #}
{{ gv_offer_button(5) }}

{# Display with custom Bootstrap classes #}
{{ gv_offer_button(5, 'btn btn-primary') }}
{{ gv_offer_button(5, 'btn btn-lg btn-success') }}

{# Display with custom CSS class #}
{{ gv_offer_button(5, 'my-custom-button-style') }}
```
```

--------------------------------

### gv_select()

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/twig-extensions.md

Displays a dropdown/select form for choosing a gift voucher. It can optionally pre-select a voucher by its ID.

```APIDOC
## gv_select()

### Description
Displays a dropdown/select form for choosing a gift voucher.

### Parameters
#### Path Parameters
- **id** (int) - Optional - ID of pre-selected voucher (0 = none selected). Defaults to 0.

### Usage Examples
```twig
{# Display select with no pre-selection #}
{{ gv_select() }}

{# Display select with voucher 5 pre-selected #}
{{ gv_select(5) }}

{# Use with Select2 library for enhanced UI #}
<div class="form-group">
    <label for="gift-voucher-select">Choose a Gift Voucher:</label>
    {{ gv_select() }}
</div>

<script>
    $('#gift-voucher-select').select2({
        placeholder: "Select a gift voucher",
        allowClear: true
    });
</script>
```
```

--------------------------------

### Display Gift Voucher Offer Link

Source: https://github.com/975l/giftvoucherbundle/blob/master/README.md

Use `gv_offer_link()` to display a link to offer a gift voucher. This is useful for directing users to gift voucher details.

```twig
{{ gv_offer_link(GIFTVOUCHER_AVAILABLE_ID) }}
```

--------------------------------

### Enum-like Patterns

Source: https://github.com/975l/giftvoucherbundle/blob/master/_autodocs/types.md

Describes enum-like patterns used for form actions, view modes, and query parameters within the Gift Voucher Bundle.

```APIDOC
## Enum-like Patterns

### Form Action Values

Used in GiftVoucherAvailableType:
```
'create'    - New voucher form
'modify'    - Edit existing voucher
'duplicate' - Clone voucher form
'delete'    - Deletion confirmation
```

### View Modes

In purchased voucher display:
```
'admin'     - Shows use/redemption button
'basic'     - Public view, no redemption options
'pdf'       - For PDF export (no styling)
```

### Query Parameters

Dashboard endpoint:
```
v='available'   - Show available vouchers
v='purchased'   - Show purchased vouchers
p=1,2,3...      - Page number for pagination
```
```