Version: current

# Class BulkLoader

A base for bulk loaders of content into the SilverStripe database. Bulk loaders give SilverStripe authors the ability to do large-scale uploads into their Sapphire databases.

You can configure column-handling,

  Object
  ViewableData implements IteratorAggregate
  BulkLoader

### Direct known subclasses

`CsvBulkLoader`

### Indirect known subclasses

`GroupCsvBulkLoader`, `MemberCsvBulkLoader`

Abstract
Package: cms\bulkloading
Author: Ingo Schommer, Silverstripe Ltd. (<firstname>@silverstripe.com)
See: http://rfc.net/rfc4180.html
Located at sapphire/dev/BulkLoader.php

## Methods summary

`public` | # `__construct( mixed $objectClass )` #### Overrides `Object::__construct`
`public` | # `load( mixed $filepath )`
`public array` | # `preview( string $filepath )` Preview a file import (don't write anything to the database). Useful to analyze the input and give the users a chance to influence it through a UI. Preview a file import (don't write anything to the database). Useful to analyze the input and give the users a chance to influence it through a UI. #### Parameters $filepath string $filepath Absolute path to the file we're importing #### Returns `array` See `BulkLoader::processAll()`
`abstract protected `BulkLoader_Result`` | # `processAll( string $filepath, boolean $preview = false )` Process every record in the file Process every record in the file #### Parameters $filepath string $filepath Absolute path to the file we're importing (with UTF8 content) $preview boolean $preview If true, we'll just output a summary of changes but not actually do anything #### Returns ``BulkLoader_Result`` A collection of objects which are either created, updated or deleted. 'message': free-text string that can optionally provide some more information about what changes have
`abstract protected` | # `processRecord( array $record, array $columnMap, mixed & $result, boolean $preview = false )` Process a single record from the file. Process a single record from the file. #### Parameters $record array $record An map of the data, keyed by the header field defined in `BulkLoader::$columnMap` $columnMap array $columnMap $result $result BulkLoader_Result (passed as reference) $preview boolean $preview
`public` | # `getOptionFields( )` Return a FieldSet containing all the options for this form; this doesn't include the actual upload field itself Return a FieldSet containing all the options for this form; this doesn't include the actual upload field itself
`public string` | # `Title( )` Return a human-readable name for this object. It defaults to the class name can be overridden by setting the static variable $title Return a human-readable name for this object. It defaults to the class name can be overridden by setting the static variable $title #### Returns `string` string
`public array` | # `getImportSpec( )` Get a specification of all available columns and relations on the used model. Useful for generation of spec documents for technical end users. Get a specification of all available columns and relations on the used model. Useful for generation of spec documents for technical end users. Return Format:
    array(
      'fields' => array('myFieldName'=>'myDescription'),
      'relations' => array('myRelationName'=>'myDescription'),
    )
#### Returns `array` array
`protected boolean` | # `isNullValue( mixed $val, string $fieldName = null )` Determines if a specific field is null. Can be useful for unusual "empty" flags in the file, e.g. a "(not set)" value. The usual DBField::isNull() checks apply when writing the `DataObject`, so this is mainly a customization method. Determines if a specific field is null. Can be useful for unusual "empty" flags in the file, e.g. a "(not set)" value. The usual DBField::isNull() checks apply when writing the `DataObject`, so this is mainly a customization method. #### Parameters $val mixed $val $fieldName string $field Name of the field as specified in the array-values for `BulkLoader::$columnMap`. #### Returns `boolean` boolean

### Methods inherited from ViewableData

