<?php

/**

 * @file

 * Field CRUD API, handling field and field instance creation and deletion.

 */

/**

 * @defgroup field_crud Field CRUD API

 * @{

 * Create, update, and delete Field API fields, bundles, and instances.

 *

 * Modules use this API, often in hook_install(), to create custom

 * data structures. UI modules will use it to create a user interface.

 *

 * The Field CRUD API uses

 * @link field Field API data structures @endlink.

 *

 * See @link field Field API @endlink for information about the other parts of

 * the Field API.

 */

/**

 * Creates a field.

 *

 * This function does not bind the field to any bundle; use

 * field_create_instance() for that.

 *

 * @param $field

 *   A field definition array. The field_name and type properties are required.

 *   Other properties, if omitted, will be given the following default values:

 *   - cardinality: 1

 *   - locked: FALSE

 *   - indexes: the field-type indexes, specified by the field type's

 *     hook_field_schema(). The indexes specified in $field are added

 *     to those default indexes. It is possible to override the

 *     definition of a field-type index by providing an index with the

 *     same name, or to remove it by redefining it as an empty array

 *     of columns. Overriding field-type indexes should be done

 *     carefully, for it might seriously affect the site's performance.

 *   - settings: each omitted setting is given the default value defined in

 *     hook_field_info().

 *   - storage:

 *     - type: the storage backend specified in the 'field_storage_default'

 *       system variable.

 *     - settings: each omitted setting is given the default value specified in

 *       hook_field_storage_info().

 *

 * @return

 *   The $field array with the id property filled in.

 *

 * @throws FieldException

 *

 * See: @link field Field API data structures @endlink.

 */

function field_create_field($field) {

  // Field name is required.

  if (empty($field['field_name'])) {

    throw new FieldException('Attempt to create an unnamed field.');

  }

  // Field type is required.

  if (empty($field['type'])) {

    throw new FieldException(format_string('Attempt to create field @field_name with no type.', array('@field_name' => $field['field_name'])));

  }

  // Field name cannot contain invalid characters.

  if (!preg_match('/^[_a-z]+[_a-z0-9]*$/', $field['field_name'])) {

    throw new FieldException(format_string('Attempt to create a field @field_name with invalid characters. Only lowercase alphanumeric characters and underscores are allowed, and only lowercase letters and underscore are allowed as the first character', array('@field_name' => $field['field_name'])));

  }

  // Field name cannot be longer than 32 characters. We use drupal_strlen()

  // because the DB layer assumes that column widths are given in characters,

  // not bytes.

  if (drupal_strlen($field['field_name']) > 32) {

    throw new FieldException(t('Attempt to create a field with a name longer than 32 characters: %name',

      array('%name' => $field['field_name'])));

  }

  // Ensure the field name is unique over active and disabled fields.

  // We do not care about deleted fields.

  $prior_field = field_read_field($field['field_name'], array('include_inactive' => TRUE));

  if (!empty($prior_field)) {

    $message = $prior_field['active']?

      t('Attempt to create field name %name which already exists and is active.', array('%name' => $field['field_name'])):

      t('Attempt to create field name %name which already exists, although it is inactive.', array('%name' => $field['field_name']));

    throw new FieldException($message);

  }

  // Disallow reserved field names. This can't prevent all field name

  // collisions with existing entity properties, but some is better

  // than none.

  foreach (entity_get_info() as $type => $info) {

    if (in_array($field['field_name'], $info['entity keys'])) {

      throw new FieldException(t('Attempt to create field name %name which is reserved by entity type %type.', array('%name' => $field['field_name'], '%type' => $type)));

    }

  }

  $field += array(

    'entity_types' => array(),

    'cardinality' => 1,

    'translatable' => FALSE,

    'locked' => FALSE,

    'settings' => array(),

    'storage' => array(),

    'deleted' => 0,

  );

  // Check that the field type is known.

  $field_type = field_info_field_types($field['type']);

  if (!$field_type) {

    throw new FieldException(t('Attempt to create a field of unknown type %type.', array('%type' => $field['type'])));

  }

  // Create all per-field-type properties (needed here as long as we have

  // settings that impact column definitions).

  $field['settings'] += field_info_field_settings($field['type']);

  $field['module'] = $field_type['module'];

  $field['active'] = 1;

  // Provide default storage.

  $field['storage'] += array(

    'type' => variable_get('field_storage_default', 'field_sql_storage'),

    'settings' => array(),

  );

  // Check that the storage type is known.

  $storage_type = field_info_storage_types($field['storage']['type']);

  if (!$storage_type) {

    throw new FieldException(t('Attempt to create a field with unknown storage type %type.', array('%type' => $field['storage']['type'])));

  }

  // Provide default storage settings.

  $field['storage']['settings'] += field_info_storage_settings($field['storage']['type']);

  $field['storage']['module'] = $storage_type['module'];

  $field['storage']['active'] = 1;

  // Collect storage information.

  module_load_install($field['module']);

  $schema = (array) module_invoke($field['module'], 'field_schema', $field);

  $schema += array('columns' => array(), 'indexes' => array(), 'foreign keys' => array());

  // 'columns' are hardcoded in the field type.

  $field['columns'] = $schema['columns'];

  // 'foreign keys' are hardcoded in the field type.

  $field['foreign keys'] = $schema['foreign keys'];

  // 'indexes' can be both hardcoded in the field type, and specified in the

  // incoming $field definition.

  $field += array(

    'indexes' => array(),

  );

  $field['indexes'] += $schema['indexes'];

  // The serialized 'data' column contains everything from $field that does not

  // have its own column and is not automatically populated when the field is

  // read.

  $data = $field;

  unset($data['columns'], $data['field_name'], $data['type'], $data['active'], $data['module'], $data['storage_type'], $data['storage_active'], $data['storage_module'], $data['locked'], $data['cardinality'], $data['deleted']);

  // Additionally, do not save the 'bundles' property populated by

  // field_info_field().

  unset($data['bundles']);

  $record = array(

    'field_name' => $field['field_name'],

    'type' => $field['type'],

    'module' => $field['module'],

    'active' => $field['active'],

    'storage_type' => $field['storage']['type'],

    'storage_module' => $field['storage']['module'],

    'storage_active' => $field['storage']['active'],

    'locked' => $field['locked'],

    'data' => $data,

    'cardinality' => $field['cardinality'],

    'translatable' => $field['translatable'],

    'deleted' => $field['deleted'],

  );

  // Store the field and get the id back.

  drupal_write_record('field_config', $record);

  $field['id'] = $record['id'];

  // Invoke hook_field_storage_create_field after the field is

  // complete (e.g. it has its id).

  try {

    // Invoke hook_field_storage_create_field after

    // drupal_write_record() sets the field id.

    module_invoke($storage_type['module'], 'field_storage_create_field', $field);

  }

  catch (Exception $e) {

    // If storage creation failed, remove the field_config record before

    // rethrowing the exception.

    db_delete('field_config')

      ->condition('id', $field['id'])

      ->execute();

    throw $e;

  }

  // Clear caches

  field_cache_clear();

  // Invoke external hooks after the cache is cleared for API consistency.

  module_invoke_all('field_create_field', $field);

  return $field;

}

