README

产品经理

简要信息

此扩展旨在使从不同来源导入产品和产品数据更加容易。

默认情况下，它支持从CSV和Excel文件导入。

!!! 如果要使用Excel源，请额外安装composer包 composer req phpoffice/phpspreadsheet

导入配置由Yaml提供。

示例配置和源文件

您可以在以下文件夹中找到导入配置和源数据结构的示例：

• Yaml配置文件 EXT:pxa_pm_importer/Configuration/Example/Yaml/
• 源数据文件 EXT:pxa_pm_importer/Resources/Private/ExampleData/

用法

如何创建导入配置

创建新的扩展，例如 "pm_myimport"。

在ext_tables.php中添加以下代码

// Register importer
\Pixelant\PxaPmImporter\Utility\ImportersRegistry::registerImporter('pm_myimport');

这将注册您的扩展为导入配置提供者。

默认情况下，扩展将在以下位置查找配置文件：

EXT:pm_myimport/Configuration/Yaml

但您可以通过第二个参数添加一个自定义路径数组，以获取YAML文件，但应位于Configuration文件夹下。

然后在您的导入配置文件中，您可以使用自己的导入器、源提供者、数据适配器和处理器。

日志

每次导入执行都会保存在单独的日志文件中。默认情况下，所有日志文件都保存在typo3temp/var/logs中，文件前缀为pm_importer_YYYY_mm_dd_hours:minutes:seconds.log。您可以在导入配置中更改日志路径。

后端模块

创建导入配置后，您可以从后端模块“PM导入器”中运行它。

计划任务

要从计划任务运行导入，请创建新的执行控制台命令任务。从可用命令中选择pxapmimporter:import: 导入“pxa_product_manager”扩展相关的记录。任务接受以下参数：

• 配置：运行配置文件的逗号分隔路径列表。例如：“EXT:pxa_pm_importer/Configuration/Example/Yaml/AttributesCsvSample.yaml”
• adminEmails：通知导入错误 - 通知提供的电子邮件关于导入错误
• senderEmail：发送者电子邮件 - 如果设置了通知电子邮件，则发送者电子邮件

简单导入

如果您想从CSV或Excel文件导入数据，并且数据不是特别复杂，扩展的可能性应该足够。

如果您只想运行一些自定义配置，但不想为此创建扩展，您可以从命令行执行此操作。

./vendor/bin/typo3cms pxapmimporter:import PATH_TO_CONFIGURATION_FILE

导入yaml配置

您可以在“fileadmin”中的某个位置创建包含导入配置的新Yaml配置文件。

示例

log:
  # Custom log path
  path: 'fileadmin/import/log/product_import.log'
  # Only track errors
  # severity: 3 
sources:
  SourceClass:
    # Different source settings
importers:
  ImporterName:
    # Override default importer class
    #importer: Class_Name
    # Unique identifier field provided by Adapter
    identifierField: 'id'

    # Domain model name
    domainModel: Pixelant\PxaProductManager\Domain\Model\Attribute

    # Allowed import operations
    # default is 'create,update,localize,createLocalize'
    allowedOperations: 'create,update'

    # Settings for new records
    importNewRecords:
      # Storage of new records
      pid: 22

    # Storage of records. Import will check storage for records
    storage:
      # Comma-separated list of folders
      pid: 22
      # Recursive level
      recursive: 0

    # Layer between raw data and importer
    adapter:
      className: 'AdapterDataClass'
      # Any additional settings
      settings:
        dummy: true
      mapping:
        # Import unique identifier for all fields
        id: 0
        excelColumns: false
        # Per language
        languages:
          0:
            # Field name to column number from raw data, 0 is first
            title: 1
            parent: 2
          1:
            title: 3
            parent: 4
    
    # Validation settings
    validation:
      name:
        - required
    
    # Mapping fields, data adapter should return array with associative array
    mapping:
      title:
        # Property name is necessary only if it differ from field name
        property: 'title'
        processor: 'Pixelant\PxaPmImporter\Processors\StringProcessor'
      parent:
        processor: 'Pixelant\PxaPmImporter\Processors\Relation\CategoryProcessor'

配置部分

日志

在日志设置中，可以设置自定义路径以写入文件日志和严重性。

源代码

源负责从不同的源读取数据。目前扩展支持两种导入源：

!!! 可以有多达多个源。脚本将为每个源运行导入。

• Pixelant\PxaPmImporter\Service\Source\CsvSource
• Pixelant\PxaPmImporter\Service\Source\ExcelSource

CsvSource支持以下选项

skipRows: 1 # Skip number of top rows
delimiter: , # CSV Delimiter
filePath: 'file.csv' #path to file

ExcelSource支持以下选项

skipRows: 1 # Skip number of top rows
sheet: -1 # Sheet number, starts from 0, -1 - active sheet
filePath: 'file.csv' #path to file

