Documentation

Checkout Extensions

The ShopBite plugin offers advanced checkout functions specifically developed for gastronomy and retail businesses. This chapter explains the configuration and use of these functions.

Overview

The checkout extensions include:

  • Container-based products: Special processing for product groups
  • Receipt print types: Different print formats for various products
  • Custom Fields: Advanced product attributes for gastronomy
  • Delivery time calculation: Dynamic calculation based on product attributes
  • Order types: Pickup, Delivery, On-site

Container-based Products

How it works

Container-based products allow the grouping of items:

  • Example: Menu with main dish, side dish, and drink
  • Advantages: Easy ordering of complex product combinations
  • Processing: Special logic in the checkout process

Configuration

  1. Create product:
    • Navigate to Catalog > Products
    • Create New product
    • Product type: Select "Container"
  2. Define container contents:
    • Add container elements
    • Mark Mandatory fields
    • Configure Selection options
  3. Pricing:
    • Fixed price: Total price for the container
    • Dynamic price: Sum of included items
    • Discounts: Container-specific discounts

Example: Pizza Menu

Container: Pizza Menu
- Main dish: Pizza (Mandatory)
  - Options: Margherita, Salami, Hawaii
- Side dish: Salad or Fries (Mandatory)
  - Options: Caesar Salad, Mixed Salad, Fries
- Drink: Optional
  - Options: Cola, Fanta, Water, Beer

Receipt Print Types

Custom Fields Configuration

  1. Set up Custom Fields:
    • Navigate to Settings > Custom Fields
    • Select ShopBite Product Set
  2. Receipt Print Type field:
    • Field name: shopbite_receipt_print_type
    • Type: Select field
    • Options:
      • standard: Normal receipt printing
      • kitchen: Kitchen receipt for preparation
      • bar: Bar receipt for drinks
      • no_print: No receipt printing required

Product Configuration

  1. Edit product:
    • Navigate to Catalog > Products
    • Select product
  2. Set Custom Fields:
    • Select Receipt Print Type
    • Save

Example Configuration

ProductReceipt Print TypeDescription
Pizza MargheritakitchenPrepared in the kitchen
Cola 0.33lbarServed at the bar
DessertstandardNormal receipt printing
Voucherno_printNo physical receipt needed

Technical Implementation

The ReceiptPrintTypeProcessor processes the receipt print types:

// src/Checkout/Cart/ReceiptPrintTypeProcessor.php

public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
{
    foreach ($toCalculate->getLineItems()->filterFlatByType(LineItem::PRODUCT_LINE_ITEM_TYPE) as $lineItem) {
        $productId = $lineItem->getReferencedId();
        if ($productId === null) {
            continue;
        }
        
        $product = $data->get(self::DATA_KEY . $productId);
        if ($product === null) {
            continue;
        }
        
        $customFields = $product->getCustomFields() ?? [];
        if (!isset($customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE])) {
            continue;
        }
        
        $lineItem->setPayloadValue(
            CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE,
            $customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE]
        );
    }
}

Delivery Time Calculation

Custom Fields for Delivery Times

  1. Delivery time factor field:
    • Field name: shopbite_delivery_time_factor
    • Type: Integer
    • Default value: 1
  2. Product configuration:
    • Factor 1: Standard delivery time
    • Factor 2: Double delivery time
    • Factor 3: Triple delivery time

Calculation Logic

// Example calculation in the storefront
function calculateDeliveryTime(product) {
    const baseTime = 30; // Base delivery time in minutes
    const factor = product.customFields?.shopbite_delivery_time_factor || 1;
    
    return baseTime * factor; // Result in minutes
}

// Example
const pizza = { customFields: { shopbite_delivery_time_factor: 2 } };
const deliveryTime = calculateDeliveryTime(pizza); // 60 minutes

Example Products

ProductFactorCalculated Delivery Time
Pizza260 minutes
Salad130 minutes
Drink0.515 minutes
Dessert130 minutes

Order Types

Configuration

  1. Enable order types:
    • Navigate to ShopBite > Checkout > Order Types
    • Enable desired types
  2. Order types:
    • Pickup: Customers pick up the order themselves
    • Delivery: Order is delivered
    • On-site: Order for immediate consumption

Checkout Integration

// Order types in the storefront
const orderTypes = [
    { id: 'pickup', name: 'Pickup', description: 'Self pickup' },
    { id: 'delivery', name: 'Delivery', description: 'Delivery' },
    { id: 'on_site', name: 'On-site', description: 'Eat here' }
];

// Select order type
function selectOrderType(typeId) {
    // Logic for selecting order type
    console.log(`Order type selected: ${typeId}`);
}

Custom Fields Installation

Automatic Installation

The plugin installs the Custom Fields automatically:

// src/Service/CustomFieldsInstaller.php

