Importer

MMO\core\entities · 1 symbol · generated 5 Oct 2026

class

Importer

Class used to import a list of raw data (organized in a map) into a list of entities.

class MMO\core\entities\Importer implements JsonSerializable

Namespace: MMO\core\entities
Implements: JsonSerializable

# Import configuration Let's consider we want to import data from a sql source, where a table is defined by this structure : | CPAM | | column | type | | ----- | ---- | | id | int | | code_cpam | int | | libelle | string | | email | string | | adresse | string | | code_postal | string | | ville | string | | code_cpam | string | The target entity to import the data into is defined by : | CPAM | | key | type | | ------ | ---- | | eid | int | | code | int | | email | string | | adresse | object | | Adresse | | key | type | | ------ | ---- | | complement | string | | numero | string | | voie | string | | codePostal | string | | ville | string | | pays | enum | The json configuration for the import will look like that: ```json { "coercer": "Oviepro\\atonline\\Coercer", "variables": { "cpam": { "name": "cpam", "repository": "main", "collection": "cpams", "options": [], "relations": [] } }, "mapping": [ { "source": "id", "target": "cpam\/eid", "type": "ignore-null", "options": [] }, { "source": "adresse", "target": [ "cpam\/adresse\/numero", "cpam\/adresse\/voie" ], "type": "adresse", "options": [] }, { "source": "code_cpam", "target": "cpam\/code", "type": "ignore-null", "options": [] }, { "source": "code_postal", "target": "cpam\/adresse\/codePostal", "type": "ignore-null", "options": [] }, { "source": "email", "target": "cpam\/email", "type": "ignore-null", "options": [] }, { "source": "libelle", "target": "cpam\/label", "type": "lettre-capitale", "options": [] }, { "source": "ville", "target": "cpam\/adresse\/ville", "type": "lettre-capitale", "options": [] } ] } ``` # Options ## variables You can define options for the variables. These options are used to change the way the variable is transformed into an entity. Valid options are : - create: {bool}(default true) if false, will only look for an existing entity. Else if the entity does not exist, it creates it. - default: {object} (default {}) the default values to inject into the entity. ## mapping These options are passed to the coercer and are used to help the coercion of the value. See `Coercers` help below. ## 1. Collections First of all, you need to define the variables entities, and the repository and collection in which they will be stored : `{'myvar1': ['myrepository', 'mycollection1'], 'myvar2': ['myrepository', 'mycollection2']}` ## 2. Coercers Then you define the coercers (transforming function) for the data to be imported. The key is the identifier of the coercer (type), the value is a function: `function(mixed $data, array $options): mixed` In options you have the options given by the map and : - `data`: {array} the current line of data being imported - `path`: {string} the current path in data - `type`: {string} the type to use to coerce the data - `target-path`: {string|array} the path to set the value at in the target import - `target`: {array} a reference on the imported data so far NOTE: a coercer MUST return an array of values in case the target-path is a list of path NOTE: To prevent a value from being imported return Importer::UNDEFINED NOTE: the coercer can directly change the imported data (`target`) as it is a reference. NOTE: the coercer can change the collection of a variable by setting the $COLLECTION key in the imported data (`target`) at the variable name: example: by setting $options['target']['myvar1']['$COLLECTION'] = ['myrepository', 'mycollection2'] or 'myrepository:mycollection2', `myvar1` will be created from `mycollection2` instead of `mycollection1` ## 3. Mapping Then you define the mapping between the raw data and the variables. Path are expressed as JSON path (with '/'). The key is the path in the raw data, the value is an array of : - a path in the destination variable (or multiple if the data needs to be sent to multiple places) - a string defining the identifier of a coercer (transforming function) that is used to convert the raw data into a valid value for the entity. null for direct value. - an array of options to pass to the coercer NOTE: to change the collection of a variable entity, set the `path` to `$COLLECTION` (format `{repository}:{collection}`) NOTE: the mapping is executed by order of declaration. ## 4. Relations Then you define the relations between the variables. For example `myvar2` could be a child of `myvar1` at the path `xxx/yyy` : `{'myvar2': 'myvar1/xxx/yyy'}` NOTE: it can also be a list of path if the variable belongs to multiple other variables. NOTE: to add `myvar2` to a list of `myvar1`, end your path with `*`. ex: `{'myvar2': 'myvar1/xxx'}` => `myvar2` will be pushed to property `xxx` of `myvar1` When pushing the value, a comparison of all the other entities present is done. The entity is then pushed only if it is not present.