导入适配器

每个导入器都需要适配器。适配器应将源中的原始数据转换为关联数组。

此外，如果存在语言层，适配器还需要为语言层准备数据。

默认情况下，扩展程序具有Pixelant\PxaPmImporter\Adapter\DefaultDataAdapter。

适配器需要映射配置。:

# Adapter settings
settings:
  dummy: 123
mapping:
  # tells in which column unique identifier is
  id: 'A'
  # Each language UID has field mapping array, where field name => to column number or letter
  # Set this if excel columns instead of numbers is used
  excelColumns: true
  languages:
    0:
      # Field name to column number from raw data, 0 is first
      title: 1
    1:
      # Or field name to column letter like in excel
      title: 'D'

重要：如果您使用Excel列字母作为列而不是数字，请设置“excelColumns: true”。一个适配器配置只能使用数字或字母。

使用多个列来生成标识符。:

以下配置将标识符设置为'1100101023se1'，如果ITEMID列是'1100101023'且DATAAREAID是'se1'，则在源中没有单个字段可以作为唯一标识符时很有用。

# Adapter settings
mapping:
  # combine these columns for record identifier
  id:
    0: 'ITEMID'
    1: 'DATAAREAID'
  languages:
    0:
      title: 'ITEMNAME'

使用适配器过滤器过滤行。:

示例用法：我有一个包含所有需要导入产品的单个API源，但它们是每种语言一行，并且它们应该存储在不同的PID中。我还需要过滤出PROJCATEGORYID不等于'BE Online'且CAP_CustUniqueItem等于'1'的行。

# Adapter settings
mapping:
  # combine these columns for record identifier
  id:
    0: 'ITEMID'
    1: 'DATAAREAID'
  languages:
    0:
      title: 'ITEMNAME'
filters:
  # only include rows when column "PROJCATEGORYID" has string value "BE Online"
  PROJCATEGORYID:
    filter: 'Pixelant\PxaPmImporter\Adapter\Filters\StringEqualsFilter'
    value: 'BE Online'
  # AND only include rows when column "DATAAREAID" has string value "SE1"
  DATAAREAID:
    filter: 'Pixelant\PxaPmImporter\Adapter\Filters\StringEqualsFilter'
    value: 'SE1'
  # AND only include rows when column "CAP_CustUniqueItem" has string value "0"
  CAP_CustUniqueItem:
    filter: 'Pixelant\PxaPmImporter\Adapter\Filters\StringEqualsFilter'
    value: '0'

导入器配置

# Override default importer class
#importer: Class_Name
# Field name with unique identifier from data adapter
identifierField: 'id'

# Domain model name
# Target import model
domainModel: Pixelant\PxaProductManager\Domain\Model\Attribute

# Allowed import operations. UPDATE is allowed by default
# default is 'create,update,localize,createLocalize'
# 'create' - Allow to create new records
# 'localize' - Allow to localize records
# 'createLocalize' - Allow to create localize records without default language record
allowedOperations: 'create'

# Settings for new records
importNewRecords:
  # Storage of new records
  pid: 22

# Storage of records. Import will check storage for records
storage:
  # Comma-separated list of folders
  pid: 22
  # Recursive level
  recursive: 0

# Validation settings
# Only required is supported so far. But you can implement more
# Add custom class name here
# If just a name is provided extension will try to load it from validators folder
validation:
  title:
    - required

# Mapping fields, data adapter should return array with associative array
mapping:
  # Field to Extbase property model mapping rules. Support next settings:
  title:
    # Extbase property name. Set this in case property name differs from field name
    property: 'title'
    # Custom field processor. If set processor take care of setting model property value, otherwise value will be set as simple string without any processing.
    processor: 'Pixelant\PxaPmImporter\Processors\StringProcessor'
    # Any other options will be passed as configuration array to processor
    customSetting: true
    anotherSettingValue: 123321

处理器

处理器的作用是将数据（字段值）转换为可以设置为模型属性的方式。处理器负责将值设置到属性中。

扩展程序自带以下处理器

简单属性处理器

• Pixelant\PxaPmImporter\Processors\BooleanProcessor - 布尔值。无参数。
• Pixelant\PxaPmImporter\Processors\FloatProcessor - 浮点值。无参数。
• Pixelant\PxaPmImporter\Processors\IntegerProcessor - 整数值。无参数。
• Pixelant\PxaPmImporter\Processors\StringProcessor - 字符串值。无参数。
• Pixelant\PxaPmImporter\Processors\ProductAttributeProcessor - 设置产品属性的值。
• Pixelant\PxaPmImporter\Processors\SlugProcessor - 更新URL的slug字段。
• Pixelant\PxaPmImporter\Processors\DateTimeProcessor - DateTime值。

######配置示例

• 简单

