Documentation

Import extends ImportExport
in package

cloudrexx

lib

convert

Import Class Class which handles the main import operations

Properties

$em : EntityManager
$fieldNames : array<string|int, mixed>
$file : File|null
$internalDateTimeZone : DateTimeZone
$pairs : array<string|int, mixed>
$parser : Csv|null

Methods

__construct() : mixed: Initializes this component
cancel() : bool: Cancels the import operation
findBy() : array<string|int, mixed>: Gets a set of entities by class, import/export field mapping and values
findOneBy() : EntityBase: Gets an entity by class, import/export field mapping and values
findValueBy() : EntityBase: Gets an entity related to $entity by import/export field mapping and values
getFinalData() : array<string|int, mixed>: getFinalData
getUploadedFileFromUploader() : bool|string: Get uploaded csv file by using uploader id
importFromFile() : void: Imports a file into the database
initFieldSelectTemplate() : void: Sets the template for the field selection
initFileSelectTemplate() : void: Sets the template for the file selection
parseMapping() : array<string|int, mixed>: Parses data based on the mapping of fields from the file to import a single entity
uploadFinished() : array<string|int, mixed>: Uploader callback function
applyParams() : void: Applies params to a string
callCallback() : mixed: Calls a callback specified
getDataFields() : array<string|int, mixed>: Gets the fieldnames of the importing file
importToEntity() : void: Imports an entity based on the given mapping and data
parseFieldMapping() : mixed: Parses the field mapping for a single field
resolveCondition() : void: Extends a query builder by the necessary joins and conditions for a filter
resolveConditions() : void: See `resolveCondition()`
resolveFilterValues() : array<string|int, mixed>: Resolves the value part of a filter
setFieldPairs() : void: Sets the field Pairs
setFile() : void: Parses the file

$em


        protected
            EntityManager
    $em

Entity manager to use for imports

$fieldNames


        protected
            array<string|int, mixed>
    $fieldNames
     = array()

$file


        protected
            File|null
    $file
     = null

$internalDateTimeZone


        protected
            DateTimeZone
    $internalDateTimeZone

Interal timezone

$pairs


        protected
            array<string|int, mixed>
    $pairs
     = array()

$parser


        protected
            Csv|null
    $parser
     = null

__construct()

Initializes this component


    public
                    __construct(EntityManager $em, DateTimeZone $internalDateTimeZone) : mixed

Parameters

$em : EntityManager
$internalDateTimeZone : DateTimeZone

cancel()

Cancels the import operation


    public
                    cancel() : bool

Do not use this. Use ViewGenerator instead.

Return values

bool

findBy()

Gets a set of entities by class, import/export field mapping and values


    public
                    findBy(EntityManager $em, string $entityClass, array<string|int, mixed> $filter, array<string|int, mixed> $params[, int $limit = 0 ][, int $offset = 0 ]) : array<string|int, mixed>

See findOneBy(). This does the same but to get multiple entities.

Use-cases related to import/export:

Find all entities to be exported

Parameters

$em : EntityManager: Entity manager to use
$entityClass : string: Class of the entity to get
$filter : array<string|int, mixed>: Filter to parse
$params : array<string|int, mixed>: Additional params to parse in mapping
$limit : int = 0: (optional) Limits the number of results returned if set
$offset : int = 0: (optional) Sets the offset to start from if set

Return values

array<string|int, mixed> —

The entity collection found

findOneBy()

Gets an entity by class, import/export field mapping and values


    public
                    findOneBy(EntityManager $em, string $entityClass, array<string|int, mixed> $filter, array<string|int, mixed> $data, array<string|int, mixed> $params) : EntityBase

This resolves the field mapping to get a simple field/value array to match entities to. However, the field can be a path of entity properties to follow, split by ".". Additionally, a specific value for a property within the path can be supplied within square brackets ("[3]").

This can for example be used to get a user by a specific profile attribute matching a value:

findOneBy(
    $em,
    \Cx\Core\User\Model\Entity\User::class,
    array(
        'profile.attributes[3].value' => array(
            'fields' => array('myImportExportField'),
        ),
    ),
    $data = $myData,
    array()
)

