Commit d1faa09b20a6635b7e586678afcc937045703129
1 parent
0f83918b
4 and 5 chapter in documentation
Showing
2 changed files
with
58 additions
and
14 deletions
Show diff stats
README.md
| ... | ... | @@ -11,12 +11,12 @@ The Multiparser library has the following requirements: |
| 11 | 11 | ##Documentation## |
| 12 | 12 | |
| 13 | 13 | ###1. Общие сведения.### |
| 14 | -Парсер позволяет отпарсить содержимое файла в массив. Парсер поддерживает csv, xml, xls, xlsx, txt расширения. Для каждого расширения необходимо описать правила парсинга в конфигурационном файле (см. п.4). Для одного расширения можно указать несколько сценариев (использование двух сценариев описано в п.3. в вложенном примере к парсеру). | |
| 14 | +Парсер позволяет прочитать содержимое файла в массив. Парсер поддерживает csv, xml, xls, xlsx, txt расширения. Для каждого расширения необходимо описать правила парсинга в конфигурационном файле (см. п.4). Для одного расширения можно указать несколько сценариев (использование двух сценариев описано в п.3. в вложенном примере к парсеру). | |
| 15 | 15 | ###2. Установка.### |
| 16 | 16 | После копирования пакета в проект необходимо установить парсер как компонент YII. Для этого необходимо составить конфигурационный файл – config.php. Примерами могут служить файл который вложен в пакет или конфигурационный файл, который скомпонован для работы примера (п. 3). Далее в файле common/config/main.php – добавить компонент: |
| 17 | 17 | |
| 18 | 18 | ```php |
| 19 | -$mp_configuration = require(path to config.php); | |
| 19 | +$mp_configuration = require("path to config.php"); | |
| 20 | 20 | return [ |
| 21 | 21 | … |
| 22 | 22 | … |
| ... | ... | @@ -33,8 +33,63 @@ $data = Yii::$app->multiparser->parse( file_path ); |
| 33 | 33 | ``` |
| 34 | 34 | |
| 35 | 35 | ###3. Установка примера.### |
| 36 | +В состав пакета входит развернутый пример парсинга всех типов файлов с разными настройками. Пример написан для использования в YII-advance. Для basic приложения необходимо будет отдельно настроить пространство имен. | |
| 37 | + Для ознакомления с примером необходимо произвести установку пакета как описано в п.2. В качестве конфигурационного файла необходимо указать файл – examples\config.php. | |
| 38 | +В состав примера входят: | |
| 39 | + 3.1. Контроллер - examples\ParserController.php – его необходимо скопировать в папку с контроллерами бекенда. | |
| 40 | + 3.2. Файлы вью - examples\Views – содержимое необходимо скопировать в папку views бекенда. | |
| 41 | + 3.3. Пользовательская форма выбора файла - examples\UploadFileParsingForm.php – скопировать в модели бекенда. | |
| 42 | + 3.4. Файлы с данными для парсинга - examples\_data – содержимое необходимо скопировать в test\_data проекта. | |
| 43 | + | |
| 36 | 44 | ###4. Описание конфигурационного файла.### |
| 37 | -###5. Дополнительные возможности.### | |
| 45 | +Конфигурационный файл представляет собой описание многомерного массива настроек (пример - examples\config.php). | |
| 46 | +4.1. Элементами первого уровня массива указываются расширения файлов, с которыми компонент будет работать. Для каждого расширения определяется массив настроек парсинга данного типа файлов. Пакет поддерживает определение нескольких сценариев (несколько параллельных настроек) для одного типа файлов. | |
| 47 | +4.2. Сценарии указываются на втором уровне. Так в примере к пакету используются два сценария – template – для файлов приложенных к пакету, и custom – для файлов выбранных пользователем. | |
| 48 | +Также на этом уровне можно определить параметры, которые будут доступны для данного расширения. В примере используется эта возможность для определения колонок выбора соответствия отпарсенных колонок с эталонными колонками (параметр - basic_column). Вызов этого параметра можно осуществить следующим образом: | |
| 49 | +```php | |
| 50 | +Yii::$app->multiparser->getConfiguration($file_extension, 'basic_column'); | |
| 51 | +``` | |
| 52 | + | |
| 53 | +4.3. На третьем указываются настройки парсера в виде конфигурационного массива YII. | |
| 54 | +Данный массив имеет один обязательный элемент с ключем – class, в котором указывается имя парсера, который будет обрабатывать данный тип файлов. Таким образом можно указать свой класс парсера, или использовать классы входящие в пакет, например для csv это класс - 'yii\multiparser\CsvParser'. | |
| 55 | +При использовании встроенного класса (или наследуемые от него) в данном массиве можно установить следующие атрибуты в качестве настроек: | |
| 56 | +4.3.1. converter_conf – array. Настройки конвертера. Детально описано в п.5. | |
| 57 | +4.3.2. keys – array. В этом параметре можно назначить имена колонкам файла. Например: | |
| 58 | +```php | |
| 59 | +'keys' => [ | |
| 60 | + 0 => 'Description', | |
| 61 | + 1 => 'Article', | |
| 62 | + 2 => 'Price', | |
| 63 | + 3 => 'Brand', | |
| 64 | + 4 => 'Count', | |
| 65 | +] | |
| 66 | +``` | |
| 67 | +При такой настройке результирующий массив будет ассоциативным, где в колонке массива с ключем ‘'Brand'’ – будут значения из четвертой колонки файла. | |
| 68 | +4.3.3. has_header_row – bolean. Признак, имеет ли файл заголовок в первой значимой строке, если true - первая значимая строка будет пропущена и не попадет в результирующий массив. По умолчанию – true. | |
| 69 | +4.3.4. first_line – integer. Номер строки с которой начинается парсинг. Если установлен аттрибут has_header_row, тогда следующая строка за данной, будет считаться заголовком и будет пропущена. По умолчанию – 0. | |
| 70 | +4.3.5. last_line – integer. Номер строки по которую будет произведен парсинг. Если = 0, парсинг будет производится до конца файла. По умолчанию – 0. | |
| 71 | +4.3.6. min_column_quantity - integer. Количество заполненных колонок строки начала файла. Если строка имеет не меньше заполненных колонок чем указано в параметре, данная строка считается значимой и с неё начинается парсинг файла. Используется при старте парсинга для определения начала файла. Имеет смысл только при first_line =0. По умолчанию – 5. То есть парсинг начнется с первой строки файла, которая имеет не меньше 5 колонок с данными. | |
| 72 | +4.3.7. empty_lines_quantity - integer. Количество пустых строк, что бы определить конец файла. Имеет смысл только при first_line =0. По умолчанию – 3. То есть парсинг закончится на строке, после которой встретятся три пустых строки. | |
| 73 | + | |
| 74 | +###5. Конвертер.### | |
| 75 | +В состав пакета входит конвертер который позволяет осуществлять преобразования прочитанных данных в процессе парсинга. Таким образом можно получить очищенные и преобразованные данные в результирующем массиве. Простейшим примером, такого преобразования может служит смена кодировки. По умолчанию конвертер входящий в пакет осуществляет смену кодировки с 'windows-1251' в 'UTF-8'. | |
| 76 | +Конвертер представляет собой отдельный класс с статическими методами конвертации значений. Что бы подключить конвертер к парсеру, необходимо заполнить свойство конфигурационного файла converter_conf. | |
| 77 | +Данное свойство является конфигурационным массивом с двумя обязательными элементами. Элемент с ключем class, в котором необходимо указать класс используемого конвертера. И Элемент с ключем configuration – массив ключи которого описывают методы преобразования, а значения – имена колонок файла для преобразования. | |
| 78 | +Конвертер входящий в пакет содержит следующие методы преобразования: | |
| 79 | +5.1. Encode – метод меняет кодировку с 'windows-1251' в 'UTF-8'. | |
| 80 | +5.2. String – метод очищает строку от специальных символов. А именно, удаляются - !, @, #, $, %, ^, &, *, (, ), _, +, =, -, ~, `, ", ', №, %, ;, :, [, ], {, }, *, ?, /, \ , |, ., ',' , <, >, \. | |
| 81 | +5.3. Integer – метод преобразует строку в Integer. | |
| 82 | +5.4. float – метод преобразует строку в float. | |
| 83 | +Конкретные значения для конвертации есть смысл указывать только если в настройках парсера указаны ключи соответствия (свойство key см. 4.3.2). Иначе необходимо указать в качестве значения – пустой массив, что будет означать применение данного метода для всех колонок файла. | |
| 84 | +Допустимо указывать колонки для конвертации тремя способами: | |
| 85 | +```php | |
| 86 | +'configuration' => ['encode' => [], // - конвертация всех колонок файла методом 'encode' | |
| 87 | + 'string' => ['Description', 'Brand'], - конвертация только двух колонок методом 'string' | |
| 88 | + 'integer' => 'Count' – конвертация колонки 'Count' методом 'integer' | |
| 89 | +] | |
| 90 | +``` | |
| 91 | +Расширение конвертера. | |
| 92 | +Для добавления своих методов преобразования необходимо создать свой класс конвертера. Это можно сделать путем наследования от базового класса конвертера или реализовав интерфейс ConverterInterface. В данном классе реализовать статические методы преобразования. | |
| 38 | 93 | |
| 39 | 94 | |
| 40 | 95 | ... | ... |