Mihail / yii-multiparser

  YII2 Multiparser

  ==================

  Flexible bunch of parsers for YII 2.
  
  ##Requirements##
  
  The Multiparser library has the following requirements:
  

   - yiisoft/yii2

  ##Documentation##
  

  ###1.	Общие сведения.###

  Парсер позволяет прочитать содержимое файла в массив. Парсер поддерживает csv, xml, xls, xlsx, txt расширения. Для каждого расширения необходимо описать правила парсинга в конфигурационном файле (см. п.4). Для одного расширения можно указать несколько сценариев (использование двух сценариев описано в п.3. в вложенном примере к парсеру).

  ###2.	Установка.###

  После копирования пакета в проект необходимо установить парсер как компонент YII. Для этого необходимо составить конфигурационный файл – config.php. Примерами могут служить файл который вложен в пакет или конфигурационный файл, который скомпонован для работы примера (п. 3). Далее в файле common/config/main.php – добавить компонент:
  
  ```php

  $mp_configuration = require("path to config.php");

  return [
      …
  	…
          'multiparser'=>[
              'class' => 'yii\multiparser\YiiMultiparser',
              'configuration' => $mp_configuration,
          ],
      ],
  ];
  ```
  После этого парсер можно запускать следующим образом:
  ```php
  $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.	Описание конфигурационного файла.###

  Конфигурационный файл представляет собой описание многомерного массива настроек (пример - 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. В данном классе реализовать статические методы преобразования.