README

这是一个为YII 2提供的通用模块，它可以将用户文件（csv、xml、xls、xlsx、txt）解析并写入数据库，具有灵活的设置。

##要求##

Multiparser库有以下要求

yiisoft/yii2

##文档##

###1. 概述。### 模块允许读取选定文件的包含内容到数组，并在屏幕上显示以供进一步写入数据库。用户必须选择在表单中对应列，以及需要加载数据的位置（可选）。解析器支持读取csv、xml、xls、xlsx、txt文件。对于每种扩展名，可以指定各自的解析规则（见第4点）。对于每个数据接收器（例如一个或多个数据库表），在设置中指定一个自己的类（writer）。对于每个接收器，将单独的脚本定义为读取和写入数据规则。###2. 模块安装。### 包含一个展开的模块示例。为了了解模块的功能（并进一步使用它），建议使用内部示例。在安装包后，将项目中的examples/modules文件夹复制到common文件夹中（对于高级应用程序），并在配置文件中注册模块。

...
 'modules' => [
        'parser' => [
            'class' => 'common\modules\parser\Module',
        ],
    ],
 ...

为了使示例正常工作，需要应用在examples/migration中描述的迁移。在此示例中，接收器是一个简单的表。在实际项目中，接收器可以是任何存储系统。对于该来源，描述了记录数据的最简单机制 - examples\modules\parser\components\DetailsWriter.php。所有脚本都在文件中定义 - examples\modules\parser\scenarios_config.php。对于上述示例，脚本文件如下所示

<?php
return [
    'details' =>
        ['parser_config' =>
            [   'csv' =>
                ['class' => 'yii\multiparser\CsvParser',
                    'converter_conf' => [
                        'class' => 'yii\multiparser\Converter',
                        'configuration' => ['encode' => []],
                    ],
                ],

                'xls' =>
                    ['class' => 'yii\multiparser\XlsParser',
                        'converter_conf' => [
                            'class' => 'yii\multiparser\Converter',
                            'configuration' => ['encode' => []],
                        ],
                    ],
            ],

            'basic_columns' => [
                Null => 'null',
                'name' => 'Название',
                'article' => 'Артикул',
                'price' => 'Цена',
                'brand' => 'Производитель',
                'count' => 'Количество',
            ],

            'require_columns' => [
                'article',
                'brand',
            ],

            'writer' => 'common\modules\parser\components\DetailsWriter',
            'title' => 'Загрузка товаров',
        ],

];

在数组的第一层指定场景。在此示例中，我们有一个场景 - details。接下来是读取和写入数据参数，以下将描述。

###3. 数据写入设置。### 'basic_columns' - 用户选择的列，将显示给用户以便他们选择对应项。此数组的关键必须是接收器的字段。'require_columns' - 必要字段。验证器将检查至少这些字段的对应项。'writer' - 实现数据写入数据库的类。为了简化数据写入操作，包中包含了一个抽象类Writer，它已经包含了许多写入和验证功能。此外，MassiveDataSQLBuilder是一个包含直接在MySQL数据库中插入和更新大量数据功能的类。可以通过以下方式将此类连接到Active Record模型：

 public function behaviors()
    {
        return [

            'SQLBuilder' => [
                'class' => MassiveDataSQLBuilder::className(),
                'batch' => 500, // размер пакета вставляемых данных
                'keys' =>  [ // поля которые являются клчевыми - если они дублируются до данные - обновляются а не записываются
                    'article',
                    'brand',
                ],
            ]
        ];
    }

###4. 读取（解析）文件设置###

'parser_config' 是描述多维度解析数据设置的数组。

4.1. 数组的第一级指定了组件将与之工作的文件扩展名。对于每个扩展名，定义了一个该类型文件的解析设置数组。包支持为一种文件类型定义多个场景（多个并行设置）。

4.2. 在此级别可以定义对于该扩展名可用的参数。

在示例中使用此功能来定义与标准列对应的解析列的选择列（参数 - basic_column）。可以通过以下方式调用此参数：```php Yii::$app->multiparser->getConfiguration($file_extension, 'basic_column'); ```

