Yandex Market Orders Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Monolith Alignment: The package is tightly coupled to Laravel’s ecosystem (Doctrine ORM, Symfony Console, Eloquent-like patterns), making it ideal for traditional Laravel monolithic applications focused on e-commerce. It assumes a centralized order management system with integrated payment and delivery workflows.
• Domain-Specific: Optimized for Yandex Marketplace (FBS/DBS) order processing, including:
  • Order intake and status synchronization.
  • Payment handling via Yandex.Kassa.
  • Delivery integration (seller-managed or marketplace-managed).
• Extensibility Constraints:
  • Limited Hooks: Lacks explicit event-driven architecture (e.g., Laravel Events or Symfony Messenger), requiring service overrides or middlewares for custom logic.
  • Opinionated Schema: Doctrine migrations enforce a specific database structure, which may conflict with existing order/payment models.
• Non-E-Commerce Use Cases: Poor fit for B2B, SaaS, or non-transactional Laravel apps unless Yandex Market is a core feature.

Integration Feasibility

• Dependencies:
  • Hard Dependencies:
    • baks-dev/yandex-market (core API wrapper).
    • Laravel 10.x+ (implied by PHP 8.4+ and Symfony Console).
    • Doctrine ORM (for migrations; conflicts with Eloquent if not using both).
  • External APIs:
    • Yandex Marketplace API (FBS/DBS): Requires OAuth tokens, rate-limit handling, and webhook validation.
    • Yandex.Kassa: Async payment confirmations via webhooks; may need retry logic for failed callbacks.
  • Risk: Tight coupling with baks-dev/yandex-market could lead to vendor lock-in or upgrade pain if the package evolves independently.
• Database Schema:
  • Custom Migrations: The package introduces order, payment, and delivery tables with Yandex-specific fields (e.g., marketplace_order_id, delivery_type).
  • Conflict Resolution:
    • Option 1: Extend existing tables (e.g., add Yandex columns to orders).
    • Option 2: Use parallel schemas (e.g., yandex_market_orders) with join tables.
    • Option 3: Replace existing models (high risk of breaking changes).
  • Recommendation: Pre-integration schema audit to plan merges or extensions.
• API/Webhook Handling:
  • Assumed but Undocumented: The README lacks details on:
    • Webhook endpoints for order updates/payments.
    • Error handling for API failures (e.g., rate limits, token expiration).
    • Mitigation: Implement stub handlers early and test with Yandex’s sandbox.

Technical Risk

Key Questions

1. Business Priorities:
   • Is Yandex Market a primary sales channel or a pilot feature? This dictates integration urgency.
   • Are there existing order/payment systems that must coexist or be replaced?
2. Technical Constraints:
   • What’s the current Laravel/PHP version? (Package requires PHP 8.4+.)
   • Does the app use Eloquent or Doctrine? Schema conflicts may arise if mixing ORMs.
   • Are there existing payment/delivery integrations (e.g., Stripe, custom couriers) that could clash?
3. Operational Requirements:
   • Who manages Yandex API credentials (tokens, OAuth) and their rotation?
   • What’s the SLA for Yandex API failures (e.g., retries, fallback mechanisms)?
4. Customization Needs:
   • Are there unique order workflows (e.g., partial refunds, custom delivery rules) not supported?
   • Does the app need multi-marketplace support (e.g., Yandex + Wildberries)? If so, this package is too niche.

Integration Approach

Stack Fit

• Laravel Core Compatibility:
  • Pros:
    • Designed for Laravel 10.x+ with Symfony Console (aligns with artisan).
    • Uses Doctrine ORM (compatible with Eloquent if configured).
    • MIT license enables seamless embedding.
  • Cons:
    • No API-first design: Optimized for CLI/migration workflows, not REST/GraphQL.
    • Monolithic assumptions: Assumes a traditional MVC Laravel app; may conflict with microservices or event-driven architectures.
• Non-Laravel Stacks: Not applicable—hard dependency on Laravel/Symfony components.

Migration Path

1. Pre-Integration Phase:
   • Audit:
     • Review existing order/payment/delivery models and DB schema.
     • Check for dependency conflicts (e.g., other packages using baks-dev/yandex-market).
   • Environment Setup:
     • Isolate a staging environment with PHP 8.4+ and Laravel 10.x+.
     • Install dependencies:

       composer require baks-dev/yandex-market baks-dev/yandex-market-orders
       

2. Configuration:
   • Choose FBS/DBS: Run the appropriate console commands:

     php bin/console baks:users-profile-type:yandex-market-fbs
     php bin/console baks:payment:yandex-market-fbs
     php bin/console baks:delivery:yandex-market-fbs
     

   • Install Assets/Migrations:

     php bin/console baks:assets:install
     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

   • Configure API Credentials: Add to .env:

     YANDEX_MARKET_FBS_TOKEN=your_token_here
     YANDEX_KASA_SECRET=your_secret_key
     

3. Customization:
   • Override Services: Use Laravel’s bindings to extend default behavior:

     // app/Providers/YandexMarketServiceProvider.php
     public function register()
     {
         $this->app->bind(
             \BaksDev\YandexMarket\Services\OrderService::class,
             fn() => new \App\Services\CustomYandexOrderService()
         );
     }
     

   • Webhook Handling: Implement endpoints for:
     • Order updates (e.g., POST /yandex-market/webhooks/orders).
     • Payment confirmations (e.g., POST /yandex-kassa/webhooks).
4. Testing:
   • Run package tests:

     php bin/phpunit --group=yandex-market-orders
     

   • Add integration tests for:
     • Order creation → payment capture → delivery update.
     • Webhook payload validation.

Compatibility

• Database:
  • Doctrine vs. Eloquent: If using Eloquent, extend the package’s models or create join tables to avoid schema conflicts.
  • Existing Data: Plan for data migration if replacing legacy order systems.
• APIs:
  • Yandex Marketplace: Test rate limits, token rotation, and error handling (e.g., 429 Too Many Requests).
  • Yandex.Kassa: Validate webhook signatures and async payment flows.
• Laravel Ecosystem:
  • Queue Workers: Configure Laravel Queues for async order processing.
  • Caching: Align with Laravel’s cache drivers for API token storage.

Sequencing

1. Phase 1: Core Setup (1-2 weeks):
   • Install package, run migrations, configure credentials.
   • Implement basic order flow (creation, status sync).
2. Phase 2: Payment/Delivery (1 week):
   • Set up Yand