README

Easier import from multiple file types (csv, json, xml, excel).

Support for Symfony, Lumen and Laravel.

Documentation

• Installation
  • Symfony
  • Laravel
  • Lumen
  • Without Framework
• How to use
  • ImportConfiguration
    • BeforeImport
    • ChunkImport
  • Import
    • Import From File
    • Import From String
  • Pass Additional Data
• Extending

Installation

1. Add dependency with composer

composer require kunicmarko/importer

Symfony

Register the bundle in your config/bundles.php

return [
    //...
    KunicMarko\Importer\Bridge\Symfony\ImporterBundle::class => ['all' => true],
];

By default, excel import is disabled, install "phpoffice/phpspreadsheet" to enable it.

Laravel

Register the service provider in your config/app.php

providers' => [
    //...
    KunicMarko\Importer\Bridge\Laravel\ImporterServiceProvider::class,
],

By default, excel import is disabled, install "phpoffice/phpspreadsheet" to enable it.

Lumen

Register the service provider in your bootstrap/app.php

$app->register(KunicMarko\Importer\Bridge\Lumen\ImporterServiceProvider::class);

By default, excel import is disabled, install "phpoffice/phpspreadsheet" to enable it.

Without Framework

Add the Readers you want to use to a Factory and get your Importer:

use KunicMarko\Importer\ImporterFactory;
use KunicMarko\Importer\Reader\CsvReader;
use KunicMarko\Importer\Reader\JsonReader;
use KunicMarko\Importer\Reader\XmlReader;
use KunicMarko\Importer\Reader\XlsxReader;

$importerFactory = new ImporterFactory();

$importerFactory->addReader(new CsvReader());
$importerFactory->addReader(new JsonReader());
$importerFactory->addReader(new XmlReader());
$importerFactory->addReader(new XlsxReader());

$importer = $importerFactory->getImporter('csv');
$importer->fromString('some,csv,string')
    ->useImportConfiguration(new YourImportConfiguration())
    ->import();

If you want to use excel import, install "phpoffice/phpspreadsheet".

How to use

ImportConfiguration

ImportConfiguration defines how should the data be mapped and saves the data. They have to implement KunicMarko\Importer\ImportConfiguration interface.

use KunicMarko\Importer\ImportConfiguration;

class ImportUserConfiguration implements ImportConfiguration
{
    public function map(array $item, array $additionalData)
    {
        $user = new User();
        
        $user->setUsername($item['username']);
        //..

        return $user;
    }

    public function save(array $items, array $additionalData): void
    {
        //save your users
    }
}

BeforeImport

BeforeImport allows your ImportConfiguration to do something with data before the mapping starts.

use KunicMarko\Importer\ImportConfiguration;
use KunicMarko\Importer\BeforeImport;
use Iterator;

class ImportSomethingConfiguration implements ImportConfiguration, BeforeImport
{
    public function before(Iterator $items, array $additionalData): Iterator
    {
        //start from 2nd line
        $items->next();

        return $items;
    }
}

ChunkImport

ChunkImport allows your configuration to define a number of items that the save method will receive, instead of receiving all at once.

use KunicMarko\Importer\ImportConfiguration;
use KunicMarko\Importer\ChunkImport;

class ImportChunkSomethingConfiguration implements ImportConfiguration, ChunkImport
{
    public function chunkSize(): int
    {
        return 50;
    }

    public function save(array $items, array $additionalData): void
    {
        //save will be called multiple times with 50 or less items
    }
}

Import

After you have defined your import configuration, you can import from a file or from a string. You HAVE to provide one of those 2 options and your import configuration.

Import From File

use KunicMarko\Importer\ImporterFactory;

class UserImport
{
    private $importerFactory;

    public function __construct(ImporterFactory $importerFactory)
    {
        $this->importerFactory = $importerFactory;
    }
    
    public function import()
    {
        $importer = $importerFactory->getImporter('csv');

        $importer->fromFile('path/to/file.csv')
            ->useImportConfiguration(new YourImportConfiguration())
            ->import();
    }
}

Import From String

use KunicMarko\Importer\ImporterFactory;

class UserImport
{
    private $importerFactory;

    public function __construct(ImporterFactory $importerFactory)
    {
        $this->importerFactory = $importerFactory;
    }
    
    public function import()
    {
        $importer = $importerFactory->getImporter('csv');

        $importer->fromString('some,csv,string')
            ->useImportConfiguration(new YourImportConfiguration())
            ->import();
    }
}

Excel import does not support import from a string.

Pass Additional Data

Sometimes you may want to pass additional data to your import configuration.

use KunicMarko\Importer\ImporterFactory;

class UserImport
{
    private $importerFactory;

    public function __construct(ImporterFactory $importerFactory)
    {
        $this->importerFactory = $importerFactory;
    }
    
    public function import()
    {
        $importer = $importerFactory->getImporter('csv');

        $importer->fromString('some,csv,string')
            ->useImportConfiguration(new YourImportConfiguration())
            ->withAdditionalData(['user' => 'kunicmarko20'])
            ->import();
    }
}

Extending

You can always add your own custom readers, just implement KunicMarko\Importer\Reader\Reader interface and call addReader() method on ImporterFactory.