`ATT_val()`, `BaseHref()`, `CSSClasses()`, `ColumnBreak()`, `ColumnCalc()`, `ColumnNumber()`, `ColumnPad()`, `ColumnPos()`, `CurrentMember()`, `CurrentPage()`, `Debug()`, `Even()`, `EvenOdd()`, `First()`, `FirstLast()`, `HasPerm()`, `IsAjax()`, `JS_val()`, `Last()`, `Me()`, `Middle()`, `MiddleString()`, `Modulus()`, `MultipleOf()`, `Odd()`, `Pos()`, `RAW_val()`, `SQL_val()`, `ThemeDir()`, `ThemeName()`, `Top()`, `TotalItems()`, `XML_val()`, `__get()`, `__isset()`, `__set()`, `buildCastingCache()`, `cachedCall()`, `castingClass()`, `castingHelper()`, `castingHelperPair()`, `castingObjectCreator()`, `castingObjectCreatorPair()`, `customise()`, `defineMethods()`, `escapeTypeForField()`, `getField()`, `getIterator()`, `getSecurityID()`, `getXMLValues()`, `hasField()`, `hasValue()`, `i18nLocale()`, `iteratorProperties()`, `obj()`, `renderWith()`, `setCustomisedObj()`, `setField()`

### Methods inherited from Object

`__call()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `exists()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Magic methods summary

## Properties summary

`public string` | $objectClass | # Each row in the imported dataset should map to one instance of this class (with optional property translation through {@self::$columnMaps}. Each row in the imported dataset should map to one instance of this class (with optional property translation through {@self::$columnMaps}.
`public static string` | $title | # Override this on subclasses to give the specific functions names. Override this on subclasses to give the specific functions names.
`public array` | $columnMap | # Map columns to DataObject-properties. If not specified, we assume the first row in the file contains the column headers. The order of your array should match the column order. Map columns to DataObject-properties. If not specified, we assume the first row in the file contains the column headers. The order of your array should match the column order. The column count should match the count of array elements, fill with NULL values if you want to skip certain columns. You can also combine $hasHeaderRow = true and `BulkLoader::$columnMap` and omit the NULL values in your map. Supports one-level chaining of has_one relations and properties with dot notation (e.g. Team.Title). The first part has to match a has_one relation name (not necessarily the classname of the used relation).
    <?php
            // simple example
     array(
            'Title',
                    'Birthday'
            )

    // complex example
            array(
                    'first name' => 'FirstName', // custom column name
                    null, // ignored column
                    'RegionID', // direct has_one/has_many ID setting
                    'OrganisationTitle', // create has_one relation to existing record using $relationCallbacks
                    'street' => 'Organisation.StreetName', // match an existing has_one or create one and write property.
            );
    ?>
`public array` | $relationCallbacks | # Find a has_one relation based on a specific column value. Find a has_one relation based on a specific column value.
    <?php
    array(
                    'OrganisationTitle' => array(
                            'relationname' => 'Organisation', // relation accessor name
                            'callback' => 'getOrganisationByTitle',
            );
    );
    ?>
`public array` | $duplicateChecks | # Specifies how to determine duplicates based on one or more provided fields in the imported data, matching to properties on the used `DataObject` class. Alternatively the array values can contain a callback method (see example for implementation details). The callback method should be defined on the source class. Specifies how to determine duplicates based on one or more provided fields in the imported data, matching to properties on the used `DataObject` class. Alternatively the array values can contain a callback method (see example for implementation details). The callback method should be defined on the source class. NOTE: If you're trying to get a unique Member record by a particular field that isn't Email, you need to ensure that Member is correctly set to the unique field you want, as it will merge any duplicates during `Member::onBeforeWrite()`. `Member::set_unique_identifier_field()`. If multiple checks are specified, the first one "wins".
    <?php
    array(
                    'customernumber' => 'ID',
                    'phonenumber' => array(
                            'callback' => 'getByImportedPhoneNumber'
                    )
    );
    ?>
`public `Boolean`` | $deleteExistingRecords | # $clearBeforeImport Delete ALL records before importing. $clearBeforeImport Delete ALL records before importing.

### Properties inherited from ViewableData

`$casting`, `$customisedObject`, `$default_cast`, `$failover`, `$iteratorPos`, `$iteratorTotalItems`

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -