# Import / Export API Reference

This document provides a programmer's reference to the Drupal Import / Export API. If you're interested in step-by-step documentation to help you utilise the API, please see the Import / Export API QuickStart guide.

See also the reference guides for the bundled engines:

- db engines
- csv engines
- xml engines

Skip to: Properties | Field types

## Fields and properties matrix

Legend:
X = property can be used with this field type
- = this property is not applicable to this field type

#type | array | datetime | entity | file | float | freeform | int | serialized | string
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
#alt_key_for | - | - | - | - | - | - | X | - | X
#alt_key_ignore | - | - | - | - | - | - | X | - | X
#default_value | - | X | - | X | X | X | X | X | X
#dependencies | - | - | X | - | - | - | - | - | -
#generated | - | - | - | - | - | - | X | - | X
#get | X | X | X | X | X | X | X | X | X
#id | X | X | X | X | X | X | X | X | X
#key | - | - | - | - | - | - | X | - | -
#key_component | - | - | - | - | - | - | X | - | X
#keys | X | - | X | - | - | - | - | - | -
#parents | X | X | X | X | X | X | X | X | X
#process | X | X | X | X | X | X | X | X | X
#processed_get | X | X | X | X | X | X | X | X | X
#processed_put | X | X | X | X | X | X | X | X | X
#put | X | X | X | X | X | X | X | X | X
#reference_delta | - | - | - | - | - | - | X | - | X
#reference_entity | - | - | - | - | - | - | X | - | X
#reference_field | - | - | - | - | - | - | X | - | X
#reference_parent | - | - | - | - | - | - | X | - | X
#required | - | X | - | X | X | X | X | X | X
#source | - | - | X | - | - | - | - | - | -
#title | X | X | X | X | X | X | X | X | X
#type | X | X | X | X | X | X | X | X | X
#unique | - | X | - | X | X | X | X | X | X
#value | X | X | - | X | X | X | X | X | X

## Field types

### array

Description: Container for one or more child fields. Array fields are used for grouping together fields that may have more than one instance, and that have a parent-child relationship with their parent entity or array. An array field can have either an entity field or another array field as its parent. An array field can have fields of any type, except for entity, as its children.

Properties: #get, #id, #keys, #parents, #process, #processed_get, #processed_put, #put, #title, #type, #value.

Usage example: (importexportapi_node.inc):

`<?php
$def['revisions'] = array(
'#type' => 'array',
'#title' => t('Revisions'),
'#db_default_table' => 'node_revisions',
'#xml_plural' => 'revisions',
'#xml_mapping' => 'revision',
'#csv_plural' => 'node-revisions'
);
?>`

### datetime

Description: A timestamp in standard UNIX timestamp format. The timestamp is converted to and from an RFC-2822 string representation when using most 'get' and 'put' formats (e.g. XML).

Properties: #default_value, #get, #id, #parents, #process, #processed_get, #processed_put, #put, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_user.inc):

`<?php
$def['created'] = array(
'#type' => 'datetime',
'#title' => t('Member since')
);
?>`

### entity

Description: Top-level container for all other fields. Entity fields are used for grouping together fields that describe a single entity, and that may have more than one instance. An entity field cannot have a parent, and it can have fields of any type as its children.

Properties: #dependencies, #get, #id, #keys, #parents, #process, #processed_get, #processed_put, #put, #source, #title, #type.

Usage example: (importexportapi_node.inc):

`<?php
$def['created'] = array(
'#type' => 'datetime',
'#title' => t('Member since')
);
?>`

### file

Description: A string specifying the path to a file. Currently, this field has no special behaviour to differentiate it from a regular string field. In future, this field will be used for assisting in automated file imports.

Properties: #default_value, #get, #id, #parents, #process, #processed_get, #processed_put, #put, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_system.inc):

`<?php
$def['file_path'] = array(
'#type' => 'file',
'#title' => t('File path'),
'#db_field_unaliased' => 'filepath'
);
?>`

### float

Description: A real number (also known as a floating-point number).

Properties: #default_value, #get, #id, #parents, #process, #processed_get, #processed_put, #put, #required, #title, #type, #unique, #value.

Usage example: NONE

### freeform

