Four Tochki Orders Laravel Package

Getting Started

Minimal Steps to First Order Sync

1. Install and Configure

   composer require baks-dev/four-tochki-orders
   php artisan vendor:publish --provider="BaksDev\FourTochkiOrders\FourTochkiOrdersBundle" --tag="config"
   php artisan baks:assets:install  # Copies assets to public/4tochki
   php artisan doctrine:migrations:migrate  # Runs bundle migrations
   

2. First Order Fetch Use the OrderService to pull orders from 4tochki:

   use BaksDev\FourTochkiOrders\Service\OrderService;
   
   public function fetchOrders(OrderService $orderService) {
       $orders = $orderService->getOrders(['status' => 'new', 'limit' => 10]);
       foreach ($orders as $order) {
           // Process order (e.g., create in your Laravel DB)
           \App\Models\Order::create($order->toArray());
       }
   }
   

   • Key Classes:
     • OrderService: Core API interaction.
     • Order: Doctrine entity (map to Eloquent if needed).
     • FourTochkiOrdersBundle: Bundle configuration.

3. Webhook Setup (Optional) If 4tochki supports webhooks, configure the bundle’s listener in config/four_tochki_orders.php:

   'webhooks' => [
       'enabled' => true,
       'secret' => env('FOURTOCHKI_WEBHOOK_SECRET'),
       'routes' => [
           'order.created' => 'app\Http\Controllers\FourTochkiWebhookController@handleOrderCreated',
       ],
   ],
   

   • Verify the route in routes/web.php (Symfony’s routing.yml may need conversion).

4. Environment Variables Add to .env:

   FOURTOCHKI_API_KEY=your_api_key
   FOURTOCHKI_API_SECRET=your_secret
   FOURTOCHKI_SHOP_ID=your_shop_id
   

Implementation Patterns

Core Workflows

1. Order Synchronization

• Pattern: Use OrderService in a scheduled job (e.g., Laravel’s schedule:run).
• Example:

  // app/Console/Commands/FetchFourTochkiOrders.php
  use BaksDev\FourTochkiOrders\Service\OrderService;
  use Illuminate\Console\Command;
  
  class FetchFourTochkiOrders extends Command {
      public function handle(OrderService $orderService) {
          $orders = $orderService->getOrders(['status' => 'pending']);
          foreach ($orders as $order) {
              $this->processOrder($order);
          }
      }
  }
  

• Schedule:

  // app/Console/Kernel.php
  protected function schedule(Schedule $schedule) {
      $schedule->command('fetch:fourtochki-orders')->hourly();
  }
  

2. Webhook Handling

• Pattern: Extend the bundle’s webhook logic or replace it with Laravel middleware.
• Example Middleware:

  // app/Http/Middleware/ValidateFourTochkiWebhook.php
  public function handle($request, Closure $next) {
      $payload = $request->getContent();
      $signature = $request->header('X-FourTochki-Signature');
  
      if (!$this->validateSignature($payload, $signature)) {
          abort(403);
      }
      return $next($request);
  }
  

• Route:

  Route::post('/4tochki/webhook', [FourTochkiWebhookController::class, 'handle'])
       ->middleware('validate.fourtochki-webhook');
  

3. Inventory Sync

• Pattern: Use InventoryService to update stock levels.
• Example:

  use BaksDev\FourTochkiOrders\Service\InventoryService;
  
  public function syncInventory(InventoryService $inventoryService) {
      $products = $inventoryService->getProducts();
      foreach ($products as $product) {
          Product::where('sku', $product->getSku())
                ->update(['stock' => $product->getQuantity()]);
      }
  }
  

Integration Tips

Laravel-Symfony Bridge

• Service Container: Resolve Symfony services via Laravel’s container:

  $container = app()->make('BaksDev\FourTochkiOrders\FourTochkiOrdersBundle')->getContainer();
  $orderService = $container->get('baks_fourtochki.order_service');
  

• Event Dispatcher: Replace Symfony events with Laravel events:

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

Doctrine ↔ Eloquent

• Option 1: Use laravel-doctrine/bridge to share entities.
• Option 2: Manually map Doctrine entities to Eloquent models:

  class FourTochkiOrder extends Model {
      protected $casts = [
          'created_at' => 'datetime',
          'updated_at' => 'datetime',
      ];
  
      public static function fromDoctrineEntity(\BaksDev\FourTochkiOrders\Entity\Order $entity) {
          return self::create([
              'id' => $entity->getId(),
              'total' => $entity->getTotal(),
              // ...
          ]);
      }
  }
  

CLI Commands

• Replace Symfony commands with Laravel Artisan commands:

  // app/Console/Commands/InstallFourTochkiAssets.php
  use Illuminate\Console\Command;
  
  class InstallFourTochkiAssets extends Command {
      public function handle() {
          $this->copyAssets();
          $this->publishConfig();
      }
  
      protected function copyAssets() {
          $this->files->copyDirectory(
              __DIR__.'/../../vendor/baks-dev/four-tochki-orders/resources/assets',
              public_path('4tochki')
          );
      }
  }
  

Gotchas and Tips

Pitfalls

1. Doctrine vs. Eloquent Conflicts

   • Issue: The bundle uses Doctrine ORM, which may conflict with Laravel’s Eloquent.
   • Fix: Isolate Doctrine to a single namespace or use a bridge like laravel-doctrine/orm.
   • Workaround: Create a hybrid model:

     class FourTochkiOrder extends \Doctrine\ORM\Mapping\Entity {
         // Doctrine entity
     }
     
     class LaravelFourTochkiOrder extends Model {
         public static function fromDoctrine(FourTochkiOrder $entity) {
             return self::create([
                 'id' => $entity->getId(),
                 // ...
             ]);
         }
     }
     

2. Symfony-Specific Assumptions

   • Issue: The bundle assumes Symfony’s Container, EventDispatcher, and Console components.
   • Fix: Wrap Symfony services in Laravel-compatible classes:

     class LaravelOrderService {
         public function __construct(private OrderService $symfonyService) {}
     
         public function getOrders(array $filters) {
             return $this->symfonyService->getOrders($filters);
         }
     }
     

3. Webhook Signature Validation

   • Issue: The bundle’s webhook validation may not align with Laravel’s security practices.
   • Fix: Implement HMAC validation manually:

     public function validateWebhook($payload, $signature) {
         $expected = hash_hmac('sha256', $payload, env('FOURTOCHKI_WEBHOOK_SECRET'));
         return hash_equals($expected, $signature);
     }
     

4. Migration Conflicts

   • Issue: Doctrine migrations may not work with Laravel’s schema builder.
   • Fix: Run Doctrine migrations separately:

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

   • Tip: Use transactions to avoid partial migrations:

     DB::transaction(function () {
         // Run Laravel migrations
         Schema::create('laravel_orders', function (Blueprint $table) { ... });
         // Run Doctrine migrations (if needed)
     });
     

5. PHP 8.4+ Requirements

   • Issue: The bundle requires PHP 8.4, which may conflict with Laravel’s PHP version.
   • Fix: Upgrade Laravel or fork the bundle to drop PHP 8.4 features:

     composer require php:^8.4
     

Debugging Tips

1. Enable Bundle Debugging Add to config/four_tochki_orders.php:

   'debug' => env('APP_DEBUG', false),
   

   • This may expose Symfony’s debug output in Laravel’s logs.

2. Log Symfony Events Subscribe to Symfony events in Laravel:

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   public