# Field to Extbase property model mapping rules. Support next settings:
title:
  # Extbase property name. Set this in case property name differs from field name
  property: 'title'
  # Custom field processor. If set processor take care of setting model property value, otherwise value will be set as simple string without any processing.
  processor: 'Pixelant\PxaPmImporter\Processors\StringProcessor'

• DateTimeProcessor

date:
  processor: 'Pixelant\PxaPmImporter\Processors\DateTimeProcessor'
  # Input format, the format to use when creating a DateTime object from value (DateTime::createFromFormat)
  inputFormat: 'd/m/Y h:i:s'
  # Output format, the format to store data in entity
  outputFormat: 'U'

• SlugProcessor

slug:
  processor: 'Pixelant\PxaPmImporter\Processors\SlugProcessor'
  # If DB field name doesn't match property name you need to provide DB field name in order to be able to update record
  fieldName: 'pxapm_slug'
  # Set to true in case your import source already has slug value for import and generation is not needed.
  # Otherwise(by default false) script will generate value using TCA configuration
  useImportValue: true

• ProductAttributeProcessor

color:
  processor: 'Pixelant\PxaPmImporter\Processors\ProductAttributeProcessor'
  # UID of attribute or import ID
  attributeUid: 11
  # You can set this to true if "attributeUid" above has import identifier value.
  # This means that attribute was previously imported and you want to find it by this import identifier
  treatAttributeUidAsImportUid: false
  # Optional, date format for \DateTime::createFromFormat. Parse date for date attribute type.
  dateFormat: 'Y-m-d'

关系（1:1，1:n，n:m）处理器

• Pixelant\PxaPmImporter\Processors\Relation\AttributeOptionsProcessor - 将字段值（例如，'Red,Blue,Green'）转换为属性选项并将其附加到属性上。仅用于属性导入。
• Pixelant\PxaPmImporter\Processors\Relation\CategoryProcessor - 将字段值（如'Food,Car'）转换为类别并将其附加到对象上。
• Pixelant\PxaPmImporter\Processors\Relation\RelatedProductsProcessor - 将产品标识符转换为产品并将其附加到对象上。

######配置示例

relatedProducts:
  processor: 'Pixelant\PxaPmImporter\Processors\Relation\RelatedProductsProcessor'
  # If values are comma-separated UIDs from DB instead of import IDs
  treatIdentifierAsUid: 1
subProducts:
  processor: 'Pixelant\PxaPmImporter\Processors\Relation\RelatedProductsProcessor'
  # If one of the related products was not found and you want to ignore this error
  disableExceptionOnFailInitEntity: true

文件处理器

• Pixelant\PxaPmImporter\Processors\Relation\Files\LocalFileProcessor - 通过名称附加文件。

######配置示例

images:
  processor: 'Pixelant\PxaPmImporter\Processors\Relation\Files\LocalFileProcessor'
  # Relative folder path where file can be found. Skip "fileadmin" for default storage.
  folder: 'import_files'
  # Optional storage UID, 1 - default.
  storageUid: 1

处理器验证

每个属性可能有多个验证器。自定义验证器应实现\Pixelant\PxaPmImporter\Validation\Validator\ValidatorInterface的实例。例如，请参阅RequiredValidator。

validation:
  title:
    - required
    # Or provide custom validator
    - Pixelant\MyExtension\Domain\Validation\Validator\CustomValidator

重要：您的自定义类应实现所需的接口。

• 适配器实现Pixelant\PxaPmImporter\Adapter\AdapterInterface。
• 处理器实现Pixelant\PxaPmImporter\Processors\FieldProcessorInterface。
  • Pixelant\PxaPmImporter\Processors\Relation\AbstractRelationFieldProcessor有助于处理1:1、1:n和n:m的关系。
  • Pixelant\PxaPmImporter\Processors\AbstractFieldProcessor是用于处理简单值（如字符串和数字）的基本类。
• 源实现Pixelant\PxaPmImporter\Source\SourceInterface。
• 导入器实现Pixelant\PxaPmImporter\Importer\ImporterInterface。
  • Pixelant\PxaPmImporter\Importer\Importer - 产品、类别和属性导入的基本类。

在YAML中导入

如果您有一个通用配置，例如产品导入映射，用于所有导入，并且希望将其放在一个地方，您可以在“Configuration/Yaml”内部创建一个子文件夹，例如“imports”。

EXT:pm_myimport/Configuration/Yaml/imports

在此处创建“general_conf.yaml”YAML文件，并将配置放在其中。然后，在您的导入文件中，您可以像下面这样导入

# imports/general_conf.yaml
imports:
    - { resource: imports/general_conf.yaml }

开发者有用信息

在导入过程中，Singleton \Pixelant\PxaPmImporter\Context\ImportContext可用，与导入数据相关。请参阅类以获取更多详细信息。