Import & Export Engine
Relevant source files
The following files were used as context for generating this wiki page:
- src/Adapter/Import/CommandHandler/StartImportJobHandler.php
- src/PrestaShopBundle/Resources/config/services/core/import_engine.yml
- tests/Integration/Behaviour/Features/Context/Domain/Import/ImportJobFeatureContext.php
- src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php
- tests/UI/campaigns/functional/BO/08_design/01_themeAndLogo/01_themeAndLogo/01_addNewTheme.ts
The Import & Export Engine provides a structured framework for migrating data into and out of the PrestaShop environment. It manages the lifecycle of import jobs, validates incoming data, and handles file normalization to ensure data integrity across different entity types such as products, categories, and manufacturers. The engine utilizes a CQRS (Command Query Responsibility Segregation) pattern to separate the execution of import actions from state retrieval.
Sources: src/Adapter/Import/CommandHandler/StartImportJobHandler.php, tests/Integration/Behaviour/Features/Context/Domain/Import/ImportJobFeatureContext.php:33-40
Import Job Lifecycle
An import job proceeds through several states, starting from initialization to terminal completion or cancellation. The system utilizes a handler to validate the initial command, check for registered importers, and prepare the working environment.
Initialization and Validation
The StartImportJobHandler performs preliminary checks before a job entity is persisted. It ensures:
- A specific importer exists for the requested entity type.
- The shop scope is valid (currently restricted to a single shop).
- The requested language is installed.
- The source file is readable and located within allowed directories.
- The file contains at least one data record after normalization.
Sources: src/Adapter/Import/CommandHandler/StartImportJobHandler.php:49-92
Job Execution Flow
The following sequence diagram illustrates the process of starting an import job:
The diagram shows the validation and normalization steps required to successfully persist a new import job.
Sources: src/Adapter/Import/CommandHandler/StartImportJobHandler.php:49-110
Core Components
The engine is composed of several specialized services defined in the container configuration.
Services and Responsibilities
| Service | Responsibility |
|---|---|
EntityImporterRegistry | Manages the collection of all available entity-specific importers. |
CsvImportFileNormalizer | Transforms various CSV formats into a canonical dialect for internal processing. |
FileDownloader | Manages local and remote file retrieval, restricted to specific allowed directories. |
ImportJobPurger | Removes expired import jobs and their associated temporary working files. |
ProductRowImporter | Orchestrates the multi-step import process for product entities using prioritized steps. |
Sources: src/PrestaShopBundle/Resources/config/services/core/import_engine.yml:18-70
Product Import Steps
Product imports are processed through a series of prioritized steps. Each step handles a specific aspect of the product entity.
| Step Class | Priority | Function |
|---|---|---|
ProductTypeStep | 1300 | Determines if the product is standard, pack, or virtual. |
ProductFieldsStep | 1200 | Maps basic data fields (name, description, price). |
StockStep | 1100 | Updates inventory levels. |
CategoriesStep | 1000 | Associates products with category trees. |
ImagesStep | 600 | Processes and attaches image files. |
ShopsStep | 200 | Propagates product data to specific shop contexts. |
DateAddStep | 100 | Finalizes the record with creation timestamps. |
Sources: src/PrestaShopBundle/Resources/config/services/core/import_engine.yml:83-125
File Management and Security
The engine enforces strict path security to prevent unauthorized file access.
Allowed Directories
Local file paths for imports are confined to specific "content" directories. The FileDownloader uses the following roots:
%prestashop.admin_dir%/import_PS_UPLOAD_DIR__PS_IMG_DIR__PS_DOWNLOAD_DIR_
Sources: src/PrestaShopBundle/Resources/config/services/core/import_engine.yml:25-30
File Normalization
The CsvImportFileNormalizer converts source files into working files located in a work/ subdirectory within the import directory. These working files use a unique UUID based on the job reference to avoid collisions. Working files are excluded from being used as source files for new jobs to prevent recursive deletion or normalization errors.
Sources: src/Adapter/Import/CommandHandler/StartImportJobHandler.php:177-187, tests/Integration/Behaviour/Features/Context/Domain/Import/ImportJobFeatureContext.php:477-485
Theme and Design Import
Beyond entity data, the engine supports importing themes and logo assets via the Back Office.
This flowchart represents the high-level logic for theme ingestion as tested in the UI suite.
Sources: tests/UI/campaigns/functional/BO/08_design/01_themeAndLogo/01_themeAndLogo/01_addNewTheme.ts:54-125
Error Handling
The engine throws specific exceptions when conditions are not met. CannotStartImportJobException includes codes for:
UNKNOWN_ENTITY_TYPE: No importer registered.EMPTY_SHOP_SCOPE: The shop constraint resolves to no shops.SOURCE_FILE_NOT_FOUND: The path provided does not exist.SOURCE_FILE_OUT_OF_BOUNDS: The file is outside allowed roots or is an existing working file.UNSUPPORTED_TRUNCATE: The importer does not support deleting existing data before import.
Sources: src/Adapter/Import/CommandHandler/StartImportJobHandler.php:49-70, tests/Integration/Behaviour/Features/Context/Domain/Import/ImportJobFeatureContext.php:403-415
Summary
The Import & Export Engine is a robust, modular system that leverages Symfony services and CQRS to handle data migration. By separating the normalization of files from the actual entity persistence, it allows for extensible multi-step processing (especially for products) while maintaining strict security via directory confinement and file ownership checks.