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:
Skip to: Properties | Field types
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 |
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'
);
?>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')
);
?>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')
);
?>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'
);
?>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
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'
);
?>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
);
?>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')
);
?>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')
);
?>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'
);
?>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
);
?>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
);
?>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
Description: INTERNAL. Indicates that this field is a computer-generated copy of an alternate key field.
Values: Boolean.
Default value: NULL
Usage example: NONE
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
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
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
);
?>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
);
?>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
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
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())
);
?>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
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
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
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
);
?>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'
);
?>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
);
?>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
);
?>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
);
?>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
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')
);
?>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')
);
?>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
);
?>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