/**

 * Updates a field.

 *

 * Any module may forbid any update for any reason. For example, the

 * field's storage module might forbid an update if it would change

 * the storage schema while data for the field exists. A field type

 * module might forbid an update if it would change existing data's

 * semantics, or if there are external dependencies on field settings

 * that cannot be updated.

 *

 * @param $field

 *   A field structure. $field['field_name'] must provided; it

 *   identifies the field that will be updated to match this

 *   structure. Any other properties of the field that are not

 *   specified in $field will be left unchanged, so it is not

 *   necessary to pass in a fully populated $field structure.

 * @return

 *   Throws a FieldException if the update cannot be performed.

 * @see field_create_field()

 */

function field_update_field($field) {

  // Check that the specified field exists.

  $prior_field = field_read_field($field['field_name']);

  if (empty($prior_field)) {

    throw new FieldException('Attempt to update a non-existent field.');

  }

  // Use the prior field values for anything not specifically set by the new

  // field to be sure that all values are set.

  $field += $prior_field;

  $field['settings'] += $prior_field['settings'];

  // Some updates are always disallowed.

  if ($field['type'] != $prior_field['type']) {

    throw new FieldException("Cannot change an existing field's type.");

  }

  if ($field['entity_types'] != $prior_field['entity_types']) {

    throw new FieldException("Cannot change an existing field's entity_types property.");

  }

  if ($field['storage']['type'] != $prior_field['storage']['type']) {

    throw new FieldException("Cannot change an existing field's storage type.");

  }

  // Collect the new storage information, since what is in

  // $prior_field may no longer be right.

  module_load_install($field['module']);

  $schema = (array) module_invoke($field['module'], 'field_schema', $field);

  $schema += array('columns' => array(), 'indexes' => array(), 'foreign keys' => array());

  // 'columns' are hardcoded in the field type.

  $field['columns'] = $schema['columns'];

  // 'foreign keys' are hardcoded in the field type.

  $field['foreign keys'] = $schema['foreign keys'];

  // 'indexes' can be both hardcoded in the field type, and specified in the

  // incoming $field definition.

  $field += array(

    'indexes' => array(),

  );

  $field['indexes'] += $schema['indexes'];

  $has_data = field_has_data($field);

  // See if any module forbids the update by throwing an exception.

  foreach (module_implements('field_update_forbid') as $module) {

    $function = $module . '_field_update_forbid';

    $function($field, $prior_field, $has_data);

  }

  // Tell the storage engine to update the field. Do this before

  // saving the new definition since it still might fail.

  $storage_type = field_info_storage_types($field['storage']['type']);

  module_invoke($storage_type['module'], 'field_storage_update_field', $field, $prior_field, $has_data);

  // Save the new field definition. @todo: refactor with

  // field_create_field.

  // The serialized 'data' column contains everything from $field that does not

  // have its own column and is not automatically populated when the field is

  // read.

  $data = $field;

  unset($data['columns'], $data['field_name'], $data['type'], $data['locked'], $data['module'], $data['cardinality'], $data['active'], $data['deleted']);

  // Additionally, do not save the 'bundles' property populated by

  // field_info_field().

  unset($data['bundles']);

  $field['data'] = $data;

  // Store the field and create the id.

  $primary_key = array('id');

  drupal_write_record('field_config', $field, $primary_key);

  // Clear caches

  field_cache_clear();

  // Invoke external hooks after the cache is cleared for API consistency.

  module_invoke_all('field_update_field', $field, $prior_field, $has_data);

}

