Four Tochki Orders Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Bundle in Laravel: The package is a Symfony bundle, requiring adaptation for Laravel via Symfony bridge components (e.g., spatie/laravel-symfony-components). The bundle’s modular design (orders, payments, API integration) aligns with Laravel’s service-oriented architecture but introduces Doctrine ORM dependency, which may conflict with Eloquent. A hybrid approach (Doctrine for 4tochki-specific models, Eloquent for core) is feasible but adds complexity.
• Domain-Specificity: Tailored for 4tochki marketplace integration, making it ideal for businesses targeting the Russian/Ukraine e-commerce niche. However, its narrow focus limits reuse for other platforms.
• Event-Driven Potential: The bundle likely uses Symfony events (e.g., KernelEvents), which can be mapped to Laravel’s event system with minimal effort.

Integration Feasibility

• API Abstraction: The package abstracts 4tochki’s API (orders, payments, webhooks), reducing manual API handling. Feasible to wrap its core logic in Laravel services using Laravel’s HTTP client or Guzzle.
• Console Commands: Tools like baks:assets:install and migration scripts are Symfony-specific. Replacement with Laravel Artisan commands or custom scripts is necessary.
• Doctrine vs. Eloquent: Heavy reliance on Doctrine ORM for migrations/entities introduces friction. Options include:
  • Isolating Doctrine: Use Doctrine only for 4tochki-specific models (e.g., FourTochkiOrder) while keeping core models in Eloquent.
  • Hybrid ORM: Leverage packages like laravel-doctrine/orm to bridge Doctrine and Eloquent.

Technical Risk

• PHP 8.4+ Requirement: May force a Laravel upgrade (current LTS is 8.2), risking compatibility issues with existing dependencies. Mitigation: Test thoroughly or fork the bundle to support PHP 8.2.
• Undocumented Assumptions: Lack of community activity (0 stars) and minimal documentation suggest potential hidden dependencies or unclear conventions (e.g., API retry logic, error handling).
• Migration Complexity: Doctrine migrations may conflict with Laravel’s schema builder. Manual sync or a custom migration layer could be required.
• Testing Gaps: Limited test coverage (only four-tochki-orders group) raises concerns about edge cases (e.g., API failures, payment retries, webhook validation).

Key Questions

1. API Contract Stability: Does the bundle handle breaking changes in 4tochki’s API gracefully, or will updates require manual intervention?
2. State Management: How does the bundle manage idempotency, retry logic, and webhook validation? Can Laravel’s queue system (e.g., shouldQueue()) replace Symfony’s event system?
3. Performance: Does the bundle batch API requests or introduce latency? Are there rate-limiting mechanisms for 4tochki’s API?
4. Localization: Is the bundle’s output (e.g., error messages, logs) in Russian only? Will UI/UX require translation layers for non-Russian teams?
5. License Compliance: Does the bundle include third-party dependencies with stricter licenses (e.g., AGPL) that conflict with Laravel’s MIT license?
6. Webhook Reliability: How does the bundle handle webhook retries, signature validation, and duplicate events? Can Laravel’s signed events or HMAC checks replace this?
7. Multi-Environment Config: Does the bundle support environment-specific configurations (e.g., sandbox vs. production 4tochki API keys)? If not, how will Laravel’s .env integration work?

Integration Approach

Stack Fit

• Symfony Bridge:
  • Use spatie/laravel-symfony-components to integrate Symfony’s HttpFoundation, Console, and DependencyInjection into Laravel.
  • Replace Symfony’s Container with Laravel’s service container for dependency injection.
• API Abstraction Layer:
  • Extract the bundle’s 4tochki client logic into Laravel services (e.g., FourTochkiOrderService, FourTochkiPaymentService) using Laravel’s HTTP client or Guzzle.
  • Example:

    class FourTochkiOrderService {
        public function __construct(private HttpClient $http) {}
        public function createOrder(array $data): array {
            return $this->http->post('https://api.4tochki.ru/orders', $data);
        }
    }
    