The example above gets us a user ($entityClass) where the attribute 3 has the value specified in the import/export data. This follows the user's relation to the profile and its attributes.

Use-cases related to import/export:

Check whether the entity to import is already present in the DB

Parameters

$em : EntityManager: Entity manager to use
$entityClass : string: Class of the entity to get
$filter : array<string|int, mixed>: Filter to parse
$data : array<string|int, mixed>: Data from the import or export
$params : array<string|int, mixed>: Additional params to parse in mapping

Return values

EntityBase —

The single entity found

findValueBy()

Gets an entity related to $entity by import/export field mapping and values


    public
                    findValueBy(EntityBase $entity, string $propertyPath, array<string|int, mixed> $data, array<string|int, mixed> $params) : EntityBase

See findOneBy(). This does the same but based of a specific entity instead of a class name. This means that $filter does only have to point to a unique entity related to $entity instead of to a overall unique entity.

Use-cases related to import/export:

Set fields of related entites on import

Parameters

$entity : EntityBase: Entity to get relation of
$propertyPath : string
$data : array<string|int, mixed>: Data from the import or export
$params : array<string|int, mixed>: Additional params to parse in mapping

Return values

EntityBase —

The single entity found

getFinalData()

getFinalData


    public
                    getFinalData(array<string|int, mixed> $fields) : array<string|int, mixed>

Do not use this. Use ViewGenerator instead.

This function returns the associated fields and values.

Parameters

$fields : array<string|int, mixed>: Name of the fields

Return values

array<string|int, mixed>

getUploadedFileFromUploader()

Get uploaded csv file by using uploader id


    public
                    getUploadedFileFromUploader(string $uploaderId) : bool|string

Do not use this. Use ViewGenerator instead.

Parameters

$uploaderId : string: Uploader id

Return values

bool|string —

File path when file exists, false otherwise

importFromFile()

Imports a file into the database


    public
                    importFromFile(Cx $cx, array<string|int, mixed> $importConfig, File $file[, array<string|int, mixed> $params = array() ][, bool $profile = false ]) : void

$importConfig defines a reader for the file format (like CSV or XML) and how each of the read fields shall be converted before inserting into the database. $importConfig has the following format:

$importConfig = array(
     'fields' => <fieldConfig>,
     'importer' => <importer>,
     'className' => <className>,
     'batchSize' => <batchSize>,
     'behavior' => <behavior>,
     'idData' => <idData>',
);

<fieldConfig> is a config as specified by ImportExport::parseMapping(). <importer> is the name of the class to read the file format (instance of \Cx\Lib\Convert\Model\Entity\ImportInterface). <className> class name of the entities to import. Can be set to "Legacy::<componentName>::<controllerName>::<methodName>" to import into non-Doctrine tables. <batchSize> is an optional integer to set the batch size. Defaults to 1000. <behavior> is one of "truncate", "overwrite" and "skip". "truncate" will empty the table before importing. "overwrite" will overwrite attributes of any existing entries. "skip" will skip existing entries. For "overwrite" and "skip" you need to specify <idData>.

Parameters

$cx : Cx: instance to work on
$importConfig : array<string|int, mixed>: Config as specified above
$file : File: File to import data from
$params : array<string|int, mixed> = array(): (optional) Additional params as a key/value array that are available as
$profile : bool = false: (optional) If set to true this adds profiling output

initFieldSelectTemplate()

Sets the template for the field selection


    public
                    initFieldSelectTemplate(object &$tpl, mixed $given_fields) : void

Do not use this. Use ViewGenerator instead.

Parses the given file and sets the template and values for the field selection.

Parameters

$tpl : object: The template object (by reference)
$given_fields : mixed

initFileSelectTemplate()

Sets the template for the file selection


    public
                    initFileSelectTemplate(object &$tpl) : void

Do not use this. Use ViewGenerator instead.

Sets the template and all neede variables for the file selection.

Parameters

$tpl : object: The template object (by reference)

parseMapping()