Description: A list in delimited string format. The string can be either line-delimited or comma-delimited. The list is converted to and from a tree structure when using some 'get' and 'put' formats (e.g. XML).

Properties: #default_value, #get, #id, #parents, #process, #processed_get, #processed_put, #put, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_user.inc):

`<?php
$def['perm'] = array(
'#type' => 'freeform',
'#title' => t('Permission list'),
'#default_value' => NULL,
'#xml_plural' => 'permissions',
'#csv_plural' => 'permissions',
'#db_table' => 'permission'
);
?>`

### int

Description: An integral number (also known as a whole number).

Properties: #alt_key_for, #alt_key_ignore, #default_value, #generated, #get, #id, #key, #key_component, #parents, #process, #processed_get, #processed_put, #put, #reference_delta, #reference_entity, #reference_field, #reference_parent, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_user.inc):

`<?php
$def['uid'] = array(
'#type' => 'int',
'#title' => t('User ID'),
'#key' => TRUE,
'#db_uses_sequences' => TRUE
);
?>`

### serialized

Description: A PHP variable in serialized string format. The string is converted to and from a tree structure when using some 'get' and 'put' formats (e.g. XML).

Properties: #default_value, #get, #id, #parents, #process, #processed_get, #processed_put, #put, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_system.inc):

`<?php
$def['value'] = array(
'#type' => 'serialized',
'#title' => t('Variable value')
);
?>`

### string

Description: A string of text. Note: this is the default field type if none is specified.

Properties: #alt_key_for, #alt_key_ignore, #default_value, #generated, #get, #id, #key_component, #parents, #process, #processed_get, #processed_put, #put, #reference_delta, #reference_entity, #reference_field, #reference_parent, #required, #title, #type, #unique, #value.

Usage example: (importexportapi_user.inc):

`<?php
$def['pass'] = array(
'#title' => t('Password')
);
?>`

## Properties

### #alt_key_for

Used by: int, string.

Description: The name of the field for which this field is an alternate key. The field being named must be either a #key or a #key_component field. All fields with this property set are implicitly #unique.

Values: A field name. The parents of the alternate key field cannot be specfied; instead, it is assumed that the alternate key field is a sibling of this field.

Default value: NULL

Usage example: (importexportapi_user.inc):

`<?php
$def['name'] = array(
'#title' => t('Username'),
'#alt_key_for' => 'uid'
);
?>`

### #alt_key_ignore

Used by: int, string.

Description: The names of alternate key fields (of the field that this field is referencing) that should NOT be copied and generated as siblings of this field. Should only be used by fields that specify a #reference_entity.

Values: Either an array of alternate key field names, or boolean TRUE to indicate all alternate key fields.

Default value: NULL

Usage example: (importexportapi_user.inc):

`<?php
$def['auth']['uid'] = array(
'#type' => 'int',
'#title' => t('User ID'),
'#reference_entity' => 'user',
'#alt_key_ignore' => array('name')
);
$def['auth']['authname'] = array(
'#title' => t('Auth name'),
'#reference_entity' => 'user',
'#reference_field' => array('name'),
'#alt_key_ignore' => TRUE
);
?>`

### #default_value

Used by: ALL types except entity, array.

Description: The value of the field that will be used if #value is NULL or undefined. Should NOT be confused with #value, which is the actual value that can be explicitly provided.

Values: Mixed.

Default value: Different for each field type.

Usage example: (importexportapi_node.inc):

`<?php
$def['status'] = array(
'#type' => 'int',
'#title' => t('Published'),
'#default_value' => 1
);
?>`

### #dependencies

Used by: entity.

Description: INTERNAL. The entities that this entity depends on. This is determined automatically, by looking for fields that reference other fields in other entities.

Values: Array of entity field names.

Default value: empty array

Usage example: NONE

### #generated

Used by: int, string.

Description: INTERNAL. Indicates that this field is a computer-generated copy of an alternate key field.

Values: Boolean.

Default value: NULL

Usage example: NONE

### #get

Used by: ALL

Description: INTERNAL. Contains engine-specific properties that have been configured for use in a 'get' operation. The properties inside are generally inherited from their equivalent top-level properties, unless they have been explicitly set. Although this property is internally generated, the properties inside it are considered public, and can (and should) be changed by other modules that utilise import / export API functionality.

