add import cookbook (#50)

* add import cookbook

* add import cookbook

Author: rprzedzik

docs/backend/cookbook.md

@@ -11,5 +11,6 @@
 * [New Condition](backend/cookbook/new_condition.md)
 * [New Channel](backend/cookbook/new_channel.md)
 * [New Mass Action](backend/cookbook/new_mass_action.md)
+* [New Import Source](backend/cookbook/new_source.md)
 
 

docs/backend/cookbook/new_channel.md

@@ -2,8 +2,8 @@
 # How to create a new channel
 
 Channel 
-* Entity Claas to management
-* external service connector(if required)
+* Entity Class to management
+* external service connector (if required)
 * specific configuration of a specific target system
 
 In your channel [module].

docs/backend/cookbook/new_source.md

@@ -0,0 +1,244 @@
+# How to create new import source
+
+## Source class
+
+Any custom source class must extend```AbstractSource```
+
+This class is used to define a new type of Source to appear in the application and can be used to store the necessary configuration data
+
+```php
+namespace YourNameSpace\Domain\Entity;
+
+use Ergonode\SharedKernel\Domain\Aggregate\SourceId;
+use Ergonode\Importer\Domain\Entity\Source\AbstractSource;
+
+class YourSource extends AbstractSource
+{
+    public const TYPE = 'your-source-type';
+
+    public function __construct(SourceId $id, string $name) 
+    {
+       parent::__construct($id, $name);
+    }
+    
+    public function getType(): string
+    {
+        return self::TYPE;
+    }
+}
+```
+
+## Source class configuration
+
+You need create Form class for configuration Your Source.
+
+Only "name" field is required, other are dependent from you needs.
+
+```php
+namespace YourNameSpace\Application\Form;
+
+use YourNameSpace\Application\Model\YourSourceConfigurationModel;
+use Symfony\Component\Form\AbstractType;
+use Symfony\Component\Form\Extension\Core\Type\TextType;
+use Symfony\Component\Form\FormBuilderInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+class YourSourceConfigurationForm extends AbstractType
+{
+    /**
+     * @param array $options
+     */
+    public function buildForm(FormBuilderInterface $builder, array $options): void
+    {
+        $builder
+            ->add(
+                'name',
+                TextType::class,
+                [
+                    'label' => 'Name',
+                ]
+            );
+    }
+
+    public function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setDefaults([
+            'translation_domain' => 'importer',
+            'data_class' => YourSourceConfigurationModel::class,
+            'allow_extra_fields' => true,
+            'label' => 'Import settings',
+        ]);
+    }
+
+    public function getBlockPrefix(): ?string
+    {
+        return null;
+    }
+}
+```
+
+Configuration Model class
+
+```php
+namespace YourNameSpace\Application\Model;
+
+use Symfony\Component\Validator\Constraints as Assert;
+use YourNameSpace\Domain\Entity\YourSource;
+
+class YourSourceConfigurationModel
+{
+    /**
+     * @Assert\NotBlank()
+     * @Assert\Length(min=2)
+     */
+    public ?string $name = null;
+
+    public function __construct(YourSource $source = null)
+    {
+        if ($source) {
+            $this->name = $source->getName();
+        }
+    }
+}
+```
+
+For providing form need to add ```YourSourceFormFactory``` class.
+
+```php
+namespace YourNameSpace\Application\Factory;
+
+use Ergonode\Importer\Domain\Entity\Source\AbstractSource;
+use YourNameSpace\Domain\Entity\YourSource;
+use Symfony\Component\Form\FormFactoryInterface;
+use YourNamespace\Application\Form\YourSourceConfigurationForm;
+use Symfony\Component\Form\FormInterface;
+use YourNamespace\Application\Model\YourSourceConfigurationModel;
+use Ergonode\Importer\Application\Provider\SourceFormFactoryInterface;
+use Symfony\Component\HttpFoundation\Request;
+
+class YourSourceFormFactory implements SourceFormFactoryInterface
+{
+    private FormFactoryInterface $formFactory;
+
+    public function __construct(FormFactoryInterface $formFactory)
+    {
+        $this->formFactory = $formFactory;
+    }
+
+    public function supported(string $type): bool
+    {
+        return YourSource::TYPE === $type;
+    }
+
+    public function create(AbstractSource $source = null): FormInterface
+    {
+        $model = new YourSourceConfigurationModel($source);
+        if (null === $source) {
+            return $this->formFactory->create(YourSourceConfigurationForm::class, $model);
+        }
+
+        return $this->formFactory->create(
+            YourSourceConfigurationForm::class,
+            $model,
+            ['method' => Request::METHOD_PUT]
+        );
+    }
+}
+```
+
+Next step is to create Source Manipulation Commands and Handlers
+
+```php
+namespace YourNameSpace\Domain\Command;
+
+use Ergonode\Importer\Domain\Command\CreateSourceCommandInterface;
+use Ergonode\SharedKernel\Domain\Aggregate\SourceId;
+use JMS\Serializer\Annotation as JMS;
+
+class CreateYourSourceCommand implements CreateSourceCommandInterface
+{
+    /**
+     * @JMS\Type("Ergonode\SharedKernel\Domain\Aggregate\SourceId")
+     */
+    private SourceId $id;
+
+    /**
+     * @JMS\Type("string")
+     */
+    private string $name;
+
+    public function __construct(
+        SourceId $id,
+        string $name
+    ) {
+        $this->id = $id;
+        $this->name = $name;
+    }
+
+    public function getId(): SourceId
+    {
+        return $this->id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+}
+
+```
+
+```php
+namespace YourNameSpace\Infrastructure\Handler;
+
+use Ergonode\Importer\Domain\Repository\SourceRepositoryInterface;
+use YourNameSpace\Domain\Command\CreateYourSourceCommand;
+use YourNameSpace\Domain\Entity\YourSource;
+
+class YourSourceSourceCommandHandler
+{
+    private SourceRepositoryInterface $repository;
+
+    public function __construct(SourceRepositoryInterface $repository)
+    {
+        $this->repository = $repository;
+    }
+
+    /**
+     * @throws \Exception
+     */
+    public function __invoke(CreateYourSourceCommand $command): void
+    {
+        $source = new YourSource(
+            $command->getId(),
+            $command->getName()
+        );
+
+        $this->repository->save($source);
+    }
+}
+
+```
+
+At last add you source import processor.
+
+```php
+namespace YourNameSpace\Infrastructure\Processor;
+
+use Ergonode\Importer\Domain\Entity\Import;
+use Ergonode\Importer\Infrastructure\Processor\SourceImportProcessorInterface;
+use YourNameSpace\Domain\Entity\YourSource;
+
+class YourSourceImportProcess implements SourceImportProcessorInterface
+{
+    public function supported(string $type): bool
+    {
+        return $type === YourSource::TYPE;
+    }
+
+    public function start(Import $import): void
+    {
+        // here is body of your import process
+    }
+}
+```

docs/backend/modules/importer.md

@@ -5,46 +5,26 @@
 This module is responsible for managing imports to ergonode from external systems or files. 
 
 
-## Reader
+## Custom Import error
 
-**Reader** is a component responsible for reading files in different formats. 
+If an error occurs during the import process, we may want to inform the user by presenting the relevant content in the import error list.
 
-One Reader class is responsible for one file type.
-
-To use it you need to create a class which implements **FileReaderInterface**.
+For that we need to create custom error. We're doing that by creating new exception class extended from ```Ergonode\Importer\Infrastructure\Exception\ImportException```
 
 ```php
-<?php
-namespace Ergonode\Component\Importer\Infrastructure\Reader;
+namespace YourNameSpace\Infrastructure\Exception;
 
-interface FileReaderInterface extends \IteratorAggregate, \Countable
+class YourCustomException extends ImportException
 {
-    public function open(string $file, array $configuration = [], array $formatters = []): void;
-    public function read(): \Traversable;
-    public function close(): void;
-}
-
-```
-
-Example of **Reader** you can find here:
-`Ergonode\Component\Importer\Infrastructure\Reader\CsvFileReader.php`
-
-
-## Formatter
+    private const MESSAGE  = 'Your error message with param {param}';
 
-**Formatters** are objects responsbile for changing every line from input file. 
-
-One **Formatter** class is responsible for one text editing operation. For example it can be used for removing some unwanted characters or changing text encoding.
-
-You you need to create a class which implements **FormatterInterface**.
-
-```php
-<?php
-namespace Ergonode\Component\Importer\Infrastructure\Formatter;
-
-interface FormatterInterface
-{
-    public function format(string $string): string;
+    public function __construct(string $param, \Throwable $previous = null)
+    {
+        parent::__construct(self::MESSAGE, ['{param}' => $param], $previous);
+    }
 }
 ```
 
+In addition to the importer.yml translation file, we can add a location-based version of our message
+
+Now if you throw this exception in import process, message will be automatically added to import error list