Parses data based on the mapping of fields from the file to import a single entity


    public
                    parseMapping(array<string|int, mixed> $mapping, array<string|int, mixed> $importData, array<string|int, mixed> $params[, EntityBase|null $referenceEntity = null ]) : array<string|int, mixed>

This should not be public! $mapping is a list of entity properties. For each property you can specify how the value for it is generated based on the import data. The following options are available for the mapping:

'fields': A list of fields that need to be present in the import file. To make fields optional, set a default value for them, see 'defaultValue'.
'defaultValue': An optional list of fields specified in 'fields' as key with the respective default value as value.
'format': A string with '<...>'-style placeholders for the fields specified in 'fields'. This can be used to combine multiple fields to one.
'entity': Foreign entity for this field. See 'type' "entity".
'type': If set a type conversion will be applied. Known types are: "int": Result will be converted to int "DateTime": Result will be converted to \DateTime "entity": Result will be used as an argument to $em->find() on the repository for the entity specified in 'entity'.
'callback': Optional callback to do custom stuff. The callback is applied last, just before the type conversion and will be given the result of previous conversions as first param and all data fields to import as second param.

Either 'fields' or 'format' must be specified. If more than one field is specified, 'format' is mandatory.

$mapping = array(
     <entityProperty> => array(
         'fields' => array(...),
         'format' => '',
         'type' => '',
         'entity' => '',
         'defaultValue' => array(...),
         'callback' => function(string $formattedString, array $fields) {
             return $formattedString;
         }
     ),
     ...
)

Parameters

$mapping : array<string|int, mixed>: Mapping according to the description above
$importData : array<string|int, mixed>: Data to import
$params : array<string|int, mixed>: Additional params to parse in mapping
$referenceEntity : EntityBase|null = null

Return values

array<string|int, mixed> —

Parsed data to import

uploadFinished()

Uploader callback function


    public
            static        uploadFinished(string $tempPath, string $tempWebPath, array<string|int, mixed> $data, string $uploaderId, array<string|int, mixed> $fileInfos, object $response) : array<string|int, mixed>

Do not use this. Use ViewGenerator instead.

Parameters

$tempPath : string: Temp path
$tempWebPath : string: Temp web path
$data : array<string|int, mixed>: Uploader data
$uploaderId : string: Uploader id
$fileInfos : array<string|int, mixed>: Info about the file
$response : object: \Cx\Core_Modules\Uploader\Controller\UploadResponse

Return values

array<string|int, mixed> —

temp path and temp web path

applyParams()

Applies params to a string


    protected
                    applyParams(string &$string, array<string|int, mixed> $params) : void

$params is a key-value array. For each entry in $params "" is replaced by the value in $string.

Parameters

$string : string: (reference) String to apply params to
$params : array<string|int, mixed>: List of params to apply

callCallback()

Calls a callback specified


    protected
                    callCallback(array<string|int, mixed> $data, string $offset, array<string|int, mixed> $arguments) : mixed

Parameters

$data : array<string|int, mixed>: Array to get callback from
$offset : string: Offset, delimited by "/", of $data to get callback from
$arguments : array<string|int, mixed>: Arguments to pass to the callback

Return values

mixed —

Return value of the callback

getDataFields()

Gets the fieldnames of the importing file


    protected
                    getDataFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

$fields

importToEntity()

Imports an entity based on the given mapping and data


    protected
                    importToEntity(string $entityClassName, array<string|int, mixed> $mapping, array<string|int, mixed> $importData, Behavior $behavior, array<string|int, mixed> $idData[, array<string|int, mixed> $params = array() ][, bool $profiling = false ]) : void

Parameters

$entityClassName : string: Name of the entity class to create
$mapping : array<string|int, mixed>: Mapping as specified by ImportExport::parseMapping()
$importData : array<string|int, mixed>: Key/value list of fields with their values as present in the import file
$behavior : Behavior: How to behave regarding existing entities
$idData : array<string|int, mixed>: Data to identify existing entities by
$params : array<string|int, mixed> = array(): (optional) Can be used to pass additional data fields
$profiling : bool = false

parseFieldMapping()