Values: Mixed.

Default value: NULL

Usage example: NONE

### #id

Used by: ALL

Description: INTERNAL. The field's id property, which is determined by the key of the field as declared in a data definition.

Values: String.

Default value: n/a

Usage example: NONE

### #key

Used by: int.

Description: Specifies that this field is the unique, database-generated, integer identifier for the entity or array of which it is a part. A maximum of one field per entity or array can be a key field For example, if "x" is an entity, "y" is an array that is the child of "x", and "z" is an array that is the child of "y", then "x", "y", and "z" can each have a maximum of one key field. Should NOT be used by fields that specify a #reference_entity.

Values: Boolean.

Default value: NULL

Usage example: (importexportapi_node.inc):

`<?php
$def['nid'] = array(
'#type' => 'int',
'#title' => t('Node ID'),
'#key' => TRUE,
'#db_uses_sequences' => TRUE
);
?>`

### #key_component

Used by: int, string.

Description: Specifies that this field is one of the fields that makes up the unique identifier for the entity or array of which it is a part. The unique identifier for each entity or array consists of the #key field (if any), plus all key_component fields. If no #key field is specified for an entity or array, then at least one field must be a key_component.

Values: Boolean.

Default value: NULL

Usage example: (importexportapi_taxonomy.inc):

`<?php
$def['parents']['tid'] = array(
'#type' => 'int',
'#title' => t('Term ID'),
'#reference_entity' => 'term',
'#alt_key_ignore' => TRUE,
'#key_component' => TRUE
);
?>`

### #keys

Used by: entity, array.

Description: INTERNAL. The list of fields that make up the unique identifier for this entity or array field. This list consists of all #key or #key_component fields that are direct children of this field.

Values: Array of field names.

Default value: n/a

Usage example: NONE

### #parents

Used by: ALL

Description: INTERNAL. The parents of the current field. This field is always an empty array for entities.

Values: Array of field names, in order from most distant parent to least distant (i.e. direct) parent.

Default value: empty array

Usage example: NONE

### #process

Used by: ALL

Description: The callback functions to use when executing the 'process' hook on this field. The callback functions are executed in the order in which they are listed. Note: if this field is of a type that specifies a default set of callback functions, then all callback functions specified here will be appended to the default list, and will not replace the default list.

Values: Array of callback functions, in the form 'function_name' => array('arguments').

Default value: Different for each field type.

Usage example: (importexportapi_user.inc):

`<?php
$def = array(
'#type' => 'entity',
'#title' => t('User role'),
'#xml_plural' => 'roles',
'#csv_plural' => 'roles',
'#process' => array('_importexportapi_user_process_role' => array())
);
?>`

### #processed_get

Used by: ALL

Description: INTERNAL. Indicates whether or not the 'process' hook has been executed for for this field during the current 'get' operation.

Values: Boolean.

Default value: NULL

Usage example: NONE

### #processed_put

Used by: ALL

Description: INTERNAL. Indicates whether or not the 'process' hook has been executed for for this field during the current 'put' operation.

Values: Boolean.

Default value: NULL

Usage example: NONE

### #put

Used by: ALL

Description: INTERNAL. Contains engine-specific properties that have been configured for use in a 'put' operation. The properties inside are generally inherited from their equivalent top-level properties, unless they have been explicitly set. Although this property is internally generated, the properties inside it are considered public, and can (and should) be changed by other modules that utilise import / export API functionality.

Values: Mixed.

Default value: NULL

Usage example: NONE

### #reference_delta

Used by: int, string.

Description: If separate instances of a particular entity or array are referenced by multiple fields that are children of the same entity or array, then each referencing field will need to set a different delta value. This allows for a separate join to be performed on each instance, when executing database queries on the entity or array that is the parent of this field.

Values: Integer (must be > 0).

Default value: NULL

Usage example: (importexportapi_taxonomy.inc):