4.3. 第二级指定解析器的设置，以YII配置数组的形式。

该数组有一个必需元素，键为 – class，其中指定了将处理该文件类型的解析器名称。因此，可以指定自己的解析器类，或使用包中包含的类，例如对于csv，类为 - `yii\multiparser\CsvParser`。在使用内置类（或继承自它的类）时，可以在该数组中设置以下属性作为配置

4.3.1. `converter_conf – array`。转换器配置。详细信息请参见第5点。

4.3.2. `keys – array`。在此参数中可以为文件列指定名称。例如

        ```php
        'keys' => [
            0 => 'Description',
            1 => 'Article',
            2 => 'Price',
            3 => 'Brand',
            4 => 'Count',
        ]
        ```

在这种情况下，结果数组将是关联的，其中数组列的键为 `'Brand'` 将包含文件的第四列的值。

4.3.3. `has_header_row – boolean`。标志，文件是否在第一行有标题，如果为true，则第一行将被忽略，不会进入结果数组。默认值为 – true。

4.3.4. `first_line – integer`。开始解析的行号。如果设置了has_header_row属性，则该行之后的下一行将被视为标题并忽略。默认值为 – 0。

4.3.5. `last_line – integer`。要解析的行号。如果等于0，则解析将进行到文件末尾。默认值为 – 0。

4.3.6. `min_column_quantity - integer`。文件行中必须填充的最小列数，以便该行进入结果数组。如果行中的填充列数少于参数中指定的列数，则该行将被忽略。默认值为 – 3。

4.3.7. `empty_lines_quantity - integer`。确定文件结尾的空行数。仅在last_line =0时才有意义。默认值为 – 3。也就是说，解析将在遇到三个连续空行后的行结束。

如果将解析器注册为应用程序组件，则可以按以下方式运行它

$data = Yii::$app->multiparser->parse( file_path );

在嵌套示例中，解析器在文件examples/modules/parser/config.php中注册为模块组件，因此可以在模块内通过以下方式访问它

        // get parser component
        $parser = Yii::$app->controller->module->multiparser;
        // setup configuration
        $parser->setConfiguration( $parser_config );
        // run parser
        $data = $parser->parse( $file_path, $custom_settings );

###5. 转换器。### 包含一个转换器，可以在解析过程中实现数据的转换。因此，可以在结果数组中获得清洗和转换后的数据。最简单的转换示例可以是更改编码。默认情况下，包中包含的转换器将编码从 'windows-1251' 转换为 'UTF-8'。转换器是一个具有转换值静态方法的独立类。要将转换器连接到解析器，需要填写配置文件中的converter_conf属性。该属性是具有两个必需元素的配置数组。键为class的元素中，需要指定使用的转换器类。键为configuration的元素是一个键值数组，键描述转换方法，值是文件列的名称。

5.1. Encode – 方法将编码从 'windows-1251' 转换为 'UTF-8'。

5.2. String – 方法清除字符串中的特殊字符。具体来说，删除以下字符 - !, @, #, $, %, ^, &, *, (, ), _, +, =, -, ~, ```, ", ', №, %, ;, :, [, ], {, }, *, ?, /, \ , |, ., ',' , <, >, \.

5.3. Integer – 方法将字符串转换为Integer。

5.4. Float – 方法将字符串转换为float。

仅在解析器的设置中指定了匹配的键（请参阅4.3.2中的属性key）时，才有必要指定转换的具体值。否则，需要将空数组指定为值，这将表示应用该方法到所有列。可以以三种方式指定转换列

'configuration' => ['encode' => [], // - конвертация всех колонок файла методом 'encode'
    'string' => ['Description', 'Brand'], - конвертация только двух колонок методом 'string'
    'integer' => 'Count' – конвертация колонки 'Count' методом 'integer'
]

扩展转换器。要添加自己的转换方法，需要创建自己的转换器类。这可以通过继承基本转换器类或实现ConverterInterface接口来完成。在此类中实现静态转换方法。

tsum / yii2-multiparser

维护者

详细信息

README