public function install(Context $context): void
{
    $customFieldSetId = Uuid::fromHexToBytes(self::CUSTOM_FIELDSET_ID);
    
    $customFieldSetData = [
        'id' => self::CUSTOM_FIELDSET_ID,
        'name' => self::CUSTOM_FIELDSET_NAME,
        'config' => [
            'label' => [
                'en-GB' => 'ShopBite',
                'de-DE' => 'ShopBite',
            ],
        ],
        'customFields' => [
            [
                'id' => '0198be8b24a0722cac46b07e3a9686ec',
                'name' => 'shopbite_delivery_time_factor',
                'type' => CustomFieldTypes::INT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Delivery Time Factor',
                        'de-DE' => 'Lieferzeitfaktor',
                    ],
                ],
            ],
            [
                'id' => '01944f2b1875706596395b8d23966952',
                'name' => self::SHOPBITE_RECEIPT_PRINT_TYPE,
                'type' => CustomFieldTypes::SELECT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Receipt Print Type',
                        'de-DE' => 'Bon-Drucktyp',
                    ],
                    'options' => [
                        ['value' => 'standard', 'label' => ['en-GB' => 'Standard', 'de-DE' => 'Standard']],
                        ['value' => 'kitchen', 'label' => ['en-GB' => 'Kitchen', 'de-DE' => 'Küche']],
                        ['value' => 'bar', 'label' => ['en-GB' => 'Bar', 'de-DE' => 'Bar']],
                        ['value' => 'no_print', 'label' => ['en-GB' => 'No Print', 'de-DE' => 'Kein Druck']],
                    ],
                ],
            ],
        ],
    ];
    
    $this->customFieldSetRepository->upsert([$customFieldSetData], $context);
}

Manual Installation

If automatic installation fails:

# Manually install Custom Fields
bin/console shopbite:custom-fields:install

# Check Custom Fields
bin/console custom-field:set:list | grep shopbite

API Integration

Checkout API Endpoints

POST /store-api/checkout/cart/line-item

Example Request

curl -X POST "https://your-shopware-domain.com/store-api/checkout/cart/line-item" \
  -H "Authorization: Bearer YourAPIToken" \
  -H "sw-access-key: YourAccessKey" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ]
  }'

Example Response

{
  "data": {
    "lineItems": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ],
    "deliveryTime": 60
  }
}

Best Practices

1. Consistent Product Configuration

  • Use uniform Custom Fields for all products
  • Document the meaning of the fields
  • Train your team in correct usage

2. Performance Optimization

-- Indexes for Custom Fields
CREATE INDEX `idx_custom_fields` ON `product` (`custom_fields`);

-- Optimization for frequent queries
CREATE INDEX `idx_receipt_print_type` ON `product` 
  ((CAST(custom_fields->>'$.shopbite_receipt_print_type' AS CHAR(50))));

3. Validation

// Validation in the checkout process
public function validateCheckout(Cart $cart): array
{
    $errors = [];
    
    foreach ($cart->getLineItems() as $lineItem) {
        $payload = $lineItem->getPayload();
        
        if (!isset($payload['shopbite_receipt_print_type'])) {
            $errors[] = sprintf(
                'Product %s has no receipt print type',
                $lineItem->getLabel()
            );
        }
        
        if (!isset($payload['shopbite_delivery_time_factor'])) {
            $errors[] = sprintf(
                'Product %s has no delivery time factor',
                $lineItem->getLabel()
            );
        }
    }
    
    return $errors;
}

4. Caching Strategy

# In config/packages/cache.yaml
framework:
    cache:
        pools:
            shopbite.checkout:
                adapter: cache.adapter.redis
                default_lifetime: 300  # 5 minutes cache

Troubleshooting

Common Issues

Problem: Custom Fields are not displayed

Symptoms:

  • Custom Fields are missing in the administration
  • Fields are not saved

Solutions:

# Reinstall Custom Fields
bin/console shopbite:custom-fields:install --force

# Clear cache
bin/console cache:clear

# Check database
mysql -u shopware -p shopware -e "SELECT * FROM custom_field_set WHERE name = 'shopbite_product_set';"

Problem: Receipt print type is ignored

Symptoms:

  • All receipts are printed with standard type
  • Custom Field values are not applied

Solutions:

# Check checkout processor
bin/console debug:container --tag=shopware.checkout.cart.processor

# Refresh plugin cache
bin/console plugin:refresh ShopBite

# Check Custom Fields
bin/console custom-field:set:list

Problem: Delivery time calculation incorrect

Symptoms:

  • Incorrect delivery times
  • Calculation does not match expectations

Solutions:

# Check Custom Field values
mysql -u shopware -p shopware -e "
  SELECT id, custom_fields FROM product 
  WHERE custom_fields LIKE '%shopbite_delivery_time_factor%' LIMIT 5;
"

# Check calculation logic
bin/console config:get ShopBitePlugin.config.baseDeliveryTime

# Enable debug mode
bin/console config:set ShopBitePlugin.config.debug true

Next Steps