`<?php
$def['parents']['parent_tid'] = array(
'#type' => 'int',
'#title' => t('Parent term ID'),
'#reference_entity' => 'term',
'#reference_field' => array('tid'),
'#db_field_unaliased' => 'parent',
'#key_component' => TRUE,
'#reference_delta' => 1,
'#reference_parent' => FALSE,
'#alt_key_ignore' => TRUE
);
?>`

### #reference_entity

Used by: int, string.

Description: The name of the entity that is the parent (direct or non-direct) of the field that this field is referencing. This is the only field that is required in order to define a field as a reference to another field.

Values: An entity field name.

Default value: NULL

Usage example: (importexportapi_node.inc):

`<?php
$def['uid'] = array(
'#type' => 'int',
'#title' => t('User ID'),
'#reference_entity' => 'user'
);
?>`

### #reference_field

Used by: int, string.

Description: The field that this field is referencing. Should only be used by fields that specify a #reference_entity. Defaults to the unique identifying name of this field. This property only needs to be specified if the unique identifying name of this field is different to the unique identifying name of the field being referenced, or if the field being referenced is not the direct child of an entity (i.e. if it is the direct child of an array).

Values: An array of field names, that consists of the names of all the parents of the referencing field (except for its parent entity), and the name of the referencing field itself, in order from the most distant parent to the actual referenced field.

Default value: NULL

Usage example: (importexportapi_user.inc):

`<?php
$def['perm_rid'] = array(
'#type' => 'int',
'#title' => t('Role ID'),
'#reference_entity' => 'role',
'#reference_field' => array('rid'),
'#db_table' => 'permission',
'#db_field_unaliased' => 'rid',
'#key_component' => TRUE,
'#csv_hidden' => TRUE
);
?>`

### #reference_parent

Used by: int, string.

Description: Allows this field to NOT be a reference to a field within its parent's parent. By default, all fields that reference a field within the parent entity or array of their parent are used for parent-child linking. Setting this value to FALSE will reverse this behaviour, and will stop this field from being used for parent-child linking. This property should generally be used in conjunction with #reference_delta.

Values: Boolean.

Default value: NULL

Usage example: (importexportapi_taxonomy.inc):

`<?php
$def['parents']['parent_tid'] = array(
'#type' => 'int',
'#title' => t('Parent term ID'),
'#reference_entity' => 'term',
'#reference_field' => array('tid'),
'#db_field_unaliased' => 'parent',
'#key_component' => TRUE,
'#reference_delta' => 1,
'#reference_parent' => FALSE,
'#alt_key_ignore' => TRUE
);
?>`

### #required

Used by: ALL types except entity, array.

Description: Specifies that a field is required to have a value (other than its #default_value). Note: this is not currently enforced or validated in the API.

Values: Boolean.

Default value: FALSE

Usage example: (importexportapi_user.inc):

`<?php
$def['auth']['module'] = array(
'#title' => t('Auth module'),
'#required' => TRUE
);
?>`

### #source

Used by: entity.

Description: The engine to be used for accessing the source of data for this entity.

Values: String.

Default value: db

Usage example: NONE

### #title

Used by: ALL

Description: The title of the field. Make sure to enclose inside the t() function so this property can be translated. Note: this is the only property that is required explicitly and universally, for all field types.

Values: String.

Default value: n/a

Usage example: (importexportapi_user.inc):

`<?php
$def['pass'] = array(
'#title' => t('Password')
);
?>`

### #type

Used by: ALL

Description: Used to determine the type of field.

Values: String.

Default value: string

Usage example: (importexportapi_user.inc):

`<?php
$def['created'] = array(
'#type' => 'int',
'#title' => t('Member since')
);
?>`

### #unique

Used by: ALL types except entity, array.

Description: Used to determine if all instances of this field must be unique.

Values: Boolean.

Default value: NULL

Usage example: (importexportapi_node.inc):

`<?php
$def['vid'] = array(
'#type' => 'int',
'#title' => t('Revision ID'),
'#reference_entity' => 'node',
'#reference_field' => array('revisions', 'vid'),
'#unique' => TRUE
);
?>`

### #value

Used by: ALL types except entity.

Description: INTERNAL. This is where the actual values of a field are placed during a 'get' operation, and it is where they are retrieved from during a 'put' operation.

Values: Mixed.

Default value: NULL

Usage example: NONE