Index

	UNDEFINED
	coercer	coercer to use to transform the raw data
	commit
	errors
	mapping	map of the mapping {source-path: [dest-path, type, options]}
	maxEmptyRows	define the max number of empty data encounter before stopping import
	options
	relations	map of the relations {variable-name: list of target path}.
	replaceEntity
	repositories	map of iRepository {name: iRepository}
	variables	map of variables {name: Collection}
	FromConfig($config, $debug) static	Load a configuration from a json file or an array.
	FromMultipleConfigs($configs, $debug) static	Load multiple importer from a json file or an array
	getMapping()
	getOption($name, $key, $default)
	getOptions($name)
	getRelations()
	getRepositories()
	getRepository($id)
	getVariablePaths($name)
	getVariableRepositoryName($name)
	getVariables()
	getVariablesPaths()
	hasVariable($name)
	ignore($row, $key, $replaceBy)	Remove entity from import NOTE: the ``-suffixed (list relation) branch had two compounding bugs: (1) it passed $path to
	isValidPath($path)	Check if a path is valid for a given entity variable
	jsonSerialize()
	loadXlsx($doc, $info, $debug)	Load importer configuration from xlsx document The document needs to have these pages: - `Import` on which the first line is a title for the column and the second line is the target path for the co…
	loopData($data, $options)	Loop through the rows of data
	loopXlsx($doc, $info, $debug)	Load an xlsx's configuration (`loadXlsx`) and import its data rows (the 'Import' sheet, starting at row 3 -- rows 1-2 are the column titles/target-path header, per `loadXlsx`).
	removeVariable($name)	Undeclare a variable (its mapping/relations/options, if any, are left in place -- only the variable itself is forgotten).
	RepositoryController($coercer) static	Build an Importer using every repository the app's `RepositoryController` already knows about.
	setMap($srcPath, $destPath, $type, $opts)	Declare how one source data path maps to one or more destination variable paths (`the` class docblock's "Mapping" section).
	setMapping($mapping, $debug)	Replace the whole mapping.
	setOptions($name, $options)	Replace variable $name's options (`getOption` -- e.g.
	setRelation($variable, $paths)	Declare where variable $variable itself belongs, within one or more OTHER variables (`the` class docblock's "Relations" section -- a path ending in `` pushes it into a list instead of a direct p…
	setRelations($relations, $debug)
	setRepositories($repositories)	Replace every registered repository.
	setRepository($repo, $id)	Register a repository under $id (default 'main').
	setVariable($name, $collection, $repository)	Declare an import variable and the collection its entities are created in.
	setVariables($variables, $debug)	Set the variables to import
	__construct($repositories, $coercer)	Constructor

Constants1

UNDEFINED

const UNDEFINED = ''

Properties10

coercer

coercer to use to transform the raw data

?MMO\core\interfaces\iCoercer $coercer = null

Type: null | iCoercer

commit

bool $commit = true

Type: bool

errors

array $errors = []

Type: array

mapping

map of the mapping {source-path: [dest-path, type, options]}

protected array $mapping = []

Type: array

maxEmptyRows

define the max number of empty data encounter before stopping import

?int $maxEmptyRows = null

Type: null | int

options

protected array $options = []

Type: array

relations

map of the relations {variable-name: list of target path}.

protected array $relations = []

Type: array

the target path starts with a variable's name and is followed by a valid path in that collection.

replaceEntity

bool $replaceEntity = true

Type: bool

repositories

map of iRepository {name: iRepository}

protected array $repositories = []

Type: array

variables

map of variables {name: Collection}

protected array $variables = []

Type: array

Methods31

FromConfig($config, $debug)

staticImporter.php:256

Load a configuration from a json file or an array.

static function FromConfig(array|string $config, bool $debug = false): static

Use the repositories given by the RepositoryController and get the coercer instance from its name in the configuration ```json { coercer: classname variables: [ {name, collection, repository, relations, options} ], mapping: [ {source, target, type, options} ] } ```

$config	array \| string
$debug = false	bool	if true, errors are added to this->errors instead of throwing exceptions
returns	static

FromMultipleConfigs($configs, $debug)

staticImporter.php:272

Load multiple importer from a json file or an array

static function FromMultipleConfigs(array|string $configs, bool $debug = false): array

$configs	array \| string	for each key of the config
$debug = false	bool	if true, errors are added to this->errors instead of throwing exceptions
returns	array

getMapping()

Importer.php:525

function getMapping(): array

returns

array

the raw mapping, source path => [destination path(s), coercer type, options].

getOption($name, $key, $default)

Importer.php:475

function getOption(string $name, string $key, mixed $default = null): mixed

$name	string
$key	string
$default = null	mixed
returns	mixed	one option of variable $name, or $default if unset.

getOptions($name)

Importer.php:465

function getOptions(string $name): array

$name	string
returns	array	variable $name's options.

getRelations()

Importer.php:482

function getRelations(): array

returns

array

every declared relation, variable name => its target path(s).

getRepositories()

Importer.php:332

function getRepositories(): array

returns

array

every registered repository, keyed by id.

getRepository($id)

Importer.php:347

function getRepository(string $id = 'main'): MMO\core\interfaces\iRepository

$id = 'main'	string
returns	iRepository
throws		if $id isn't registered.

getVariablePaths($name)

Importer.php:422

function getVariablePaths(string $name): array

$name	string
returns	array	every mapped destination path (relative to $name) that targets variable $name.

getVariableRepositoryName($name)

Importer.php:413

function getVariableRepositoryName(string $name): string

$name	string
returns	string	the id (in `getRepositories`) of the repository $name's collection belongs to.
throws		if $name is unknown.

getVariables()

Importer.php:360

function getVariables(): array

returns array every declared variable, name => its target collection (null for an embedded-only variable, see setVariable).

getVariablesPaths()

Importer.php:435

function getVariablesPaths(): array

returns array getVariablePaths for every declared variable.

hasVariable($name)

Importer.php:452

function hasVariable(string $name): bool

$name	string
returns	bool	whether $name is a declared variable.

ignore($row, $key, $replaceBy)

Importer.php:742

Remove entity from import NOTE: the ``-suffixed (list relation) branch had two compounding bugs: (1) it passed $path to

function ignore( array &$row, string $key, MMO\core\interfaces\iEntity|array|null $replaceBy = null ): MMO\core\interfaces\iEntity|array|null

See: get straight, WITH its literal trailing ` -- which isn't a real path segment (the loopData caller that builds these list relations always strips it first, via substr($path, 0, -2)), so get() could never find anything and always returned null, skipping the whole replacement; (2) even past that, get() returns arrays by VALUE, so splicing the returned $list only mutated a throwaway copy and was never written back into $row. Verified concretely that $entity stayed in the list and $replaceBy was never substituted in. Fixed to strip the suffix first and write the spliced list back via set`.

$row	array
$key	string
$replaceBy = null	iEntity \| array \| null
returns	iEntity \| array \| null

isValidPath($path)

Importer.php:285

Check if a path is valid for a given entity variable

function isValidPath(string $path): bool

$path	string	MUST start with the variable name
returns	bool

jsonSerialize()

Importer.php:303

function jsonSerialize(): array

returns array this importer's current configuration (collections/coercer types/variables/mapping, plus any $errors), in the same shape FromConfig accepts.

loadXlsx($doc, $info, $debug)

Importer.php:785

Load importer configuration from xlsx document The document needs to have these pages: - `Import` on which the first line is a title for the column and the second line is the target path for the column and an optional coercer type separated by a semi colon `:` ex: line 1: Name line 2: person/name:string - `Configuration` in which each line is a configuration key on the first column, followed by values on other column: - variables | name | collection | relation

function loadXlsx( MMO\core\documents\xlsx\Document|string $doc, array &$info = [], bool $debug = false ): MMO\core\documents\xlsx\Document

$doc	`Document` \| string
$info = []	array
$debug = false	bool
returns	`Document`

loopData($data, $options)

Importer.php:583

Loop through the rows of data

function loopData(iterable $data, array $options = []): Generator

YIELD {int} index in data (line) => {array[Entity]} the entities for that line with the injected data WARNING: in case an exception happen, it is yield at the line ({int} => {\Throwable})

$data	iterable	array[array[key: value]]
$options = []	array	options sent to the coercer
returns	Generator

loopXlsx($doc, $info, $debug)

Importer.php:853

Load an xlsx's configuration (loadXlsx) and import its data rows (the 'Import' sheet, starting at row 3 -- rows 1-2 are the column titles/target-path header, per loadXlsx).

function loopXlsx( MMO\core\documents\xlsx\Document|string $doc, array &$info = [], bool $debug = false ): Generator

$doc	`Document` \| string
$info = []	array
$debug = false	bool
returns	Generator	same shape as `loopData`.

removeVariable($name)

Importer.php:444

Undeclare a variable (its mapping/relations/options, if any, are left in place -- only the variable itself is forgotten).

function removeVariable(string $name): void

$name	string
returns	void

RepositoryController($coercer)

staticImporter.php:234

Build an Importer using every repository the app's RepositoryController already knows about.

static function RepositoryController(MMO\core\interfaces\iCoercer|string|null $coercer = null): static

$coercer = null	iCoercer \| string \| null	a coercer instance, or a class name to build one (via `getInstance`).
returns	static

setMap($srcPath, $destPath, $type, $opts)

Importer.php:557

Declare how one source data path maps to one or more destination variable paths (the class docblock's "Mapping" section).

function setMap( string $srcPath, array|string $destPath = '', ?string $type = null, array $opts = [] ): void

$srcPath	string	a JSON path into each imported row's raw data.
$destPath = ''	array \| string	one destination path (or several, for a coercer that splits one source value into multiple destinations), each starting with a variable name.
$type = null	null \| string	a registered `$coercer` type to convert the raw value, or null to use it as-is.
$opts = []	array	extra options passed to the coercer.
returns	void
throws		if $type isn't a known coercer type, or a destination path is invalid.

setMapping($mapping, $debug)

Importer.php:535

Replace the whole mapping.

function setMapping(array $mapping, bool $debug = false): void

$mapping	array	each an array with 'source', 'target', 'type' (optional), 'options' (optional) -- see `setMap`.
$debug = false	bool	if true, errors are added to `$errors` instead of throwing exceptions
returns	void

setOptions($name, $options)

Importer.php:457

Replace variable $name's options (getOption -- e.g. 'create'/'default').

function setOptions(string $name, array $options): void

$name	string
$options	array
returns	void

setRelation($variable, $paths)

Importer.php:513

Declare where variable $variable itself belongs, within one or more OTHER variables (the class docblock's "Relations" section -- a path ending in `` pushes it into a list instead of a direct property).

function setRelation(string $variable, string ...$paths): void

$variable	string
...$paths	string
returns	void
throws		if $variable is unknown.
throws		if a path is invalid for its target variable.

setRelations($relations, $debug)

Importer.php:492

function setRelations(array $relations, bool $debug = false): void

$relations	array
$debug = false	bool	if true, errors are added to this->errors instead of throwing exceptions
returns	void
throws

setRepositories($repositories)

Importer.php:337

Replace every registered repository. @param iRepository[] $repositories id => repository.

function setRepositories(array $repositories): void

$repositories	array
returns	void

setRepository($repo, $id)

Importer.php:353

function setRepository(MMO\core\interfaces\iRepository $repo, string $id = 'main'): void

$repo	iRepository
$id = 'main'	string
returns	void

setVariable($name, $collection, $repository)

Importer.php:399

Declare an import variable and the collection its entities are created in.

function setVariable(string $name, ?string $collection, string $repository = 'main'): void

$name	string
$collection	null \| string	the collection name, or null for a variable that's only ever embedded into another variable (no collection/entity-lookup of its own).
$repository = 'main'	string	which registered repository (`setRepository`) $collection belongs to.
returns	void
throws		if $repository or $collection is unknown.

setVariables($variables, $debug)

Importer.php:370

Set the variables to import

function setVariables(array $variables, bool $debug = false): void

$variables	array	[{name: {string}, collection: {string}, repository: {string}, relations: {string\|array\|null}, options: {create, class}}]
$debug = false	bool	if true, errors are added to this->errors instead of throwing exceptions
returns	void

__construct($repositories, $coercer)

Importer.php:223

Constructor

function __construct( MMO\core\interfaces\iRepository|array $repositories, ?MMO\core\interfaces\iCoercer $coercer = null )

$repositories	iRepository \| array	list of repositories to use. If only one, the repository has the id `main`
$coercer = null	null \| iCoercer	the coercer class to use