quince/data-importer

Tool for importing data from tabular data files into laravel models

data-importer

Tool for importing data from tabular data files into laravel models, _(*1)

Installation

Add data-importer to your composer.json file., _(*2)

for laravel 4:, _(*3)

"require": {
  "quince/data-importer": "~1.0"
}

and for laravel 5:, _(*4)

"require": {
  "quince/data-importer": "~2.0"
}

Use composer to install this package., _(*5)

$ composer update

Registering the Package

Register the service provider within the providers array found in app/config/app.php:, _(*6)

'providers' => array(
    'Quince\DataImporter\DataImporterServiceProvider'
)

Configuration

Next step is to publish package configuration by running:, _(*7)

in laravel 4 run:, _(*8)

$ php artisan config:publish quince/data-importer

and in laravel 5 run:, _(*9)

$ php artisan vendor:publish

Config file could be found in app/config/packages/quince/data-importer/config.php for laravel 4 and in config/quince/data-importer.php, _(*10)

Usage

You can use data-importer in two ways, _(*11)

Using Laravel IoC Container

Make sure exporter service manager is registered in your app config., _(*12)

<?php

// Initialize required data
$filePath = '/absolute/path/to/file/to/import';
$bindingModel = '/Namespace/ToYour/Model'; // or YourModel::class

// get data-importer out of IoC
$importer = App::make('importer');

/** @var RowsCollection $data */
$importer->import($filePath, $bindingModel, function($data) {
    // whatever you want to do with data
    // $data is an instance of RowsCollection
    // for example

    /** @var RowData $row */
    foreach ($data as $row) {
        YourModel::create($row->getBase());
    }
});

Using Laravel Dependency Injection

You can also inject Quince\DataImporterManager in your class, and use it., _(*13)

<?php

use Quince\DataImporterManager as Importer;

class ExampleClass {

    protected $importer

    public function __construct(Importer $importer)
    {
        $this->importer = $importer;
    }

    public function exampleMethod($file)
    {
        $this->importer->import($file->getPath(), DesiredModel::class, function($data) {
            // whatever you want to do with data
        });
    }

}

Advanced Usages

Each row of file is a presenter of a record in database, and each record may have relation records. In your csv file, a column may be present these relation records. Header of this column is a concatenation of relation name and field name of relation that is provide in that column (Concat with relation_joint is set in config file). if a column have many relation records, values should be separated with relation_value_delimiter which is set in config file., _(*14)

Example

The file below:, _(*15)

will be converted to something like this (as json):, _(*16)

[
    {
        "name": "John Doe",
        "username": "Johny",
        "email": "J.Doe@mail.com",
        "phones": [
            {
                "number": "0941120773"
            }
        ]
    },
    {
        "name": "Jane Doe",
        "username": "Jane6",
        "email": "miss.J.Doe@gmail.com",
        "phones": [
            {
                "number": "0929339687"
            },
            {
                "number": "0916740160"
            }
        ]
    }
]

Additional Fields

When only some of the table fields are provided in given file, you can set those field manualy, _(*17)

NOTE: You should specify additional fields are for main record or relation records, _(*18)

<?php

// Initialize required data
$filePath = '/absolute/path/to/file/to/import';
$bindingModel = '/Namespace/ToYour/Model'; // or YourModel::class
$additionalFields = [
    'base' => [
        'column_name' => 'value'
    ],
    'relation' => [
        'relation_name' => [
            'column_name' => 'value'
        ]
        // another relations goes heare
    ]
];

// get data-importer out of IoC
$importer = App::make('importer');

$importer->setAdditionalFields($additionalFields)
         ->import($filePath, $bindingModel, function($data) {
            // whatever you want to do with data
         });

If fields that specified as additional fields exist in csv file, data will be loaded from csv file. But if you pass true as second parameter for setAdditionalFields aditional fields will overwrite existing data in csv file., _(*19)

$importer->setAdditionalFields($additionalFields, true)
         ->import($filePath, $bindingModel, function($data) {
            // whatever you want to do with data
         });

Translating file headers

When column headers of your file are defferent from your table columns, you can map them to your database table columns. Assume your file is like:, _(*20)

you can pass a dictionary for your file custom header to translate them to their table-column names., _(*21)

<?php

// Initialize required data
$filePath = '/absolute/path/to/file/to/import';
$bindingModel = '/Namespace/ToYour/Model'; // or YourModel::class
$dictionary = [
    'Real Name'     => 'name',
    'Nickname'      => 'username',
    'Mail Address'  => 'email',
    'Phone Numbers' => 'phones.number'
];

// get data-importer out of IoC
$importer = App::make('importer');

$importer->setDictionary($dictionary)
         ->import($filePath, $bindingModel, function($data) {
            // whatever you want to do with data
         });

you can also map a single column of your file to a column in your database table., _(*22)

$importer->setColumnDictionary($columnName, $translation)
         ->import($filePath, $bindingModel, function($data) {
            // whatever you want to do with data
         });

For more information about advanced usage visit wiki pages, _(*23)

Config file