Getting Started

Minimal Setup

Installation Add the package via Composer (note the @dev tag implies this is pre-release):
```
composer require birko/minishop-heureka "@dev"
composer require heureka/overenozakazniky "dev-master"
```
Ensure your composer.json includes both dependencies under "require".
Bundle Registration Register CoreHeurekaBundle in app/AppKernel.php:
```
$bundles[] = new Core\HeurekaBundle\CoreHeurekaBundle();
```

Routing Include Heureka routes in app/config/routing.yml:

core_heureka:
    resource: "@CoreHeurekaBundle/Resources/config/routing.yml"
    prefix: /

Configuration Define Heureka settings in app/config/config.yml:

core_heureka:
    prices: ['normal']  # Supported price types (extend as needed)
    key: %heureka_api_key%  # Replace with your Heureka API key

First Use Case Trigger a product feed update via CLI:
```
php app/console heureka:feed:generate
```
Verify the feed at /heureka/feed.xml (or configured endpoint).

Implementation Patterns

Core Workflows

Product Feed Generation
- Automated Sync: Schedule heureka:feed:generate via Laravel’s task scheduler (app/console schedule:run).
- Manual Trigger: Call the command programmatically:
```
$this->call('heureka:feed:generate');
```
- Event-Driven: Hook into ProductUpdated events to update Heureka feeds incrementally:
```
Event::listen('product.updated', function ($product) {
    // Rebuild feed for this product only
});
```
Price Management
- Use the prices config array to filter which price types (e.g., normal, sale) are exposed to Heureka.
- Extend the PriceTransformer service to map custom price logic:
```
// app/config/services.yml
core_heureka.price_transformer:
    class: AppBundle\Service\CustomHeurekaPriceTransformer
    arguments: ["@minishop.product.price_service"]
```

Image Handling

Heureka requires images in specific formats (e.g., 800x800px). Override the ImageTransformer:

class CustomImageTransformer extends \Core\HeurekaBundle\Transformer\ImageTransformer
{
    public function transform($imageUrl, $product)
    {
        // Custom logic (e.g., resize, CDN rewrite)
        return parent::transform($imageUrl, $product);
    }
}

Attribute Mapping

Custom product attributes (e.g., color, material) must map to Heureka’s schema. Extend the ProductTransformer:

class CustomProductTransformer extends \Core\HeurekaBundle\Transformer\ProductTransformer
{
    protected function getCustomAttributes($product)
    {
        return [
            'color' => $product->getAttribute('color'),
            'material' => $product->getAttribute('material'),
        ];
    }
}

Integration Tips

MiniShop Compatibility: Ensure your Product model extends MiniShop\ProductBundle\Entity\Product. If not, create a custom transformer to bridge the gap.

Caching: Cache the generated feed XML to reduce API load:

$feed = Cache::remember('heureka_feed', 3600, function () {
    return $this->generateFeed();
});

Validation: Use Heureka’s validation API to test your feed before submission:

curl -X POST https://api.heureka.cz/feed/validate --data-urlencode "feed=@/path/to/feed.xml"

Gotchas and Tips

Common Pitfalls

API Key Misconfiguration
- Issue: Feeds fail silently if key is missing or invalid in config.yml.
- Fix: Validate the key via Heureka’s API dashboard and ensure it’s loaded as a parameter:
```
parameters:
    heureka_api_key: %env(HEUREKA_API_KEY)%
```
Price Mismatches
- Issue: Heureka rejects feeds with prices not in the prices config array.
- Fix: Double-check the prices array in config and ensure your Product model’s price logic aligns:
```
// Example: Only expose 'normal' prices
$product->getHeurekaPrice() {
    return $this->getPrice('normal');
}
```
Image URL Issues
- Issue: Broken image links cause feed validation failures.
- Fix: Use absolute URLs and handle missing images gracefully:
```
public function transform($imageUrl, $product) {
    return $imageUrl ? asset($imageUrl) : asset('images/default-heureka.jpg');
}
```
Character Encoding
- Issue: Special characters (e.g., č, š) may corrupt the XML feed.
- Fix: Enforce UTF-8 encoding in your transformer:
```
$feed->encoding = 'UTF-8';
```
Namespace Collisions
- Issue: If CoreHeurekaBundle conflicts with other bundles (e.g., CoreBundle), rename the namespace in AppKernel.php:
```
new \Vendor\HeurekaBundle\CoreHeurekaBundle(),
```

Debugging Tips

Enable Debug Mode: Add this to config.yml to log feed generation:
```
core_heureka:
    debug: true
```
Check storage/logs/heureka.log for errors.
Dry-Run Validation: Use Heureka’s sandbox environment (https://sandbox.heureka.cz) to test feeds before going live.
XPath Inspection: Validate the XML structure with:
```
xmllint --format /path/to/feed.xml
```

Extension Points

Custom Feed Types Extend the FeedGenerator to support multiple feed formats (e.g., CSV for bulk imports):

class CsvFeedGenerator extends \Core\HeurekaBundle\Generator\FeedGenerator
{
    public function generate() {
        // Custom CSV logic
    }
}

Webhook Integration Listen for Heureka’s webhook events (e.g., feed acceptance/rejection):

// app/config/routing.yml
heureka_webhook:
    path: /heureka/webhook
    defaults: { _controller: AppBundle\Controller\HeurekaWebhookController::handle }

Multi-Store Support Override the StoreTransformer to handle multiple MiniShop stores:

class MultiStoreTransformer extends \Core\HeurekaBundle\Transformer\StoreTransformer
{
    public function transform($store) {
        return [
            'id' => $store->getHeurekaId(),
            'name' => $store->getName(),
            // Add store-specific logic
        ];
    }
}

Rate Limiting Implement a queue system (e.g., Laravel Queues) to avoid hitting Heureka’s API limits:
```
Queue::push(new UpdateHeurekaFeedJob($product));
```

Minishop Heureka Laravel Package