xeops / iiko-exchange
Installs: 4 108
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 2
Forks: 3
Open Issues: 0
Type:project
Requires
- php: ^7.4
- ext-ftp: *
- ext-json: *
- ext-simplexml: *
- ext-ssh2: *
- php-http/guzzle6-adapter: ^1.1
- phpseclib/phpseclib: ~2.0
- symfony/config: ~3.0
- symfony/event-dispatcher: 3.2.*
- symfony/monolog-bundle: ^3.2
- symfony/yaml: 3.2.*
Requires (Dev)
- phpunit/php-code-coverage: 9.1.11
- phpunit/phpunit: ^9
- symfony/phpunit-bridge: 5.1.*
This package is auto-updated.
Last update: 2025-03-15 11:22:58 UTC
README
iiko data exchange library
Данная библиотека представляет собой ETL процесс для интеграции iiko c внешними системами посредством сервера iikoWeb.
Суть интеграции состоит в плановом одностороннем обмене данных между iiko и внешней системой.
/-------------/ /----------------/
/ iiko / -----> / 3d paty system /
/-------------/ /----------------/
Возможен обмен в обратном порядке ( 3d paty system -> iiko )
Процесс разработки обмена следующий
- Создается проект, использующий данную библиотеку
- Проект проходит аудит и ревью разработчиками iikoWeb
- Проект включается в продукт iikoWeb посредством composer
Процесс работы обмена
- Пользователь открывает frontend приложение Exchange, написанное на Angular
- Приложение запрашивает все возможные типы обменов у сервера iikoWeb
- Пользователь создает обмен, указывая имя и рестораны, для которых оно будет работать. На данном этапе рестораны могут быть не указаны, и тогда будут работать все, что есть в сети.
- Пользователь вводит настройки подключения к внешней системе
- Пользователь заполняет все настройки и сопоставления (мапинги) согласно документации и/или подсказкам.
- Пользователь настраивает расписание
- После сохранения расписания, согласно ему создается задание на сервере iikoWeb.
- При наступлении времени исполнения, iikoWeb запускает процесс обмена, заполняя его всеми необходимыми настройками и сопоставлениями.
Первые шаги
Создание проекта
Необходимо создать проект со следующей директорией папок
AcmeExchangeBundle │ ├── src │ ├── Formatter │ ├── Loader │ ├── Mapping │ ├── OptionSet(?) │ ├── Request │ ├── Resources │ │ ├── config │ │ │ └── services.yml │ │ └── view │ │ └── preview.html.twig │ └── Transformer ├── Tests │ └── ***** └── README.md
Инициализация проекта
Процесс инициализации проекта описан в отдельной статье
Подключение библиотеки
composer require xeops/iiko-exchange
Реализация
1. Инициализация сервиса Обмена
Первым делом необходимо в services.yml создать сервис обмена
exchange.acme: # Собственный класс можно не создавать, базовый класс содержит всю необходимую реализацию class: iikoExchangeBundle\Exchange\Exchange # в качестве аргумента необходимо передать уникальный код обмена, который будет использоваться для переводов и получения настроек # чтобы гарантировать уникальность - используйте названия внешней системы, с которой вы интегрируетесь и способ arguments: [ 'ACME_OLAP_TO_FTP_EXCHANGE_CODE' ] calls: # задайте расписание, с помощью которого обмен будет запускать в автоматическом режиме - [ setSchedules,[ [ '@exchange.schedule.cron' ] ] ] # задайте шаблон, с помощью которого будет выводиться превью выгрузки - [ setPreviewTemplate, [ 'AcmeExchangeBundle::preview.html.twig' ] ] # без тегирования система не узнает о том, что вы подключили новый механизм обмена tags: - { name: "exchange" }
! не забудьте добавить первой строкой в services.yml
services: # начиная от этого отступа объявляйте сервисы
2. Создание соединения с внешней системой
Есть несколько типов подключения
Для создания своего типа используйте базовый класс После создайте сервис и подключите его к уже созданному сервису обмена
# Создание соединения exchange.acme.connection: class: AcmeExchangeBundle\Loader\AcmeOAuth2Connection arguments: [ 'ACME_CONNECTION', '@exchange.storage.session', '@logger' ] tags: - { name: "exchange.connection" }
# подключение соединения exchange.acme: class: iikoExchangeBundle\Exchange\Exchange ..... calls: ...... # для добавления соединения просто добавьте строчку ниже в уже существующий массив calls созданного сервиса обмена - [ setLoader, [ '@exchange.acme.connection' ] ] ...... ........
Для подключения соединения с iiko просто подключите уже созданный сервис соединения
# подключение соединения к iiko exchange.acme: class: iikoExchangeBundle\Exchange\Exchange ..... calls: ...... # для добавления соединения просто добавьте строчку ниже в уже существующий массив calls созданного сервиса обмена - [ setExtractor, [ '@exchange.connection.iiko' ] ] ...... ........
В данном примере используется направление iiko -> 3d party system
. Если нужна выгрузка в обратную сторону, соединения
нужно поменять местами.
3. Создание движков
Под каждую задачу в рамках одного процесса выгрузки создайте движок Создайте для каждого движка сервис
exchange.acme.engine: # Собственный класс можно не создавать, базовый класс содержит всю необходимую реализацию class: iikoExchangeBundle\Engine\ExchangeEngine # В качестве аргумента необходимо передать уникальный код движка arguments: [ 'ACME_SALES' ]
3.1 Создание запросов
Каждый движок опеределяется уникальным набором запросов и механизмом трансформации ( трансформер и форматор )
exchange.acme.request.sales: class: Exchange\AcmeExchangeBundle\Request\SalesRequest arguments: [ 'ACME_SALES_REQUEST' ]
3.2 Создание трансформера
После выполнения запросов к внешней системе, данные должны быть очищены и преобразованы в бизнес модель системы, в которую данные будут выгружены с помощью трансформера.
exchange.acme.transformer.sales: class: Exchange\AcmeExchangeBundle\Transformer\SalesTransformer arguments: [ 'ACME_TRANSFORMER_SALES']
3.3 Создание форматера
После трансформации данных в бизнес модель, эти данные необходимо отформатировать в запрос, принимаемой принимающей стороной. Для этого необходимо реализовать форматер
exchange.acme.formatter.sales: class: Exchange\AcmeExchangeBundle\Formatter\SalesFormatter arguments: [ 'ACME_FORMATTER_SALES' ]
3.4 подключение модулей движка
После реализации запросов, трансформера и форматера сервисы нужно подключить в качестве модулей в движок, который собирается их использовать
exchange.acme.engine: class: iikoExchangeBundle\Engine\ExchangeEngine .... calls: # Запросы подключаются массивом, т.к. данные от запросов аккумулируются и передаются массивом в трансформацию - [ setRequests, [ [ '@exchange.acme.request.sales' ] ] ] - [ setFormatter, [ '@exchange.acme.formatter.sales' ] ] - [ setTransformer, [ '@exchange.acme.transformer.sales' ] ]
Создание и использование расширений
На каждом этапе выгрузки может потребоваться получить
Для этого классы могут использовать механизм трейтов Каждое расширение подключается отдельно и используется тоже отдельно, прочитать подробнее можно по ссылкам сверху.
Далее механизм обмена, автоматически заполнит ваши сервисы маппингом, конфигурацией, рестораном, периодом, если они ему необходимы.
Переводы
Пример
Пример реализации доступен в проекте песочницы
Запуск проекта
Для запуска проекта используйте песочницу