Minishop Heureka Laravel Package

Technical Evaluation

Architecture Fit

• Monolithic Laravel Fit: The package is designed for MiniShop (Symfony-based), not Laravel. While Laravel and Symfony share some similarities (e.g., routing, dependency injection), this package assumes a Symfony Kernel (AppKernel) and bundles, which are not native to Laravel. Direct integration would require significant abstraction or a compatibility layer.
• Heureka API Dependency: Relies on heureka/overenozakazniky (a Heureka-specific library), which may introduce vendor-lock and maintenance risks if the API changes.
• Laravel Service Provider Alternative: Laravel uses Service Providers instead of Symfony bundles. The package’s CoreHeurekaBundle would need to be refactored or wrapped in a Laravel-compatible provider.

Integration Feasibility

• Medium-High Effort: Requires:
  1. Symfony-to-Laravel Adapter: Convert bundle registration to Laravel’s ServiceProvider.
  2. Routing System Override: Laravel’s routing (routes/web.php) differs from Symfony’s routing.yml.
  3. Configuration Handling: Symfony’s YAML config (config.yml) must map to Laravel’s config/heureka.php.
  4. Dependency Injection: Symfony’s container vs. Laravel’s IoC container (Pimple-based) may need alignment.
• Heureka API Wrapping: The heureka/overenozakazniky library may need to be Laravelized (e.g., using Facades, HTTP clients like Guzzle).

Technical Risk

• Breaking Changes: The package is in @dev state with no stars/dependents, indicating immature or untested code.
• Symfony-Specific Assumptions: Risks of hidden dependencies (e.g., Symfony’s EventDispatcher, Twig, or Doctrine).
• Maintenance Burden: If the upstream heureka/overenozakazniky changes, the Laravel wrapper may break without updates.
• Performance Overhead: Symfony bundles often include heavy configurations (e.g., event listeners, Twig extensions) that may bloat Laravel’s lightweight architecture.

Key Questions

1. Why Symfony? Is there a Laravel-native Heureka package (e.g., via API wrapper) that avoids Symfony dependencies?
2. API Stability: How frequently does Heureka’s API change? Is heureka/overenozakazniky actively maintained?
3. Feature Parity: Does this package cover all required Heureka functionalities (e.g., product feeds, order sync, pricing)?
4. Testing: Are there unit/integration tests? If not, how will edge cases (e.g., failed API calls) be handled?
5. Alternatives: Could a custom Laravel service (using Guzzle + Heureka’s API docs) achieve the same result with less risk?

Integration Approach

Stack Fit

• Laravel Incompatibility: The package is not natively Laravel-compatible. Options:
  • Option 1: Full Reimplementation – Build a Laravel service provider that mirrors Heureka’s API calls (recommended for long-term maintainability).
  • Option 2: Symfony Microkernel – Run MiniShopHeureka as a separate Symfony micro-service and communicate via API (high complexity).
  • Option 3: Partial Integration – Use only the Heureka API (heureka/overenozakazniky) directly in Laravel, bypassing the bundle.
• Recommended Stack:
  • Laravel 10+ (for dependency injection and HTTP clients).
  • Guzzle HTTP Client (for Heureka API calls).
  • Laravel Service Provider (to encapsulate Heureka logic).
  • Laravel Config (replace YAML config with config/heureka.php).

Migration Path

1. Assessment Phase:
   • Audit Heureka’s API requirements (e.g., product feed format, authentication).
   • Compare birko/minishop-heureka vs. direct API integration.
2. Proof of Concept (PoC):
   • Implement a minimal Heureka client in Laravel (using Guzzle + API docs).
   • Test core functionalities (e.g., product sync, order push).
3. Refactor or Replace:
   • If PoC succeeds, deprecate the Symfony bundle in favor of the Laravel-native solution.
   • If bundle is critical, wrap it in a Laravel Service Provider (high effort).
4. Deprecation Plan:
   • Phase out birko/minishop-heureka in favor of a maintained Laravel package.

Compatibility

• Routing: Symfony’s routing.yml → Laravel’s routes/web.php (manual mapping required).
• Configuration:

  # Symfony (input)
  core_heureka:
      prices: ['normal']
      key: ~
  

  →

  // Laravel (output, config/heureka.php)
  'heureka' => [
      'prices' => ['normal'],
      'api_key' => env('HEUREKA_API_KEY'),
  ]
  

• Dependency Injection:
  • Replace Symfony’s ContainerAware with Laravel’s bindings or Facades.
  • Example:

    // Symfony (bundle service)
    $this->container->get('heureka.client');
    

    →

    // Laravel (Service Provider)
    $this->app->bind('heureka.client', function () {
        return new HeurekaClient(config('heureka.api_key'));
    });
    

Sequencing

1. Phase 1: API-First Approach (2-4 weeks)
   • Implement Heureka logic without the bundle (direct API calls).
   • Validate against MiniShop’s data model.
2. Phase 2: Bundle Wrapping (if Phase 1 fails)
   • Create a Laravel ServiceProvider to load the Symfony bundle (complex, high risk).
3. Phase 3: Testing & Optimization
   • Load test with production-like data.
   • Optimize API call batching/retries.
4. Phase 4: Deprecation
   • Remove birko/minishop-heureka from composer.json.
   • Document the custom Laravel solution.

Operational Impact

Maintenance

• High Ongoing Effort:
  • Symfony Bundle: Requires monitoring for upstream (heureka/overenozakazniky) changes.
  • Custom Laravel Solution: Easier to maintain but needs API contract tests to catch Heureka changes.
• Dependency Risks:
  • birko/minishop-heureka is unmaintained (no stars, @dev).
  • heureka/overenozakazniky may have undocumented breaking changes.
• Recommended: Fork and maintain if using the bundle, or switch to a direct API integration.

Support

• Limited Community Support:
  • No GitHub stars/issues → no community troubleshooting.
  • Heureka’s official docs may be the only resource.
• Internal Documentation Needed:
  • Runbooks for API failures (e.g., rate limits, auth errors).
  • Example error handling:

    try {
        $response = $heurekaClient->syncProducts();
    } catch (HeurekaApiException $e) {
        Log::error("Heureka sync failed: " . $e->getMessage());
        // Retry or notify admin
    }
    

Scaling

• API Rate Limits:
  • Heureka may throttle requests. Implement:
    • Exponential backoff for retries.
    • Queue workers (Laravel Queues) for async processing.
• Data Volume:
  • Large product catalogs? Use chunked API calls or database batching.
• Performance Bottlenecks:
  • Symfony bundle may introduce unnecessary overhead (e.g., Twig, events).
  • Direct Laravel API calls are lighter.

Failure Modes

Ramp-Up

• Learning Curve:
  • Symfony Bundle: Steep (requires Symfony knowledge).
  • Direct API Integration: Moderate (familiar to Laravel devs).
• Onboarding Steps:
  1. Document Heureka API Contracts (endpoints, payloads, auth).
  2. Set Up Local Testing (mock Heureka responses with Laravel’s Http::fake()).
  3. Train Devs on Laravel Service Providers (if wrapping the bundle).