PHPackages                             michaelhoughton/silverstripe-importexport - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. michaelhoughton/silverstripe-importexport

ActiveSilverstripe-vendormodule[PDF & Document Generation](/categories/documents)

michaelhoughton/silverstripe-importexport
=========================================

An upgrade to SilverStripe's bulk loading and exporting for PHP 8.1

2.5.1(2y ago)0207MITPHPPHP >=8.1

Since Jul 31Pushed 2y agoCompare

[ Source](https://github.com/MichaelHoughton/silverstripe-importexport)[ Packagist](https://packagist.org/packages/michaelhoughton/silverstripe-importexport)[ RSS](/packages/michaelhoughton-silverstripe-importexport/feed)WikiDiscussions 2 Synced 1mo ago

READMEChangelogDependencies (4)Versions (3)Used By (0)

SilverStripe Import/Export Module
=================================

[](#silverstripe-importexport-module)

[![Build Status](https://camo.githubusercontent.com/1b77df4a35aced5c94fb2fd837f70ed8cd77c544bdfbec9b934a440d54986609/68747470733a2f2f7472617669732d63692e6f72672f6275726e6272696768742f73696c7665727374726970652d696d706f72746578706f72742e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/burnbright/silverstripe-importexport)

Import and export data from SilverStripe in various forms, including CSV. This module serves as a replacement/overhaul of BulkLoader functionality found in the framework.

This module is a fork of the [original](https://github.com/burnbright/silverstripe-importexport) module

The loading process
-------------------

[](#the-loading-process)

1. Raw data is retrieved from a source (`BulkLoaderSource`).
2. Data is provided as iterable rows (each row is heading->value mapped array).
3. Rows are mapped to a standardised format, based on a user/developer provided mapping.
4. Data is set/linked/tranformed onto a placeholder DataObject.
5. Existing record replaces placeholder, or placeholder becomes the brand new DataObject.
6. DataObject is validated and saved.
7. All results are stored in `BulkLoader_Result`.

User-defined column mapping
---------------------------

[](#user-defined-column-mapping)

Users can choose which columns map to DataObject fields. This removes any need to define headings, or headings according to a given schema. Users can state if the first line of data is in fact a heading row. Mappings are saved for the next time an import is done on the same GridField.

[![gridfieldimporter](https://cloud.githubusercontent.com/assets/1356335/7108697/24db13c4-e1e2-11e4-9ff1-86d42144201b.gif)](https://cloud.githubusercontent.com/assets/1356335/7108697/24db13c4-e1e2-11e4-9ff1-86d42144201b.gif)

Grid Field Importer
-------------------

[](#grid-field-importer)

This is a grid field component for users to selecting a CSV file and map it's columns to data fields.

```
$importer = new GridFieldImporter('before');
$gridConfig->addComponent($importer);
```

The importer makes use of the `CSVFieldMapper`, which displays the beginning content of a CSV.

BulkLoaderSource
----------------

[](#bulkloadersource)

A `BulkLoaderSource` provides an iterator to get record data from. Data could come from anywhere such as a CSV file, a web API, etc.

It can be used independently from the BulkLoader to obtain data.

```
$source = new CsvBulkLoaderSource();
$source->setFilePath("files/myfile.csv")
    ->setHasHeader(true)
    ->setFieldDelimiter(",")
    ->setFieldEnclosure("'");

foreach($source->getIterator() as $record){
    //do stuff
}
```

(Better)BulkLoader
------------------

[](#betterbulkloader)

- Saves data from a particular source and persists it to database via the ORM.
- Determines which fields can be mapped to, either scaffolded from the model, provided by configuration, or both.
- Detects existing records, and either skips or updates them, based on criteria.
- Maps the source data to new/existing dataobjects, based on a given mapping.
- Finds, creates, and connects relation objects to objects.
- Can clear all records prior to processing.

```
$source = new CsvBulkLoaderSource();
$source->setFilePath("files/myfile.csv");

$loader = new BetterBulkLoader("Product");
$loader->setSource($source);
$loader->addNewRecords = false;  // an option to skip new records

$result = $loader->load();
```

ListBulkLoader
--------------

[](#listbulkloader)

Often you'll want to confine bulk loading to a specific DataList. The ListBulkLoader is a variation of BulkLoader that adds and removes records from a given DataList. Of course DataList iself doesn't have an add method implemented, so you'll probably find it more useful for a `HasManyList`.

```
$category = ProductCategory::get()->first();

$source = new CsvBulkLoaderSource();
$source->setFilePath("productlist.csv");

$loader = new ListBulkLoader($category->Products());
$loader->setSource($source);

$result = $loader->load();
```

Mapping record data to a standard format
----------------------------------------

[](#mapping-record-data-to-a-standard-format)

You can provide a `columnMap` to map incoming records to a standard format.

```
$loader->columnMap = array(
    'first name' => 'FirstName',
    'Name' => 'FirstName',
    'bio' => 'Biography',
    'bday' => 'Birthday',
    'teamtitle' => 'Team.Title',
    'teamsize' => 'Team.TeamSize',
    'salary' => 'Contract.Amount'
);
```

This column map is generated by the `CSVFieldMapper` control inside the `GridFieldImporter` component.

Scaffolding vs Defining Mappable Fields
---------------------------------------

[](#scaffolding-vs-defining-mappable-fields)

Mappable fields will be scaffolded if you do not define them yourself. This includes fields that are on relations, so that relations can be linked up.

It is likely there will be fields you don't want mapped, in which case you should specify a `mappableFields` array on your loader:

```
$loader->mappableFields = array(
    'FirstName' => 'First Name',
    'Surname' => 'Last Name',
    'Biography' => 'Biography',
    'Birthday' => 'Birthday',
    'Team.Title' => 'Team'
);
```

Transform incoming record data
------------------------------

[](#transform-incoming-record-data)

You may want to perform some transformations to incoming record data. This can be done by specifying a callback against the record field name.

```
$loader->transforms = array(
    'Code' => array(
        'callback' => function($value, $placeholder) {
            //capitalize course codes
            return strtoupper($value);
        }
    )
);
```

Require specific data to be present
-----------------------------------

[](#require-specific-data-to-be-present)

Incoming records without required data will be skipped.

```
$loader->transforms = array(
    'Title' => array(
        'required' => true
    )
);
```

Note that empty records are skipped by default.

Creating and linking related DataObjects
----------------------------------------

[](#creating-and-linking-related-dataobjects)

The bulk loader can handle linking and creating `has_one` relationship objects, by either providing a callback, or using the `Relation.FieldName` style "dot notation". Relationship handling is also performed in the `transformations` array.

You can specify at the BulkLoader level if records will be created and linked, then you can also specify the behaviour for each field. The default behaviour is to both link and create relation objects.

Here are some configuration examples:

```
$loader->transforms = array(
    //link and create courses
    'Course.Title' = array(
        'link' => true,
        'create' => true
    ),
    //only link to existing tutors
    'Tutor.Name' => array(
        'link' => true,
        'create' => false
    ),
    //custom way to find parent courses
    'Parent' => array(
        'callback' => function($value, $placeholder) use ($self){
            return Course::get()
                ->filter("Title", $value)
                ->first();
        }
    )
);
```

Note that `$placeholder` in the above example refers to a dummy DataObject that is populated in order to then be saved, or checked against for duplicates. You should not call `$placeholder->write()` in your callback.

Specify a relation list
-----------------------

[](#specify-a-relation-list)

In the same way that you may use a `ListBulkLoader` to constrain records to a given DataList, you may also want to constrain the relation records to a List.

```
$loader->transforms = array(
    //link and create courses
    'Course.Title' = array(
        'list' => $self->Courses()
    )
);
```

Determining when to overwrite existing (duplicate) DataObjects
--------------------------------------------------------------

[](#determining-when-to-overwrite-existing-duplicate-dataobjects)

Duplicate checks are performed on record data, mapped into the standardised form.

You can perform duplicate checking on data fields:

```
//course is a duplicate when title is the same
$loader->duplicateChecks = array(
    "Title"
);
```

Or on a relation:

```
//course selection is a duplicate when course is the same
$loader->duplicateChecks = array(
    "Course.Title"
);
```

Duplicates can also be found using a callback function:

```
$loader->duplicateChecks = array(
    "FooBar" => array(
        "callback" => function($fieldName, $record) {
            if(!isset($record["FirstName"]) || !isset($record["LastName"])){
                return null;
            }

            return Person::get()
                ->filter("FirstName", $record['FirstName'])
                ->filter("LastName", $record['LastName'])
                ->first();
        }
    )
);
```

Publish pages during import
---------------------------

[](#publish-pages-during-import)

If you are importing instances of SiteTree, you can have those pages automatically published using this configuration:

```
$loader->setPublishPages(true);
```

Replace all the "legacy" ModelAdmin importers
---------------------------------------------

[](#replace-all-the-legacy-modeladmin-importers)

Some simple yaml config options to help with swapping out all the importer functionality.

```
ModelAdmin:
    removelegacyimporters: true
    addbetterimporters: true
```

Remove only the scafolded (non-custom) importers:

```
ModelAdmin:
    removelegacyimporters: scaffolded
```

Troubleshooting
---------------

[](#troubleshooting)

### Missing relation objects

[](#missing-relation-objects)

If you are writing relation objects during loading, and they fail validation, the loader will simply ignore that relation object.

### Multiple relation data fields not mapping to the same relation

[](#multiple-relation-data-fields-not-mapping-to-the-same-relation)

If you have mapped multiple fields mapping to the same relation, you may get situations where the incorrect existing relation object is joined. The first field that is mapped is the same field used to find the relation. For example, you'll likely want a Title to be used to find/create a relation, and then an Amount will be added to that same relation, rather than finding/creating a relation by an Amount, and setting the Title.

Define the correct ordering using the mappableFields array to fix this.

Contributions
-------------

[](#contributions)

Please do contribute whatever you can to this module. Check out the [issues](https://github.com/burnbright/silverstripe-importexport/issues) and [milestones](https://github.com/burnbright/silverstripe-importexport/milestones) to see what has needs to be done.

License
-------

[](#license)

MIT

Author
------

[](#author)

Jeremy Shipman ()

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 64.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~42 days

Total

3

Last Release

932d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/36ff0f925b41887978347c0ed99ee187131f647b9f50bffe91b4465b6e6d7b86?d=identicon)[MichaelHoughton](/maintainers/MichaelHoughton)

---

Top Contributors

[![jedateach](https://avatars.githubusercontent.com/u/1356335?v=4)](https://github.com/jedateach "jedateach (80 commits)")[![mlewis-everley](https://avatars.githubusercontent.com/u/687143?v=4)](https://github.com/mlewis-everley "mlewis-everley (26 commits)")[![wernerkrauss](https://avatars.githubusercontent.com/u/1043925?v=4)](https://github.com/wernerkrauss "wernerkrauss (6 commits)")[![MichaelHoughton](https://avatars.githubusercontent.com/u/5341149?v=4)](https://github.com/MichaelHoughton "MichaelHoughton (4 commits)")[![Zauberfisch](https://avatars.githubusercontent.com/u/186158?v=4)](https://github.com/Zauberfisch "Zauberfisch (3 commits)")[![patricknelson](https://avatars.githubusercontent.com/u/4269377?v=4)](https://github.com/patricknelson "patricknelson (2 commits)")[![AntonyThorpe](https://avatars.githubusercontent.com/u/1023740?v=4)](https://github.com/AntonyThorpe "AntonyThorpe (2 commits)")[![gregsmirnov](https://avatars.githubusercontent.com/u/584406?v=4)](https://github.com/gregsmirnov "gregsmirnov (1 commits)")

---

Tags

dataexportcsvimportbulkload

### Embed Badge

![Health badge](/badges/michaelhoughton-silverstripe-importexport/health.svg)

```
[![Health](https://phpackages.com/badges/michaelhoughton-silverstripe-importexport/health.svg)](https://phpackages.com/packages/michaelhoughton-silverstripe-importexport)
```

###  Alternatives

[maatwebsite/excel

Supercharged Excel exports and imports in Laravel

12.7k144.3M712](/packages/maatwebsite-excel)[league/csv

CSV data manipulation made easy in PHP

3.5k166.1M646](/packages/league-csv)[burnbright/silverstripe-importexport

An upgrade to SilverStripe's bulk loading and exporting

4534.1k1](/packages/burnbright-silverstripe-importexport)[goodby/csv

CSV import/export library

9555.6M23](/packages/goodby-csv)[sonata-project/exporter

Lightweight Exporter library

44920.9M35](/packages/sonata-project-exporter)[handcraftedinthealps/goodby-csv

CSV import/export library

441.6M4](/packages/handcraftedinthealps-goodby-csv)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)