Parses the field mapping for a single field


    protected
                    parseFieldMapping(array<string|int, mixed> $fieldMapping, array<string|int, mixed> $importData, string $debugFieldName, array<string|int, mixed> $params[, EntityBase|null $referenceEntity = null ]) : mixed

Parameters

$fieldMapping : array<string|int, mixed>: Mapping of the field
$importData : array<string|int, mixed>: Data to import
$debugFieldName : string: Name of the field to add to debug output
$params : array<string|int, mixed>: Additional params to parse in mapping
$referenceEntity : EntityBase|null = null

Return values

mixed —

Returns the mapped value. Its type depends on the mapping.

resolveCondition()

Extends a query builder by the necessary joins and conditions for a filter


    protected
                    resolveCondition(EntityManager $em, QueryBuilder $qb, string $entityClass, string $fieldPath, mixed $value, array<string|int, mixed> $params) : void

This turns a path and a value into a query part. The path could be something simple like "id" or something more complex like "profile.attributes[5]". The latter would match the ID field of the profile attribute with ID 5.

This assumes that "a" is the alias for the table in the main from clause. This may add relations to other tables and will alias them. To avoid conflicts it will start aliasing them at "aa" (going towards "az"). So "a" to "z" can be used outside this method without conflicts.

Parameters

$em : EntityManager: Entity manager to use
$qb : QueryBuilder: Query builder to extend
$entityClass : string: Class of the entity to get
$fieldPath : string: The path to the related field
$value : mixed: The value to match
$params : array<string|int, mixed>: Additional params to parse in mapping

resolveConditions()

See `resolveCondition()`


    protected
                    resolveConditions(EntityManager $em, QueryBuilder $qb, string $entityClass, array<string|int, mixed> $filter, array<string|int, mixed> $params) : void

Parameters

$em : EntityManager: Entity manager to use
$qb : QueryBuilder: Query builder to extend
$entityClass : string: Class of the entity to get
$filter : array<string|int, mixed>: Filter to parse
$params : array<string|int, mixed>: Additional params to parse in mapping

resolveFilterValues()

Resolves the value part of a filter


    protected
                    resolveFilterValues(array<string|int, mixed> $filter, array<string|int, mixed> $data, bool &$simple, array<string|int, mixed> $params) : array<string|int, mixed>

This simply replaces the values using the import mapping. Doing this might lead to recursion.

Parameters

$filter : array<string|int, mixed>: Filter to parse
$data : array<string|int, mixed>: Data from the import or export
$simple : bool: Set to true if there's no advanced filter present, false otherwise
$params : array<string|int, mixed>: Additional params to parse in mapping

Return values

array<string|int, mixed> —

The updated filter with resolved values

setFieldPairs()

Sets the field Pairs


    protected
                    setFieldPairs(array<string|int, mixed> $left_fields, array<string|int, mixed> $right_fields) : void

Parameters

$left_fields : array<string|int, mixed>
$right_fields : array<string|int, mixed>

setFile()

Parses the file


    protected
                    setFile(string $file) : void

Parameters

$file : string: Path to the csv file

Import extends ImportExport in package cloudrexx lib convert

Tags

Table of Contents

Properties

Methods

Properties

$em

$fieldNames

$file

$internalDateTimeZone

$pairs

$parser

Methods

__construct()

Parameters

Tags

cancel()

Return values

findBy()

Parameters

Tags

Return values

findOneBy()

Parameters

Tags

Return values

findValueBy()

Parameters

Tags

Return values

getFinalData()

Parameters

Return values

getUploadedFileFromUploader()

Parameters

Return values

importFromFile()

Parameters

Tags

initFieldSelectTemplate()

Parameters

initFileSelectTemplate()

Parameters

parseMapping()

Parameters

Return values

uploadFinished()

Parameters

Return values

applyParams()

Parameters

callCallback()

Parameters

Tags

Return values

getDataFields()

Return values

importToEntity()

Parameters

Tags

parseFieldMapping()

Parameters

Tags

Return values

resolveCondition()

Parameters

resolveConditions()

Parameters

resolveFilterValues()

Parameters

Return values

setFieldPairs()

Parameters

setFile()

Parameters

Import extends ImportExport
in package

cloudrexx

lib

convert