Aventux
Docs
/

Developer Documentation

Architecture Overview

The AventDropshippingSuite follows a modular, event-driven architecture designed for extensibility. The Core plugin provides the data model, interfaces, events, and a reusable CSV mapping engine. Paid extension plugins decorate core services and listen to events.

Core Plugin (Free)
+-- Entities (Supplier, SupplierProduct, DropshipOrder, MappingProfile)
+-- Interfaces (Strategy, Notification, Processor, Import)
+-- Events (Created, StatusChanged, SupplierSelected, Cancelled, Notification)
+-- Services (Selection, OrderProcessing, CSV Mapping Engine)
+-- Admin UI (Supplier CRUD, CSV Components, Product/Order Tabs)

Extensions (Paid) - decorate interfaces and listen to events

Entity Overview

avent_supplier (with Translation)

The main supplier entity with translatable fields (name, description, customFields).

use Avent\DropshippingSuite\Core\Content\Dropshipping\Supplier\SupplierDefinition;
use Avent\DropshippingSuite\Core\Content\Dropshipping\Supplier\SupplierEntity;

// Access via repository
$supplier = $this->supplierRepository->search($criteria, $context)->first();
$supplier->getName();        // Translated name
$supplier->getEmail();       // Contact email
$supplier->getPriority();    // Selection priority (lower = higher)
$supplier->isActive();       // Active flag

avent_supplier_product (M:N with Priority)

Links products to suppliers with additional business data.

use Avent\DropshippingSuite\Core\Content\Dropshipping\SupplierProduct\SupplierProductDefinition;

// Fields: supplierId, productId, productVersionId, supplierSku, priority, purchasePrice, currencyId, active

avent_dropship_order

Tracks dropship order line items per supplier.

use Avent\DropshippingSuite\Core\Content\Dropshipping\DropshipOrder\DropshipOrderEntity;

// Status constants:
DropshipOrderEntity::STATUS_PENDING          // 'pending'
DropshipOrderEntity::STATUS_SENT_TO_SUPPLIER // 'sent_to_supplier'
DropshipOrderEntity::STATUS_CONFIRMED        // 'confirmed'
DropshipOrderEntity::STATUS_SHIPPED          // 'shipped'
DropshipOrderEntity::STATUS_DELIVERED        // 'delivered'
DropshipOrderEntity::STATUS_CANCELLED        // 'cancelled'

avent_mapping_profile

Stores CSV mapping configurations with field mappings, transformations, and schedule configs.

// Types: 'product_import', 'stock_import', 'order_export'
// Config: delimiter, encoding, headerLine
// fieldMapping: [{source: 'CSV Column', target: 'entity_field'}, ...]
// validationRules: [{field: 'name', rule: 'required'}, ...]
// scheduleConfig: {active: true, sourceType: 'url', sourcePath: 'https://...'}

Interfaces

All interfaces are in Avent\DropshippingSuite\Interface\.

SupplierSelectionStrategyInterface

interface SupplierSelectionStrategyInterface
{
    public function selectSupplier(string $productId, Context $context): ?SupplierEntity;
}

Default implementation: SupplierSelectionService - selects by lowest priority number from active supplier-product mappings.

DropshipOrderProcessorInterface

interface DropshipOrderProcessorInterface
{
    /** @return array<DropshipOrderEntity> */
    public function process(OrderEntity $order, Context $context): array;
}

Default implementation: DropshipOrderService - iterates order line items, selects suppliers, creates DropshipOrder entries.

SupplierNotificationInterface

interface SupplierNotificationInterface
{
    public function notify(SupplierEntity $supplier, DropshipOrderEntity $dropshipOrder, Context $context): void;
}

No default implementation in Core - designed for extension plugins (e.g., AutoOrder).

SupplierImportInterface

interface SupplierImportInterface
{
    public function import(array $data, Context $context): void;
}

No default implementation in Core - designed for extension plugins (e.g., SupplierConnect).

Events

All events are in Avent\DropshippingSuite\Event\.

DropshipOrderCreatedEvent

Dispatched after a new DropshipOrder is created.

use Avent\DropshippingSuite\Event\DropshipOrderCreatedEvent;

public static function getSubscribedEvents(): array
{
    return [
        DropshipOrderCreatedEvent::class => 'onDropshipOrderCreated',
    ];
}

public function onDropshipOrderCreated(DropshipOrderCreatedEvent $event): void
{
    $dropshipOrder = $event->getDropshipOrder();
    $context = $event->getContext();
}

DropshipOrderStatusChangedEvent

Dispatched when a DropshipOrder status changes.

public function onStatusChanged(DropshipOrderStatusChangedEvent $event): void
{
    $previousStatus = $event->getPreviousStatus();
    $newStatus = $event->getNewStatus();
    $dropshipOrder = $event->getDropshipOrder();
}

SupplierSelectedEvent

Dispatched during supplier selection. Mutable - extensions can override the selected supplier.

public function onSupplierSelected(SupplierSelectedEvent $event): void
{
    $productId = $event->getProductId();
    $orderId = $event->getOrderId();

    // Override supplier selection
    $event->setSupplier($myPreferredSupplier);
}

DropshipOrderCancelledEvent

Convenience event dispatched when status changes to 'cancelled'.

BeforeSupplierNotificationEvent / AfterSupplierNotificationEvent

Dispatched before/after supplier notification. Before event has mutable payload.

public function onBeforeNotification(BeforeSupplierNotificationEvent $event): void
{
    $payload = $event->getPayload();
    $payload['customField'] = 'value';
    $event->setPayload($payload);
}

Service Registration

All services are registered in Resources/config/services/service.xml. Key service IDs:

Service Interface
Avent\DropshippingSuite\Service\SupplierSelectionService SupplierSelectionStrategyInterface
Avent\DropshippingSuite\Service\DropshipOrderService DropshipOrderProcessorInterface
Avent\DropshippingSuite\Service\SupplierProductService (direct)
Avent\DropshippingSuite\Service\CsvMapping\CsvParserService (direct)
Avent\DropshippingSuite\Service\CsvMapping\MappingProfileService (direct)
Avent\DropshippingSuite\Service\CsvMapping\TransformationService (direct)
Avent\DropshippingSuite\Service\CsvMapping\ValidationService (direct)
Avent\DropshippingSuite\Service\CsvMapping\DeltaImportService (direct)
Avent\DropshippingSuite\Service\CsvMapping\RollbackService (direct)
Avent\DropshippingSuite\Service\CsvMapping\ScheduledImportService (direct)

CSV Mapping Engine

CsvParserService

$parser = $container->get(CsvParserService::class);

// Parse CSV content with auto-detection
$result = $parser->parse($csvContent);
// Returns: ['headers' => [...], 'rows' => [...], 'delimiter' => ',', 'encoding' => 'UTF-8']

// Parse with explicit settings
$result = $parser->parse($csvContent, ';', 'ISO-8859-1', 1);

TransformationService

$transformer = $container->get(TransformationService::class);

$transformations = [
    ['field' => 'price', 'type' => 'multiply', 'config' => ['factor' => 1.19]],
    ['field' => 'name', 'type' => 'trim', 'config' => []],
    ['field' => 'sku', 'type' => 'prefix', 'config' => ['prefix' => 'SUP-']],
];

$transformedRows = $transformer->applyTransformations($rows, $transformations);

Available transformation types:

  • multiply - Multiply numeric value (config: factor, decimals)
  • date_format - Convert date format (config: inputFormat, outputFormat)
  • regex_replace - Regex replacement (config: pattern, replacement)
  • default_value - Set default for empty values (config: value)
  • trim - Trim whitespace
  • uppercase / lowercase - Case conversion
  • number_format - Number formatting (config: decimals, decimalPoint, thousandsSeparator)
  • prefix / suffix - Add prefix/suffix (config: prefix/suffix)
  • map_value - Map values via lookup table (config: mapping, default)

ValidationService

$validator = $container->get(ValidationService::class);

$rules = [
    ['field' => 'name', 'rule' => 'required'],
    ['field' => 'price', 'rule' => 'numeric'],
    ['field' => 'stock', 'rule' => 'min', 'config' => ['value' => 0]],
    ['field' => 'email', 'rule' => 'email'],
];

$result = $validator->validate($rows, $rules);
// Returns: ['valid' => [...], 'errors' => [{row: 1, field: 'name', rule: 'required', message: '...'}]]

Available validation rules:

  • required - Field must not be empty
  • numeric - Must be numeric
  • integer - Must be integer
  • min / max - Numeric range (config: value)
  • min_length / max_length - String length (config: value)
  • email - Valid email format
  • url - Valid URL format
  • regex - Match regex pattern (config: pattern, message)
  • in - Value must be in list (config: values)

Admin Components

Reusable CSV Mapping Components

These Vue components can be reused by extension plugins:

Component Purpose
avent-csv-upload File upload with drag & drop
avent-csv-column-mapper Source-to-target column mapping
avent-csv-preview Preview mapped data (first 20 rows)
avent-csv-transformer Configure field transformations
avent-csv-profile-manager Save/load mapping profiles

Usage in extension plugins:

<avent-csv-upload @file-loaded="onFileLoaded" />

<avent-csv-column-mapper
    :source-columns="csvHeaders"
    :target-fields="targetFields"
    :mapping="currentMapping"
    @mapping-changed="onMappingChanged"
/>

<avent-csv-preview
    :rows="csvRows"
    :mapping="currentMapping"
/>

Directory Structure

AventDropshippingSuite/
+-- composer.json
+-- src/
    +-- AventDropshippingSuite.php           # Plugin class with uninstall
    +-- Core/Content/Dropshipping/
    |   +-- Supplier/                        # Entity with Translation
    |   +-- SupplierProduct/                 # M:N Mapping
    |   +-- DropshipOrder/                   # Order tracking
    |   +-- MappingProfile/                  # CSV profiles
    +-- Event/                               # All events
    +-- Interface/                           # All interfaces
    +-- Service/
    |   +-- SupplierSelectionService.php
    |   +-- DropshipOrderService.php
    |   +-- SupplierProductService.php
    |   +-- CsvMapping/                      # CSV engine services
    +-- Subscriber/
    |   +-- OrderPlacedSubscriber.php
    +-- ScheduledTask/                       # Scheduled import task
    +-- Migration/                           # Database migration
    +-- Resources/
        +-- config/
        |   +-- config.xml                   # Plugin settings
        |   +-- services.xml                 # Main service config
        |   +-- services/                    # Modular service definitions
        +-- app/administration/src/
            +-- main.js
            +-- module/
                +-- avent-dropshipping-supplier/    # Supplier CRUD
                +-- avent-dropshipping-csv-mapper/  # CSV components
                +-- sw-product/                     # Product tab extension
                +-- sw-order/                       # Order tab extension