From d1faa09b20a6635b7e586678afcc937045703129 Mon Sep 17 00:00:00 2001 From: Mihail Date: Fri, 25 Dec 2015 17:50:14 +0200 Subject: [PATCH] 4 and 5 chapter in documentation --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- lib/ParserValidator.php | 11 ----------- 2 files changed, 58 insertions(+), 14 deletions(-) delete mode 100644 lib/ParserValidator.php diff --git a/README.md b/README.md index 6dcbee3..a7f160d 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,12 @@ The Multiparser library has the following requirements: ##Documentation## ###1. Общие сведения.### -Парсер позволяет отпарсить содержимое файла в массив. Парсер поддерживает csv, xml, xls, xlsx, txt расширения. Для каждого расширения необходимо описать правила парсинга в конфигурационном файле (см. п.4). Для одного расширения можно указать несколько сценариев (использование двух сценариев описано в п.3. в вложенном примере к парсеру). +Парсер позволяет прочитать содержимое файла в массив. Парсер поддерживает csv, xml, xls, xlsx, txt расширения. Для каждого расширения необходимо описать правила парсинга в конфигурационном файле (см. п.4). Для одного расширения можно указать несколько сценариев (использование двух сценариев описано в п.3. в вложенном примере к парсеру). ###2. Установка.### После копирования пакета в проект необходимо установить парсер как компонент YII. Для этого необходимо составить конфигурационный файл – config.php. Примерами могут служить файл который вложен в пакет или конфигурационный файл, который скомпонован для работы примера (п. 3). Далее в файле common/config/main.php – добавить компонент: ```php -$mp_configuration = require(path to config.php); +$mp_configuration = require("path to config.php"); return [ … … @@ -33,8 +33,63 @@ $data = Yii::$app->multiparser->parse( file_path ); ``` ###3. Установка примера.### +В состав пакета входит развернутый пример парсинга всех типов файлов с разными настройками. Пример написан для использования в YII-advance. Для basic приложения необходимо будет отдельно настроить пространство имен. + Для ознакомления с примером необходимо произвести установку пакета как описано в п.2. В качестве конфигурационного файла необходимо указать файл – examples\config.php. +В состав примера входят: + 3.1. Контроллер - examples\ParserController.php – его необходимо скопировать в папку с контроллерами бекенда. + 3.2. Файлы вью - examples\Views – содержимое необходимо скопировать в папку views бекенда. + 3.3. Пользовательская форма выбора файла - examples\UploadFileParsingForm.php – скопировать в модели бекенда. + 3.4. Файлы с данными для парсинга - examples\_data – содержимое необходимо скопировать в test\_data проекта. + ###4. Описание конфигурационного файла.### -###5. Дополнительные возможности.### +Конфигурационный файл представляет собой описание многомерного массива настроек (пример - examples\config.php). +4.1. Элементами первого уровня массива указываются расширения файлов, с которыми компонент будет работать. Для каждого расширения определяется массив настроек парсинга данного типа файлов. Пакет поддерживает определение нескольких сценариев (несколько параллельных настроек) для одного типа файлов. +4.2. Сценарии указываются на втором уровне. Так в примере к пакету используются два сценария – template – для файлов приложенных к пакету, и custom – для файлов выбранных пользователем. +Также на этом уровне можно определить параметры, которые будут доступны для данного расширения. В примере используется эта возможность для определения колонок выбора соответствия отпарсенных колонок с эталонными колонками (параметр - 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 – bolean. Признак, имеет ли файл заголовок в первой значимой строке, если 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. Количество заполненных колонок строки начала файла. Если строка имеет не меньше заполненных колонок чем указано в параметре, данная строка считается значимой и с неё начинается парсинг файла. Используется при старте парсинга для определения начала файла. Имеет смысл только при first_line =0. По умолчанию – 5. То есть парсинг начнется с первой строки файла, которая имеет не меньше 5 колонок с данными. +4.3.7. empty_lines_quantity - integer. Количество пустых строк, что бы определить конец файла. Имеет смысл только при first_line =0. По умолчанию – 3. То есть парсинг закончится на строке, после которой встретятся три пустых строки. + +###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. +Конкретные значения для конвертации есть смысл указывать только если в настройках парсера указаны ключи соответствия (свойство key см. 4.3.2). Иначе необходимо указать в качестве значения – пустой массив, что будет означать применение данного метода для всех колонок файла. +Допустимо указывать колонки для конвертации тремя способами: +```php +'configuration' => ['encode' => [], // - конвертация всех колонок файла методом 'encode' + 'string' => ['Description', 'Brand'], - конвертация только двух колонок методом 'string' + 'integer' => 'Count' – конвертация колонки 'Count' методом 'integer' +] +``` +Расширение конвертера. +Для добавления своих методов преобразования необходимо создать свой класс конвертера. Это можно сделать путем наследования от базового класса конвертера или реализовав интерфейс ConverterInterface. В данном классе реализовать статические методы преобразования. diff --git a/lib/ParserValidator.php b/lib/ParserValidator.php deleted file mode 100644 index 923c576..0000000 --- a/lib/ParserValidator.php +++ /dev/null @@ -1,11 +0,0 @@ -