DAM-connector

This is a skeleton for an Akeneo PIM Connector between a DAM and the Akeneo PIM API.

It's a PHP console application using Symfony 4 and MySQL to hold information on executed commands.

For more information on how to create your DAM Connector see the guide.

Concepts & Resources

Please refer to our official documentation This is the source of truth of our Ubiquitous Language.

Install

Via Composer:

Requirements:

• PHP >= 7.2
• composer

composer install

Via Docker & Docker Compose:

Requirements:

• Docker & Docker Compose >= 3

docker-compose run --rm dam-connector_php-cli composer install

Composer default configuration will use a UID=1000 and GID=1000 for files permissions and use a local composer configuration folder at COMPOSER_HOME=~/.composer.

If it doesn't suit your need you can override this configuration by running docker-compose run commands with different value for each environment variable

UID=$UID GID=$GID COMPOSER_HOME=$HOME/.composer docker-compose run dam-connector_php-cli composer install

Or you can use a custom Docker Compose override file.

How to use this skeleton?

This skeleton provides 2 Symfony commands:

• dam-connector:assets:synchronize-structure to init/synchronize the assets structure
• dam-connector:assets:synchronize to synchronize the assets

Development with Docker Compose 🐳

To start the MySQL server:

docker-compose up -d

To access the Symfony console:

docker-compose run --rm dam-connector_php-cli bin/console

Accessing a local Akeneo PIM running in another Docker Compose

If you are hosting a parallel Akeneo PIM instance on your host (e.g. localhost:8080) and want to access it inside your connector, then the simplest way is to share the Akeneo PIM network with your Connector.

It can be done in a docker-compose.override.yml file:

version: '3'

networks:
    akeneo:
        external:
            name: pim_network_name # Use "docker network ls" to find the name of your Akeneo PIM network.

services:
    dam-connector_php-cli:
        networks:
            - default # Access this docker-compose network (mysql, ...)
            - akeneo # Access to Akeneo PIM network

Documentation

⚠️ In this DAM connector skeleton we made some structural choices and those may not be the right one for your use case.

Config

As seen in the guide we need to define a configuration for the mapping between the DAM Assets Properties and the PIM Assets Attributes.

We choose to do this with a simple .yaml configuration file referenced in a Symfony DI parameter app.dam_to_pim_mapping.config_path (see config/services/dam-example.yaml).

Architecture 🏗️

This skeleton uses hexagonal architecture. The code is split in 3 main parts: Application, Domain and Infrastructure.

Application

On the Application side we defined a service Application\Service\SynchronizeAssets that is handling all the synchronization logic between the PIM and the DAM.

We also have some Interfaces that describe what actions are needed to communicate with the DAM and the PIM and you can found the concrete implementation of these classes on the Infrastructure side.

• Application\DamAdapter\
• Application\PimAdapter\

The Application\Mapping folder hold all the logic needed to transform a DAM Asset into a PIM Asset. You may have to change this depending on your need, especially for the Application\Mapping\AssetValueConverter that is transforming the data format of your DAM to the PIM format.

Domain

The Domain objects have been defined following our ubiquitous language

Infrastructure

Define a concrete class that implement the Application\DamAdapter\FetchAssets interface. See dam-example.yaml. The Application\Service\SynchronizeAssets will then have access to your FetchAssets implementation.

We already provide a simple implementation for the Application\PimAdapter\UpdateAsset interface inside Infrastructure\Pim. So you can upsert PimAsset right away.

Then we have the Symfony Console Command Infrastructure\Command\SynchronizeAssetsCommand that is designed to be the entry point of the Connector via bin/console dam-connector:assets:synchronize and can be called regularly, via a Cron jon for example, to synchronize assets between the DAM and the PIM.

Run tests

Our test stack is based on hexagonal architecture and is composed of different types:

• Unit tests for logic. Most of the time, you have one unit test class by implemented class.
• Integration tests for the infrastructure layer. It tests that the input or output are correctly working.
• End-To-End tests to test the whole stack. We currently don't have these tests but behat and phpunit are good tools for that.

Unit tests

We suggest phpspec and phpunit as unit test tools. You can run them through docker-compose run --rm dam-connector_php-cli vendor/bin/phpspec run and docker-compose run --rm dam-connector_php-cli bin/phpunit --testsuite unit

Integration tests

We suggest phpunit as integration test tool. You can run these these with the following command docker-compose run --rm dam-connector_php-cli bin/phpunit --testsuite integration.

Checkstyle

You can launch php-cs-fixer using the following command docker-compose run --rm dam-connector_php-cli vendor/bin/php-cs-fixer fix src && docker-compose run --rm dam-connector_php-cli vendor/bin/php-cs-fixer fix tests

Coupling Detector

We use Akeneo Coupling Detector tool to check coupling between the different layers. The rules are defined in .php_cd.php file and can be launched using docker-compose run --rm dam-connector_php-cli vendor/bin/php-coupling-detector detect src --config-file=.php_cd.php.