Importer

MMO\core\entities · 1 symbole · générée le 27 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

Espace de noms: MMO\core\entities
Implémente: 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. - existing: {string} (default: the importer's [`$existing`](https://mmoframework.fr/fr/documentation/mmo.core/php/entities/Importer.md#importer-existing), the configuration's `existing`) what the row does to an entity that already exists (found by its `@unique` values): `load` loads the row's values into it, as an update (a property of the row replaces the entity's whole, an embedded entity included); `fill` writes only what the entity has empty ([`Fill`](https://mmoframework.fr/fr/documentation/mmo.core/php/entities/Importer.md#importer-fill)): an entry made since the import is never overwritten. ## 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

	EXISTING_FILL	a row writes only what the entity found has empty (`Fill`)
	EXISTING_LOAD	a row loads its values into the entity found, as an update (`$existing`)
	UNDEFINED
	coercer	coercer to use to transform the raw data
	commit
	errors
	existing
	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}
	Fill($entity, $data) static	Write into an entity that exists only what it has empty (`EXISTING_FILL`, my.oviepro #342), property by property, never over a value: - an empty property (`IsEmpty`: null, blank, an empty arr…
	FillArray($current, $data) static
	fills($name)
	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
	IsEmpty($value) static
	isValidPath($path)	Check if a path is valid for a given entity variable
	jsonSerialize()
	keeps($row, $path)
	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.
	setExisting($existing)
	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

Constantes3

EXISTING_FILL

a row writes only what the entity found has empty (Fill)

const EXISTING_FILL = 'fill'

EXISTING_LOAD

a row loads its values into the entity found, as an update ($existing)

const EXISTING_LOAD = 'load'

UNDEFINED

const UNDEFINED = ''

Propriétés11

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

existing

string $existing = 'load'

Type: string

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

Méthodes37

Fill($entity, $data)

staticImporter.php:794

Write into an entity that exists only what it has empty ([`EXISTING_FILL`](https://mmoframework.fr/fr/documentation/mmo.core/php/entities/Importer.md#importer-existing-fill), my.oviepro #342), property by property, never over a value: - an empty property ([`IsEmpty`](https://mmoframework.fr/fr/documentation/mmo.core/php/entities/Importer.md#importer-isempty): null, blank, an empty array) takes the row's value; - an embedded entity, or a map, the entity has is filled the same way, field by field, instead of being replaced by the row's (a partial follow-up no longer erases its decision and its list); - anything else is kept: a value (`0` and `false` are values), a list with items, a reference to another entity (never followed: the other record is not changed).

static function Fill(MMO\core\classes\aEntity $entity, array $data): bool

`id`, `ctime` and `mtime` are the entity's own: never written. The values go through [`aEntity::loadArray`](https://mmoframework.fr/fr/documentation/mmo.core/php/classes/aEntity.md#aentity-loadarray), as the row's of an entity created.

$entity	aEntity	the entity found, or one of its embedded entities
$data	array	the row's values for it
retourne	bool	whether something was written

Importer::Fill($folder, ['note' => 'x', 'followUp' => ['rate' => 12]]); // the note if it has none, followUp/rate if empty

FillArray($current, $data)

staticImporter.php:829

protected static function FillArray(array $current, array $data): array

$current	array	a map an entity has
$data	array	the row's
retourne	array	$current with what it has empty taken from $data, deep (`Fill`)

fills($name)

Importer.php:489

function fills(string $name): bool

$name	string
retourne	bool	whether the row only fills variable $name's entity when it exists (its option `existing`, else `$existing`)

FromConfig($config, $debug)

staticImporter.php:275

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 existing: load|fill (@see $existing) 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
retourne	static

FromMultipleConfigs($configs, $debug)

staticImporter.php:292

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
retourne	array

getMapping()

Importer.php:562

function getMapping(): array

retourne

array

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

getOption($name, $key, $default)

Importer.php:512

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

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

getOptions($name)

Importer.php:502

function getOptions(string $name): array

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

getRelations()

Importer.php:519

function getRelations(): array

retourne

array

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

getRepositories()

Importer.php:353

function getRepositories(): array

retourne

array

every registered repository, keyed by id.

getRepository($id)

Importer.php:368

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

$id = 'main'	string
retourne	iRepository
lève		if $id isn't registered.

getVariablePaths($name)

Importer.php:443

function getVariablePaths(string $name): array

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

getVariableRepositoryName($name)

Importer.php:434

function getVariableRepositoryName(string $name): string

$name	string
retourne	string	the id (in `getRepositories`) of the repository $name's collection belongs to.
lève		if $name is unknown.

getVariables()

Importer.php:381

function getVariables(): array

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

getVariablesPaths()

Importer.php:456

function getVariablesPaths(): array

retourne array getVariablePaths for every declared variable.

hasVariable($name)

Importer.php:473

function hasVariable(string $name): bool

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

ignore($row, $key, $replaceBy)

Importer.php:871

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

Voir: 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
retourne	iEntity \| array \| null

IsEmpty($value)

staticImporter.php:843

static function IsEmpty(mixed $value): bool

$value	mixed	a property's
retourne	bool	whether nothing was entered in it (`Fill`): null, a blank string, an empty array

isValidPath($path)

Importer.php:305

Check if a path is valid for a given entity variable

function isValidPath(string $path): bool

$path	string	MUST start with the variable name
retourne	bool

jsonSerialize()

Importer.php:323

function jsonSerialize(): array

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

keeps($row, $path)

Importer.php:852

protected function keeps(ArrayAccess|array $row, string $path): bool

$row	ArrayAccess \| array	the row's variables
$path	string	a relation's path: its first segment is the variable it goes into
retourne	bool	whether that variable is an entity that exists and only gets what it has empty (`fills`)

loadXlsx($doc, $info, $debug)

Importer.php:914

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
retourne	`Document`

loopData($data, $options)

Importer.php:620

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
retourne	Generator

loopXlsx($doc, $info, $debug)

Importer.php:982

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
retourne	Generator	same shape as `loopData`.

removeVariable($name)

Importer.php:465

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
retourne	void

RepositoryController($coercer)

staticImporter.php:252

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`).
retourne	static

setExisting($existing)

Importer.php:481

function setExisting(string $existing): void

$existing	string	what a row does to an entity that already exists: `EXISTING_LOAD`, `EXISTING_FILL`
retourne	void
lève		for another value

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

Importer.php:594

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.
retourne	void
lève		if $type isn't a known coercer type, or a destination path is invalid.

setMapping($mapping, $debug)

Importer.php:572

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
retourne	void

setOptions($name, $options)

Importer.php:494

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

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

$name	string
$options	array
retourne	void

setRelation($variable, $paths)

Importer.php:550

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
retourne	void
lève		if $variable is unknown.
lève		if a path is invalid for its target variable.

setRelations($relations, $debug)

Importer.php:529

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
retourne	void
lève

setRepositories($repositories)

Importer.php:358

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

function setRepositories(array $repositories): void

$repositories	array
retourne	void

setRepository($repo, $id)

Importer.php:374

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

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

setVariable($name, $collection, $repository)

Importer.php:420

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.
retourne	void
lève		if $repository or $collection is unknown.

setVariables($variables, $debug)

Importer.php:391

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
retourne	void

__construct($repositories, $coercer)

Importer.php:241

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