• Event System:
  • Map Symfony events to Laravel events. For example:

    // Symfony event (in bundle)
    $dispatcher->dispatch(new OrderCreatedEvent($order));
    
    // Laravel equivalent
    event(new \App\Events\FourTochkiOrderCreated($order));
    

• ORM Hybridization:
  • Use Doctrine only for 4tochki-specific entities (e.g., FourTochkiOrder) and Eloquent for core models.
  • Leverage laravel-doctrine/orm to manage Doctrine entities alongside Eloquent models.

Migration Path

1. Phase 1: Dependency Isolation

   • Install the bundle in a separate namespace (e.g., Vendor\FourTochki) to avoid autoloading Symfony services globally.
   • Use composer scripts to run migrations only for 4tochki tables:

     php artisan doctrine:migrations:migrate --path=vendor/baks-dev/four-tochki-orders/migrations
     

   • Replace Symfony console commands with Laravel Artisan commands (e.g., php artisan fourtochki:install-assets).

2. Phase 2: Hybrid ORM Implementation

   • Configure Doctrine to work alongside Eloquent:
     • Add doctrine/orm to composer.json.
     • Set up a custom Doctrine entity manager for 4tochki models in AppServiceProvider:

       $this->app->bind(\Doctrine\ORM\EntityManagerInterface::class, function ($app) {
           return EntityManager::create([...], $app['config']['doctrine']);
       });
       

   • Manually map Doctrine entities to Eloquent models where possible (e.g., using HybridRepository).

3. Phase 3: Event and Console Replacement

   • Replace Symfony events with Laravel events:
     • Create listeners for FourTochkiOrderCreated, FourTochkiPaymentProcessed, etc.
     • Example listener:

       public function handle(FourTochkiOrderCreated $event) {
           // Sync with Laravel's orders table or trigger other logic
       }
       

   • Replace baks:assets:install with a Laravel command that copies assets to public/4tochki.

4. Phase 4: API Wrapper Layer

   • Create a facade or service to abstract the bundle’s API calls:

     class FourTochkiFacade {
         public static function createOrder(array $data) {
             return app(FourTochkiOrderService::class)->createOrder($data);
         }
     }
     

Compatibility

• Symfony vs. Laravel:
  • Breaking Points: Symfony’s Container, EventDispatcher, and Console components require wrappers. Mitigation:
    • Use Laravel’s service container to resolve Symfony services where possible.
    • Replace EventDispatcher with Laravel’s Event facade.
    • Replace console commands with Artisan commands.
  • Doctrine vs. Eloquent: Doctrine migrations may include non-standard SQL (e.g., PostgreSQL-specific). Test thoroughly and consider database abstraction layers.
• PHP Version:
  • If Laravel is on PHP 8.2, upgrade to 8.4 or fork the bundle to drop PHP 8.4-specific features (e.g., named arguments, new attributes).
• Database:
  • Doctrine migrations may introduce schema rigidity. Use transactions and backups during migrations.

Sequencing

1. Proof of Concept (PoC):
   • Integrate only the API client (without Doctrine) to validate core functionality.
   • Test order creation, retrieval, and basic webhook handling.
2. Feature Expansion:
   • Add webhook handling using Laravel queues + bundle logic.
   • Implement payment reconciliation (sync 4tochki orders with Laravel’s orders table).
   • Extend to shipping and inventory updates.
3. Performance Testing:
   • Benchmark API call latency and database writes under load.
   • Simulate high-order volumes to test queue and retry logic.
4. Full Integration:
   • Migrate to hybrid ORM (Doctrine + Eloquent).
   • Replace Symfony events and console commands.
   • Deploy in a staging environment with real 4tochki API traffic.

Operational Impact

Maintenance

• Vendor Lock-In: Tight coupling to 4tochki’s API may require frequent updates if their API changes. Mitigation:
  • Monitor 4tochki’s API changelog and update