/**

 * Reads a single field record directly from the database.

 *

 * Generally, you should use the field_info_field() instead.

 *

 * This function will not return deleted fields. Use

 * field_read_fields() instead for this purpose.

 *

 * @param $field_name

 *   The field name to read.

 * @param array $include_additional

 *   The default behavior of this function is to not return a field that

 *   is inactive. Setting

 *   $include_additional['include_inactive'] to TRUE will override this

 *   behavior.

 * @return

 *   A field definition array, or FALSE.

 */

function field_read_field($field_name, $include_additional = array()) {

  $fields = field_read_fields(array('field_name' => $field_name), $include_additional);

  return $fields ? current($fields) : FALSE;

}

/**

 * Reads in fields that match an array of conditions.

 *

 * @param array $params

 *   An array of conditions to match against. Keys are columns from the

 *   'field_config' table, values are conditions to match. Additionally,

 *   conditions on the 'entity_type' and 'bundle' columns from the

 *   'field_config_instance' table are supported (select fields having an

 *   instance on a given bundle).

 * @param array $include_additional

 *   The default behavior of this function is to not return fields that

 *   are inactive or have been deleted. Setting

 *   $include_additional['include_inactive'] or

 *   $include_additional['include_deleted'] to TRUE will override this

 *   behavior.

 * @return

 *   An array of fields matching $params. If

 *   $include_additional['include_deleted'] is TRUE, the array is keyed

 *   by field id, otherwise it is keyed by field name.

 */

function field_read_fields($params = array(), $include_additional = array()) {

  $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));

  $query->fields('fc');

  // Turn the conditions into a query.

  foreach ($params as $key => $value) {

    // Allow filtering on the 'entity_type' and 'bundle' columns of the

    // field_config_instance table.

    if ($key == 'entity_type' || $key == 'bundle') {

      if (empty($fci_join)) {

        $fci_join = $query->join('field_config_instance', 'fci', 'fc.id = fci.field_id');

      }

      $key = 'fci.' . $key;

    }

    else {

      $key = 'fc.' . $key;

    }

    $query->condition($key, $value);

  }

  if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) {

    $query

      ->condition('fc.active', 1)

      ->condition('fc.storage_active', 1);

  }

  $include_deleted = (isset($include_additional['include_deleted']) && $include_additional['include_deleted']);

  if (!$include_deleted) {

    $query->condition('fc.deleted', 0);

  }

  $fields = array();

  $results = $query->execute();

  foreach ($results as $record) {

    $field = unserialize($record['data']);

    $field['id'] = $record['id'];

    $field['field_name'] = $record['field_name'];

    $field['type'] = $record['type'];

    $field['module'] = $record['module'];

    $field['active'] = $record['active'];

    $field['storage']['type'] = $record['storage_type'];

    $field['storage']['module'] = $record['storage_module'];

    $field['storage']['active'] = $record['storage_active'];

    $field['locked'] = $record['locked'];

    $field['cardinality'] = $record['cardinality'];

    $field['translatable'] = $record['translatable'];

    $field['deleted'] = $record['deleted'];

    module_invoke_all('field_read_field', $field);

    // Populate storage information.

    module_load_install($field['module']);

    $schema = (array) module_invoke($field['module'], 'field_schema', $field);

    $schema += array('columns' => array(), 'indexes' => array());

    $field['columns'] = $schema['columns'];

    $field_name = $field['field_name'];

    if ($include_deleted) {

      $field_name = $field['id'];

    }

    $fields[$field_name] = $field;

  }

  return $fields;

}

/**

 * Marks a field and its instances and data for deletion.

 *

 * @param $field_name

 *   The field name to delete.

 */

function field_delete_field($field_name) {

  // Delete all non-deleted instances.

  $field = field_info_field($field_name);

  if (isset($field['bundles'])) {

    foreach ($field['bundles'] as $entity_type => $bundles) {

      foreach ($bundles as $bundle) {

        $instance = field_info_instance($entity_type, $field_name, $bundle);

        field_delete_instance($instance, FALSE);

      }

    }