Overenozakazniky Laravel Package

Technical Evaluation

Architecture Fit

• Microservice/Event-Driven Fit: The package is ideal for order confirmation workflows in e-commerce, fitting seamlessly into Laravel’s event-driven architecture (e.g., OrderPlaced events). It can be triggered post-checkout via Laravel’s queues/jobs (e.g., LogOrderToHeurekaJob) for async processing.
• API-Centric Design: The package abstracts Heureka’s API into a thin PHP client, aligning with Laravel’s service container (dependency injection) and facade pattern for clean API consumption.
• Multi-TLD Support: Explicit support for CZ/SK markets via HEUREKA_CZ/HEUREKA_SK constants enables regional segmentation without code duplication.

Integration Feasibility

• Laravel Compatibility:
  • PHP 7.3+: Aligns with Laravel 8+/9+ (LTS versions).
  • PSR-4 Autoloading: Native support for Laravel’s Composer autoloading.
  • Exception Handling: Custom exceptions (e.g., RequesterException) integrate with Laravel’s exception handling (e.g., App\Exceptions\Handler).
• Data Flow:
  • Order Data Source: Requires email, orderId, and optional productItemIds (mapped from Laravel’s orders/order_items tables).
  • Heureka XML Feed IDs: Assumes ITEM_ID alignment with Heureka’s feed (may require migration if IDs differ).
• Async Potential: Can be wrapped in a Laravel Queue Job for non-blocking API calls.

Technical Risk

Key Questions

1. Data Mapping:
   • How are productItemIds sourced? Are they stored in Laravel’s DB, or generated dynamically?
   • Is there a mapping table for Heureka ITEM_ID ↔ Laravel product_id?
2. Error Handling:
   • Should failed API calls trigger customer notifications (e.g., email)?
   • How should rate limits (if any) be handled (exponential backoff, queue delays)?
3. Testing:
   • Are there mockable interfaces for the Heureka client to enable unit/integration tests?
   • Should feature flags control the Heureka integration rollout?
4. Performance:
   • Will this run in synchronous (checkout flow) or asynchronous (queue) mode?
   • What’s the expected volume of orders/day? (Scaling considerations for retries.)
5. Compliance:
   • Does Heureka’s API require GDPR-compliant data handling (e.g., customer consent for email tracking)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Provider: Register the Heureka client as a bound service (Heureka\ShopCertification) in AppServiceProvider.
  • Facade: Create a Heureka facade for cleaner syntax (e.g., Heureka::logOrder($order)).
  • Config: Store API keys/TLD in config/services.php:

    'heureka' => [
        'api_key' => env('HEUREKA_API_KEY'),
        'tld'     => env('HEUREKA_TLD', 'cz'), // 'cz' or 'sk'
    ],
    

• Database:
  • Order Model: Add accessors/mutators to extract email, orderId, and productItemIds:

    public function getHeurekaData(): array
    {
        return [
            'email' => $this->email,
            'orderId' => $this->id,
            'productItemIds' => $this->items->pluck('heureka_item_id')->toArray(),
        ];
    }
    

  • Product Model: Add heureka_item_id field if not already present.

Migration Path

1. Phase 1: Core Integration
   • Add package via Composer: composer require heureka/overeno-zakazniky.
   • Configure API key/TLD in .env and config/services.php.
   • Implement a service class to wrap the Heureka client:

     class HeurekaService
     {
         public function __construct(private ShopCertification $client) {}
     
         public function logOrder(Order $order): void
         {
             $this->client->setEmail($order->email);
             $this->client->setOrderId($order->id);
             $order->items->each(fn($item) => $this->client->addProductItemId($item->heureka_item_id));
             $this->client->logOrder();
         }
     }
     

2. Phase 2: Async Processing
   • Convert to a Laravel Job for background processing:

     class LogOrderToHeurekaJob implements ShouldQueue
     {
         use Dispatchable, InteractsWithQueue, Queueable;
     
         public function handle(HeurekaService $service, Order $order)
         {
             $service->logOrder($order);
         }
     }
     

   • Dispatch in OrderPlaced event listener:

     LogOrderToHeurekaJob::dispatch($order)->onQueue('heureka');
     

3. Phase 3: Observability
   • Add logging for API responses (success/failure).
   • Implement metrics (e.g., Prometheus) to track:
     • Orders logged successfully.
     • API latency.
     • Failure rates by error code.

Compatibility

• Laravel Versions: Tested on PHP 7.3+; compatible with Laravel 8/9/10.
• Heureka API: V2-only (no backward compatibility with V1).
• Data Format: Requires ITEM_ID alignment with Heureka’s XML feed (may need data migration if IDs differ).

Sequencing

1. Pre-requisites:
   • Heureka API key and TLD configured.
   • Order/product data models updated with heureka_item_id.
2. Development:
   • Start with synchronous calls in a staging environment.
   • Gradually migrate to async (queues) for production.
3. Rollout:
   • Enable via feature flag (e.g., config('services.heureka.enabled')).
   • Monitor error rates post-launch.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor heureka/overeno-zakazniky for breaking changes (e.g., PHP 8+ support).
  • Pin version in composer.json if stability is critical.
• API Key Rotation:
  • Implement a secure key management process (e.g., Laravel Forge/Vault).
  • Rotate keys periodically via .env updates.
• Documentation:
  • Add internal docs for:
    • How to update the Heureka client.
    • Troubleshooting common errors (e.g., 401 unauthorized).

Support

• Error Handling:
  • Map Heureka’s error codes to user-friendly messages (e.g., "Order logging failed; please contact support").
  • Log raw API responses for debugging:

    try {
        $this->client->logOrder();
    } catch (RequesterException $e) {
        \Log::error('Heureka API Error', ['response' => $e->getResponse()]);
        throw new \RuntimeException('Failed to log order to Heureka.');
    }
    

• Customer Communication:
  • For critical failures, notify customers via email or in-app banner (e.g., "We’re verifying your purchase with Heureka").
• Support Escalation:
  • Heureka’s support email (podpora@heureka.cz) for API-specific issues.

Scaling

• Queue Scaling:
  • Use Laravel Horizon or Redis queues to handle high-order volumes.
  • Scale workers based on queue length (e.g., auto-scale in Kubernetes).
• Rate Limiting:
  • Implement exponential backoff for retries (e.g., Laravel\Queue\Retryable).
  • Consider batch processing for bulk order logs (if API supports it).
• Database Load:
  • Ensure order_items table has an index on heureka_item_id for fast