field.crud.inc

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

File

drupal/modules/field/field.crud.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Field CRUD API, handling field and field instance creation and deletion.
  5. */
  6. /**
  7. * @defgroup field_crud Field CRUD API
  8. * @{
  9. * Create, update, and delete Field API fields, bundles, and instances.
  10. *
  11. * Modules use this API, often in hook_install(), to create custom
  12. * data structures. UI modules will use it to create a user interface.
  13. *
  14. * The Field CRUD API uses
  15. * @link field Field API data structures @endlink.
  16. *
  17. * See @link field Field API @endlink for information about the other parts of
  18. * the Field API.
  19. */
  20. /**
  21. * Creates a field.
  22. *
  23. * This function does not bind the field to any bundle; use
  24. * field_create_instance() for that.
  25. *
  26. * @param $field
  27. * A field definition array. The field_name and type properties are required.
  28. * Other properties, if omitted, will be given the following default values:
  29. * - cardinality: 1
  30. * - locked: FALSE
  31. * - indexes: the field-type indexes, specified by the field type's
  32. * hook_field_schema(). The indexes specified in $field are added
  33. * to those default indexes. It is possible to override the
  34. * definition of a field-type index by providing an index with the
  35. * same name, or to remove it by redefining it as an empty array
  36. * of columns. Overriding field-type indexes should be done
  37. * carefully, for it might seriously affect the site's performance.
  38. * - settings: each omitted setting is given the default value defined in
  39. * hook_field_info().
  40. * - storage:
  41. * - type: the storage backend specified in the 'field_storage_default'
  42. * system variable.
  43. * - settings: each omitted setting is given the default value specified in
  44. * hook_field_storage_info().
  45. *
  46. * @return
  47. * The $field array with the id property filled in.
  48. *
  49. * @throws FieldException
  50. *
  51. * See: @link field Field API data structures @endlink.
  52. */
  53. function field_create_field($field) {
  54. // Field name is required.
  55. if (empty($field['field_name'])) {
  56. throw new FieldException('Attempt to create an unnamed field.');
  57. }
  58. // Field type is required.
  59. if (empty($field['type'])) {
  60. throw new FieldException('Attempt to create a field with no type.');
  61. }
  62. // Field name cannot contain invalid characters.
  63. if (!preg_match('/^[_a-z]+[_a-z0-9]*$/', $field['field_name'])) {
  64. throw new FieldException('Attempt to create a field with invalid characters. Only lowercase alphanumeric characters and underscores are allowed, and only lowercase letters and underscore are allowed as the first character');
  65. }
  66. // Field name cannot be longer than 32 characters. We use drupal_strlen()
  67. // because the DB layer assumes that column widths are given in characters,
  68. // not bytes.
  69. if (drupal_strlen($field['field_name']) > 32) {
  70. throw new FieldException(t('Attempt to create a field with a name longer than 32 characters: %name',
  71. array('%name' => $field['field_name'])));
  72. }
  73. // Ensure the field name is unique over active and disabled fields.
  74. // We do not care about deleted fields.
  75. $prior_field = field_read_field($field['field_name'], array('include_inactive' => TRUE));
  76. if (!empty($prior_field)) {
  77. $message = $prior_field['active']?
  78. t('Attempt to create field name %name which already exists and is active.', array('%name' => $field['field_name'])):
  79. t('Attempt to create field name %name which already exists, although it is inactive.', array('%name' => $field['field_name']));
  80. throw new FieldException($message);
  81. }
  82. // Disallow reserved field names. This can't prevent all field name
  83. // collisions with existing entity properties, but some is better
  84. // than none.
  85. foreach (entity_get_info() as $type => $info) {
  86. if (in_array($field['field_name'], $info['entity keys'])) {
  87. throw new FieldException(t('Attempt to create field name %name which is reserved by entity type %type.', array('%name' => $field['field_name'], '%type' => $type)));
  88. }
  89. }
  90. $field += array(
  91. 'entity_types' => array(),
  92. 'cardinality' => 1,
  93. 'translatable' => FALSE,
  94. 'locked' => FALSE,
  95. 'settings' => array(),
  96. 'storage' => array(),
  97. 'deleted' => 0,
  98. );
  99. // Check that the field type is known.
  100. $field_type = field_info_field_types($field['type']);
  101. if (!$field_type) {
  102. throw new FieldException(t('Attempt to create a field of unknown type %type.', array('%type' => $field['type'])));
  103. }
  104. // Create all per-field-type properties (needed here as long as we have
  105. // settings that impact column definitions).
  106. $field['settings'] += field_info_field_settings($field['type']);
  107. $field['module'] = $field_type['module'];
  108. $field['active'] = 1;
  109. // Provide default storage.
  110. $field['storage'] += array(
  111. 'type' => variable_get('field_storage_default', 'field_sql_storage'),
  112. 'settings' => array(),
  113. );
  114. // Check that the storage type is known.
  115. $storage_type = field_info_storage_types($field['storage']['type']);
  116. if (!$storage_type) {
  117. throw new FieldException(t('Attempt to create a field with unknown storage type %type.', array('%type' => $field['storage']['type'])));
  118. }
  119. // Provide default storage settings.
  120. $field['storage']['settings'] += field_info_storage_settings($field['storage']['type']);
  121. $field['storage']['module'] = $storage_type['module'];
  122. $field['storage']['active'] = 1;
  123. // Collect storage information.
  124. module_load_install($field['module']);
  125. $schema = (array) module_invoke($field['module'], 'field_schema', $field);
  126. $schema += array('columns' => array(), 'indexes' => array(), 'foreign keys' => array());
  127. // 'columns' are hardcoded in the field type.
  128. $field['columns'] = $schema['columns'];
  129. // 'foreign keys' are hardcoded in the field type.
  130. $field['foreign keys'] = $schema['foreign keys'];
  131. // 'indexes' can be both hardcoded in the field type, and specified in the
  132. // incoming $field definition.
  133. $field += array(
  134. 'indexes' => array(),
  135. );
  136. $field['indexes'] += $schema['indexes'];
  137. // The serialized 'data' column contains everything from $field that does not
  138. // have its own column and is not automatically populated when the field is
  139. // read.
  140. $data = $field;
  141. 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']);
  142. // Additionally, do not save the 'bundles' property populated by
  143. // field_info_field().
  144. unset($data['bundles']);
  145. $record = array(
  146. 'field_name' => $field['field_name'],
  147. 'type' => $field['type'],
  148. 'module' => $field['module'],
  149. 'active' => $field['active'],
  150. 'storage_type' => $field['storage']['type'],
  151. 'storage_module' => $field['storage']['module'],
  152. 'storage_active' => $field['storage']['active'],
  153. 'locked' => $field['locked'],
  154. 'data' => $data,
  155. 'cardinality' => $field['cardinality'],
  156. 'translatable' => $field['translatable'],
  157. 'deleted' => $field['deleted'],
  158. );
  159. // Store the field and get the id back.
  160. drupal_write_record('field_config', $record);
  161. $field['id'] = $record['id'];
  162. // Invoke hook_field_storage_create_field after the field is
  163. // complete (e.g. it has its id).
  164. try {
  165. // Invoke hook_field_storage_create_field after
  166. // drupal_write_record() sets the field id.
  167. module_invoke($storage_type['module'], 'field_storage_create_field', $field);
  168. }
  169. catch (Exception $e) {
  170. // If storage creation failed, remove the field_config record before
  171. // rethrowing the exception.
  172. db_delete('field_config')
  173. ->condition('id', $field['id'])
  174. ->execute();
  175. throw $e;
  176. }
  177. // Clear caches
  178. field_cache_clear(TRUE);
  179. // Invoke external hooks after the cache is cleared for API consistency.
  180. module_invoke_all('field_create_field', $field);
  181. return $field;
  182. }
  183. /**
  184. * Updates a field.
  185. *
  186. * Any module may forbid any update for any reason. For example, the
  187. * field's storage module might forbid an update if it would change
  188. * the storage schema while data for the field exists. A field type
  189. * module might forbid an update if it would change existing data's
  190. * semantics, or if there are external dependencies on field settings
  191. * that cannot be updated.
  192. *
  193. * @param $field
  194. * A field structure. $field['field_name'] must provided; it
  195. * identifies the field that will be updated to match this
  196. * structure. Any other properties of the field that are not
  197. * specified in $field will be left unchanged, so it is not
  198. * necessary to pass in a fully populated $field structure.
  199. * @return
  200. * Throws a FieldException if the update cannot be performed.
  201. * @see field_create_field()
  202. */
  203. function field_update_field($field) {
  204. // Check that the specified field exists.
  205. $prior_field = field_read_field($field['field_name']);
  206. if (empty($prior_field)) {
  207. throw new FieldException('Attempt to update a non-existent field.');
  208. }
  209. // Use the prior field values for anything not specifically set by the new
  210. // field to be sure that all values are set.
  211. $field += $prior_field;
  212. $field['settings'] += $prior_field['settings'];
  213. // Some updates are always disallowed.
  214. if ($field['type'] != $prior_field['type']) {
  215. throw new FieldException("Cannot change an existing field's type.");
  216. }
  217. if ($field['entity_types'] != $prior_field['entity_types']) {
  218. throw new FieldException("Cannot change an existing field's entity_types property.");
  219. }
  220. if ($field['storage']['type'] != $prior_field['storage']['type']) {
  221. throw new FieldException("Cannot change an existing field's storage type.");
  222. }
  223. // Collect the new storage information, since what is in
  224. // $prior_field may no longer be right.
  225. module_load_install($field['module']);
  226. $schema = (array) module_invoke($field['module'], 'field_schema', $field);
  227. $schema += array('columns' => array(), 'indexes' => array());
  228. // 'columns' are hardcoded in the field type.
  229. $field['columns'] = $schema['columns'];
  230. // 'indexes' can be both hardcoded in the field type, and specified in the
  231. // incoming $field definition.
  232. $field += array(
  233. 'indexes' => array(),
  234. );
  235. $field['indexes'] += $schema['indexes'];
  236. $has_data = field_has_data($field);
  237. // See if any module forbids the update by throwing an exception.
  238. foreach (module_implements('field_update_forbid') as $module) {
  239. $function = $module . '_field_update_forbid';
  240. $function($field, $prior_field, $has_data);
  241. }
  242. // Tell the storage engine to update the field. Do this before
  243. // saving the new definition since it still might fail.
  244. $storage_type = field_info_storage_types($field['storage']['type']);
  245. module_invoke($storage_type['module'], 'field_storage_update_field', $field, $prior_field, $has_data);
  246. // Save the new field definition. @todo: refactor with
  247. // field_create_field.
  248. // The serialized 'data' column contains everything from $field that does not
  249. // have its own column and is not automatically populated when the field is
  250. // read.
  251. $data = $field;
  252. unset($data['columns'], $data['field_name'], $data['type'], $data['locked'], $data['module'], $data['cardinality'], $data['active'], $data['deleted']);
  253. // Additionally, do not save the 'bundles' property populated by
  254. // field_info_field().
  255. unset($data['bundles']);
  256. $field['data'] = $data;
  257. // Store the field and create the id.
  258. $primary_key = array('id');
  259. drupal_write_record('field_config', $field, $primary_key);
  260. // Clear caches
  261. field_cache_clear(TRUE);
  262. // Invoke external hooks after the cache is cleared for API consistency.
  263. module_invoke_all('field_update_field', $field, $prior_field, $has_data);
  264. }
  265. /**
  266. * Reads a single field record directly from the database.
  267. *
  268. * Generally, you should use the field_info_field() instead.
  269. *
  270. * This function will not return deleted fields. Use
  271. * field_read_fields() instead for this purpose.
  272. *
  273. * @param $field_name
  274. * The field name to read.
  275. * @param array $include_additional
  276. * The default behavior of this function is to not return a field that
  277. * is inactive. Setting
  278. * $include_additional['include_inactive'] to TRUE will override this
  279. * behavior.
  280. * @return
  281. * A field definition array, or FALSE.
  282. */
  283. function field_read_field($field_name, $include_additional = array()) {
  284. $fields = field_read_fields(array('field_name' => $field_name), $include_additional);
  285. return $fields ? current($fields) : FALSE;
  286. }
  287. /**
  288. * Reads in fields that match an array of conditions.
  289. *
  290. * @param array $params
  291. * An array of conditions to match against. Keys are columns from the
  292. * 'field_config' table, values are conditions to match. Additionally,
  293. * conditions on the 'entity_type' and 'bundle' columns from the
  294. * 'field_config_instance' table are supported (select fields having an
  295. * instance on a given bundle).
  296. * @param array $include_additional
  297. * The default behavior of this function is to not return fields that
  298. * are inactive or have been deleted. Setting
  299. * $include_additional['include_inactive'] or
  300. * $include_additional['include_deleted'] to TRUE will override this
  301. * behavior.
  302. * @return
  303. * An array of fields matching $params. If
  304. * $include_additional['include_deleted'] is TRUE, the array is keyed
  305. * by field id, otherwise it is keyed by field name.
  306. */
  307. function field_read_fields($params = array(), $include_additional = array()) {
  308. $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));
  309. $query->fields('fc');
  310. // Turn the conditions into a query.
  311. foreach ($params as $key => $value) {
  312. // Allow filtering on the 'entity_type' and 'bundle' columns of the
  313. // field_config_instance table.
  314. if ($key == 'entity_type' || $key == 'bundle') {
  315. if (empty($fci_join)) {
  316. $fci_join = $query->join('field_config_instance', 'fci', 'fc.id = fci.field_id');
  317. }
  318. $key = 'fci.' . $key;
  319. }
  320. else {
  321. $key = 'fc.' . $key;
  322. }
  323. $query->condition($key, $value);
  324. }
  325. if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) {
  326. $query
  327. ->condition('fc.active', 1)
  328. ->condition('fc.storage_active', 1);
  329. }
  330. $include_deleted = (isset($include_additional['include_deleted']) && $include_additional['include_deleted']);
  331. if (!$include_deleted) {
  332. $query->condition('fc.deleted', 0);
  333. }
  334. $fields = array();
  335. $results = $query->execute();
  336. foreach ($results as $record) {
  337. $field = unserialize($record['data']);
  338. $field['id'] = $record['id'];
  339. $field['field_name'] = $record['field_name'];
  340. $field['type'] = $record['type'];
  341. $field['module'] = $record['module'];
  342. $field['active'] = $record['active'];
  343. $field['storage']['type'] = $record['storage_type'];
  344. $field['storage']['module'] = $record['storage_module'];
  345. $field['storage']['active'] = $record['storage_active'];
  346. $field['locked'] = $record['locked'];
  347. $field['cardinality'] = $record['cardinality'];
  348. $field['translatable'] = $record['translatable'];
  349. $field['deleted'] = $record['deleted'];
  350. module_invoke_all('field_read_field', $field);
  351. // Populate storage information.
  352. module_load_install($field['module']);
  353. $schema = (array) module_invoke($field['module'], 'field_schema', $field);
  354. $schema += array('columns' => array(), 'indexes' => array());
  355. $field['columns'] = $schema['columns'];
  356. $field_name = $field['field_name'];
  357. if ($include_deleted) {
  358. $field_name = $field['id'];
  359. }
  360. $fields[$field_name] = $field;
  361. }
  362. return $fields;
  363. }
  364. /**
  365. * Marks a field and its instances and data for deletion.
  366. *
  367. * @param $field_name
  368. * The field name to delete.
  369. */
  370. function field_delete_field($field_name) {
  371. // Delete all non-deleted instances.
  372. $field = field_info_field($field_name);
  373. if (isset($field['bundles'])) {
  374. foreach ($field['bundles'] as $entity_type => $bundles) {
  375. foreach ($bundles as $bundle) {
  376. $instance = field_info_instance($entity_type, $field_name, $bundle);
  377. field_delete_instance($instance, FALSE);
  378. }
  379. }
  380. }
  381. // Mark field data for deletion.
  382. module_invoke($field['storage']['module'], 'field_storage_delete_field', $field);
  383. // Mark the field for deletion.
  384. db_update('field_config')
  385. ->fields(array('deleted' => 1))
  386. ->condition('field_name', $field_name)
  387. ->execute();
  388. // Clear the cache.
  389. field_cache_clear(TRUE);
  390. module_invoke_all('field_delete_field', $field);
  391. }
  392. /**
  393. * Creates an instance of a field, binding it to a bundle.
  394. *
  395. * @param $instance
  396. * A field instance definition array. The field_name, entity_type and
  397. * bundle properties are required. Other properties, if omitted,
  398. * will be given the following default values:
  399. * - label: the field name
  400. * - description: empty string
  401. * - required: FALSE
  402. * - default_value_function: empty string
  403. * - settings: each omitted setting is given the default value specified in
  404. * hook_field_info().
  405. * - widget:
  406. * - type: the default widget specified in hook_field_info().
  407. * - settings: each omitted setting is given the default value specified in
  408. * hook_field_widget_info().
  409. * - display:
  410. * Settings for the 'default' view mode will be added if not present, and
  411. * each view mode in the definition will be completed with the following
  412. * default values:
  413. * - label: 'above'
  414. * - type: the default formatter specified in hook_field_info().
  415. * - settings: each omitted setting is given the default value specified in
  416. * hook_field_formatter_info().
  417. * View modes not present in the definition are left empty, and the field
  418. * will not be displayed in this mode.
  419. *
  420. * @return
  421. * The $instance array with the id property filled in.
  422. *
  423. * @throws FieldException
  424. *
  425. * See: @link field Field API data structures @endlink.
  426. */
  427. function field_create_instance($instance) {
  428. $field = field_read_field($instance['field_name']);
  429. if (empty($field)) {
  430. throw new FieldException(t("Attempt to create an instance of a field @field_name that doesn't exist or is currently inactive.", array('@field_name' => $instance['field_name'])));
  431. }
  432. // Check that the required properties exists.
  433. if (empty($instance['entity_type'])) {
  434. throw new FieldException(t('Attempt to create an instance of field @field_name without an entity type.', array('@field_name' => $instance['field_name'])));
  435. }
  436. if (empty($instance['bundle'])) {
  437. throw new FieldException(t('Attempt to create an instance of field @field_name without a bundle.', array('@field_name' => $instance['field_name'])));
  438. }
  439. // Check that the field can be attached to this entity type.
  440. if (!empty($field['entity_types']) && !in_array($instance['entity_type'], $field['entity_types'])) {
  441. throw new FieldException(t('Attempt to create an instance of field @field_name on forbidden entity type @entity_type.', array('@field_name' => $instance['field_name'], '@entity_type' => $instance['entity_type'])));
  442. }
  443. // Set the field id.
  444. $instance['field_id'] = $field['id'];
  445. // Note that we do *not* prevent creating a field on non-existing bundles,
  446. // because that would break the 'Body as field' upgrade for contrib
  447. // node types.
  448. // TODO: Check that the widget type is known and can handle the field type ?
  449. // TODO: Check that the formatters are known and can handle the field type ?
  450. // TODO: Check that the display view modes are known for the entity type ?
  451. // Those checks should probably happen in _field_write_instance() ?
  452. // Problem : this would mean that a UI module cannot update an instance with a disabled formatter.
  453. // Ensure the field instance is unique within the bundle.
  454. // We only check for instances of active fields, since adding an instance of
  455. // a disabled field is not supported.
  456. $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle']);
  457. if (!empty($prior_instance)) {
  458. $message = t('Attempt to create an instance of field @field_name on bundle @bundle that already has an instance of that field.', array('@field_name' => $instance['field_name'], '@bundle' => $instance['bundle']));
  459. throw new FieldException($message);
  460. }
  461. _field_write_instance($instance);
  462. // Clear caches
  463. field_cache_clear();
  464. // Invoke external hooks after the cache is cleared for API consistency.
  465. module_invoke_all('field_create_instance', $instance);
  466. return $instance;
  467. }
  468. /**
  469. * Updates an instance of a field.
  470. *
  471. * @param $instance
  472. * An associative array representing an instance structure. The following
  473. * required array elements specify which field instance is being updated:
  474. * - entity_type: The type of the entity the field is attached to.
  475. * - bundle: The bundle this field belongs to.
  476. * - field_name: The name of an existing field.
  477. * The other array elements represent properties of the instance, and all
  478. * properties must be specified or their default values will be used (except
  479. * internal-use properties, which are assigned automatically). To avoid
  480. * losing the previously stored properties of the instance when making a
  481. * change, first load the instance with field_info_instance(), then override
  482. * the values you want to override, and finally save using this function.
  483. * Example:
  484. * @code
  485. * // Fetch an instance info array.
  486. * $instance_info = field_info_instance($entity_type, $field_name, $bundle_name);
  487. * // Change a single property in the instance definition.
  488. * $instance_info['definition']['required'] = TRUE;
  489. * // Write the changed definition back.
  490. * field_update_instance($instance_info['definition']);
  491. * @endcode
  492. *
  493. * @throws FieldException
  494. *
  495. * @see field_info_instance()
  496. * @see field_create_instance()
  497. */
  498. function field_update_instance($instance) {
  499. // Check that the specified field exists.
  500. $field = field_read_field($instance['field_name']);
  501. if (empty($field)) {
  502. throw new FieldException(t('Attempt to update an instance of a nonexistent field @field.', array('@field' => $instance['field_name'])));
  503. }
  504. // Check that the field instance exists (even if it is inactive, since we
  505. // want to be able to replace inactive widgets with new ones).
  506. $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE));
  507. if (empty($prior_instance)) {
  508. throw new FieldException(t("Attempt to update an instance of field @field on bundle @bundle that doesn't exist.", array('@field' => $instance['field_name'], '@bundle' => $instance['bundle'])));
  509. }
  510. $instance['id'] = $prior_instance['id'];
  511. $instance['field_id'] = $prior_instance['field_id'];
  512. _field_write_instance($instance, TRUE);
  513. // Clear caches.
  514. field_cache_clear();
  515. module_invoke_all('field_update_instance', $instance, $prior_instance);
  516. }
  517. /**
  518. * Stores an instance record in the field configuration database.
  519. *
  520. * @param $instance
  521. * An instance structure.
  522. * @param $update
  523. * Whether this is a new or existing instance.
  524. */
  525. function _field_write_instance($instance, $update = FALSE) {
  526. $field = field_read_field($instance['field_name']);
  527. $field_type = field_info_field_types($field['type']);
  528. // Set defaults.
  529. $instance += array(
  530. 'settings' => array(),
  531. 'display' => array(),
  532. 'widget' => array(),
  533. 'required' => FALSE,
  534. 'label' => $instance['field_name'],
  535. 'description' => '',
  536. 'deleted' => 0,
  537. );
  538. // Set default instance settings.
  539. $instance['settings'] += field_info_instance_settings($field['type']);
  540. // Set default widget and settings.
  541. $instance['widget'] += array(
  542. // TODO: what if no 'default_widget' specified ?
  543. 'type' => $field_type['default_widget'],
  544. 'settings' => array(),
  545. );
  546. // If no weight specified, make sure the field sinks at the bottom.
  547. if (!isset($instance['widget']['weight'])) {
  548. $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], 'form');
  549. $instance['widget']['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
  550. }
  551. // Check widget module.
  552. $widget_type = field_info_widget_types($instance['widget']['type']);
  553. $instance['widget']['module'] = $widget_type['module'];
  554. $instance['widget']['settings'] += field_info_widget_settings($instance['widget']['type']);
  555. // Make sure there are at least display settings for the 'default' view mode,
  556. // and fill in defaults for each view mode specified in the definition.
  557. $instance['display'] += array(
  558. 'default' => array(),
  559. );
  560. foreach ($instance['display'] as $view_mode => $display) {
  561. $display += array(
  562. 'label' => 'above',
  563. 'type' => isset($field_type['default_formatter']) ? $field_type['default_formatter'] : 'hidden',
  564. 'settings' => array(),
  565. );
  566. if ($display['type'] != 'hidden') {
  567. $formatter_type = field_info_formatter_types($display['type']);
  568. $display['module'] = $formatter_type['module'];
  569. $display['settings'] += field_info_formatter_settings($display['type']);
  570. }
  571. // If no weight specified, make sure the field sinks at the bottom.
  572. if (!isset($display['weight'])) {
  573. $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], $view_mode);
  574. $display['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
  575. }
  576. $instance['display'][$view_mode] = $display;
  577. }
  578. // The serialized 'data' column contains everything from $instance that does
  579. // not have its own column and is not automatically populated when the
  580. // instance is read.
  581. $data = $instance;
  582. unset($data['id'], $data['field_id'], $data['field_name'], $data['entity_type'], $data['bundle'], $data['deleted']);
  583. $record = array(
  584. 'field_id' => $instance['field_id'],
  585. 'field_name' => $instance['field_name'],
  586. 'entity_type' => $instance['entity_type'],
  587. 'bundle' => $instance['bundle'],
  588. 'data' => $data,
  589. 'deleted' => $instance['deleted'],
  590. );
  591. // We need to tell drupal_update_record() the primary keys to trigger an
  592. // update.
  593. if ($update) {
  594. $record['id'] = $instance['id'];
  595. $primary_key = array('id');
  596. }
  597. else {
  598. $primary_key = array();
  599. }
  600. drupal_write_record('field_config_instance', $record, $primary_key);
  601. }
  602. /**
  603. * Reads a single instance record from the database.
  604. *
  605. * Generally, you should use field_info_instance() instead, as it
  606. * provides caching and allows other modules the opportunity to
  607. * append additional formatters, widgets, and other information.
  608. *
  609. * @param $entity_type
  610. * The type of entity to which the field is bound.
  611. * @param $field_name
  612. * The field name to read.
  613. * @param $bundle
  614. * The bundle to which the field is bound.
  615. * @param array $include_additional
  616. * The default behavior of this function is to not return an instance that
  617. * has been deleted, or whose field is inactive. Setting
  618. * $include_additional['include_inactive'] or
  619. * $include_additional['include_deleted'] to TRUE will override this
  620. * behavior.
  621. * @return
  622. * An instance structure, or FALSE.
  623. */
  624. function field_read_instance($entity_type, $field_name, $bundle, $include_additional = array()) {
  625. $instances = field_read_instances(array('entity_type' => $entity_type, 'field_name' => $field_name, 'bundle' => $bundle), $include_additional);
  626. return $instances ? current($instances) : FALSE;
  627. }
  628. /**
  629. * Reads in field instances that match an array of conditions.
  630. *
  631. * @param $param
  632. * An array of properties to use in selecting a field
  633. * instance. Valid keys include any column of the
  634. * field_config_instance table. If NULL, all instances will be returned.
  635. * @param $include_additional
  636. * The default behavior of this function is to not return field
  637. * instances that have been marked deleted, or whose field is inactive.
  638. * Setting $include_additional['include_inactive'] or
  639. * $include_additional['include_deleted'] to TRUE will override this
  640. * behavior.
  641. * @return
  642. * An array of instances matching the arguments.
  643. */
  644. function field_read_instances($params = array(), $include_additional = array()) {
  645. $include_inactive = isset($include_additional['include_inactive']) && $include_additional['include_inactive'];
  646. $include_deleted = isset($include_additional['include_deleted']) && $include_additional['include_deleted'];
  647. $query = db_select('field_config_instance', 'fci', array('fetch' => PDO::FETCH_ASSOC));
  648. $query->join('field_config', 'fc', 'fc.id = fci.field_id');
  649. $query->fields('fci');
  650. // Turn the conditions into a query.
  651. foreach ($params as $key => $value) {
  652. $query->condition('fci.' . $key, $value);
  653. }
  654. if (!$include_inactive) {
  655. $query
  656. ->condition('fc.active', 1)
  657. ->condition('fc.storage_active', 1);
  658. }
  659. if (!$include_deleted) {
  660. $query->condition('fc.deleted', 0);
  661. $query->condition('fci.deleted', 0);
  662. }
  663. $instances = array();
  664. $results = $query->execute();
  665. foreach ($results as $record) {
  666. // Filter out instances on unknown entity types (for instance because the
  667. // module exposing them was disabled).
  668. $entity_info = entity_get_info($record['entity_type']);
  669. if ($include_inactive || $entity_info) {
  670. $instance = unserialize($record['data']);
  671. $instance['id'] = $record['id'];
  672. $instance['field_id'] = $record['field_id'];
  673. $instance['field_name'] = $record['field_name'];
  674. $instance['entity_type'] = $record['entity_type'];
  675. $instance['bundle'] = $record['bundle'];
  676. $instance['deleted'] = $record['deleted'];
  677. module_invoke_all('field_read_instance', $instance);
  678. $instances[] = $instance;
  679. }
  680. }
  681. return $instances;
  682. }
  683. /**
  684. * Marks a field instance and its data for deletion.
  685. *
  686. * @param $instance
  687. * An instance structure.
  688. * @param $field_cleanup
  689. * If TRUE, the field will be deleted as well if its last instance is being
  690. * deleted. If FALSE, it is the caller's responsibility to handle the case of
  691. * fields left without instances. Defaults to TRUE.
  692. */
  693. function field_delete_instance($instance, $field_cleanup = TRUE) {
  694. // Mark the field instance for deletion.
  695. db_update('field_config_instance')
  696. ->fields(array('deleted' => 1))
  697. ->condition('field_name', $instance['field_name'])
  698. ->condition('entity_type', $instance['entity_type'])
  699. ->condition('bundle', $instance['bundle'])
  700. ->execute();
  701. // Clear the cache.
  702. field_cache_clear();
  703. // Mark instance data for deletion.
  704. $field = field_info_field($instance['field_name']);
  705. module_invoke($field['storage']['module'], 'field_storage_delete_instance', $instance);
  706. // Let modules react to the deletion of the instance.
  707. module_invoke_all('field_delete_instance', $instance);
  708. // Delete the field itself if we just deleted its last instance.
  709. if ($field_cleanup && count($field['bundles']) == 0) {
  710. field_delete_field($field['field_name']);
  711. }
  712. }
  713. /**
  714. * @} End of "defgroup field_crud".
  715. */
  716. /**
  717. * @defgroup field_purge Field API bulk data deletion
  718. * @{
  719. * Clean up after Field API bulk deletion operations.
  720. *
  721. * Field API provides functions for deleting data attached to individual
  722. * entities as well as deleting entire fields or field instances in a single
  723. * operation.
  724. *
  725. * Deleting field data items for an entity with field_attach_delete() involves
  726. * three separate operations:
  727. * - Invoking the Field Type API hook_field_delete() for each field on the
  728. * entity. The hook for each field type receives the entity and the specific
  729. * field being deleted. A file field module might use this hook to delete
  730. * uploaded files from the filesystem.
  731. * - Invoking the Field Storage API hook_field_storage_delete() to remove
  732. * data from the primary field storage. The hook implementation receives the
  733. * entity being deleted and deletes data for all of the entity's bundle's
  734. * fields.
  735. * - Invoking the global Field Attach API hook_field_attach_delete() for all
  736. * modules that implement it. Each hook implementation receives the entity
  737. * being deleted and can operate on whichever subset of the entity's bundle's
  738. * fields it chooses to.
  739. *
  740. * These hooks are invoked immediately when field_attach_delete() is
  741. * called. Similar operations are performed for field_attach_delete_revision().
  742. *
  743. * When a field, bundle, or field instance is deleted, it is not practical to
  744. * invoke these hooks immediately on every affected entity in a single page
  745. * request; there could be thousands or millions of them. Instead, the
  746. * appropriate field data items, instances, and/or fields are marked as deleted
  747. * so that subsequent load or query operations will not return them. Later, a
  748. * separate process cleans up, or "purges", the marked-as-deleted data by going
  749. * through the three-step process described above and, finally, removing
  750. * deleted field and instance records.
  751. *
  752. * Purging field data is made somewhat tricky by the fact that, while
  753. * field_attach_delete() has a complete entity to pass to the various deletion
  754. * hooks, the Field API purge process only has the field data it has previously
  755. * stored. It cannot reconstruct complete original entities to pass to the
  756. * deletion hooks. It is even possible that the original entity to which some
  757. * Field API data was attached has been itself deleted before the field purge
  758. * operation takes place.
  759. *
  760. * Field API resolves this problem by using "pseudo-entities" during purge
  761. * operations. A pseudo-entity contains only the information from the original
  762. * entity that Field API knows about: entity type, id, revision id, and
  763. * bundle. It also contains the field data for whichever field instance is
  764. * currently being purged. For example, suppose that the node type 'story' used
  765. * to contain a field called 'subtitle' but the field was deleted. If node 37
  766. * was a story with a subtitle, the pseudo-entity passed to the purge hooks
  767. * would look something like this:
  768. *
  769. * @code
  770. * $entity = stdClass Object(
  771. * [nid] => 37,
  772. * [vid] => 37,
  773. * [type] => 'story',
  774. * [subtitle] => array(
  775. * [0] => array(
  776. * 'value' => 'subtitle text',
  777. * ),
  778. * ),
  779. * );
  780. * @endcode
  781. *
  782. * See @link field Field API @endlink for information about the other parts of
  783. * the Field API.
  784. */
  785. /**
  786. * Purges a batch of deleted Field API data, instances, or fields.
  787. *
  788. * This function will purge deleted field data in batches. The batch size
  789. * is defined as an argument to the function, and once each batch is finished,
  790. * it continues with the next batch until all have completed. If a deleted field
  791. * instance with no remaining data records is found, the instance itself will
  792. * be purged. If a deleted field with no remaining field instances is found, the
  793. * field itself will be purged.
  794. *
  795. * @param $batch_size
  796. * The maximum number of field data records to purge before returning.
  797. */
  798. function field_purge_batch($batch_size) {
  799. // Retrieve all deleted field instances. We cannot use field_info_instances()
  800. // because that function does not return deleted instances.
  801. $instances = field_read_instances(array('deleted' => 1), array('include_deleted' => 1));
  802. foreach ($instances as $instance) {
  803. // field_purge_data() will need the field array.
  804. $field = field_info_field_by_id($instance['field_id']);
  805. // Retrieve some entities.
  806. $query = new EntityFieldQuery();
  807. $results = $query
  808. ->fieldCondition($field)
  809. ->entityCondition('bundle', $instance['bundle'])
  810. ->deleted(TRUE)
  811. ->range(0, $batch_size)
  812. ->execute();
  813. if ($results) {
  814. foreach ($results as $entity_type => $stub_entities) {
  815. field_attach_load($entity_type, $stub_entities, FIELD_LOAD_CURRENT, array('field_id' => $field['id'], 'deleted' => 1));
  816. foreach ($stub_entities as $stub_entity) {
  817. // Purge the data for the entity.
  818. field_purge_data($entity_type, $stub_entity, $field, $instance);
  819. }
  820. }
  821. }
  822. else {
  823. // No field data remains for the instance, so we can remove it.
  824. field_purge_instance($instance);
  825. }
  826. }
  827. // Retrieve all deleted fields. Any that have no instances can be purged.
  828. $fields = field_read_fields(array('deleted' => 1), array('include_deleted' => 1));
  829. foreach ($fields as $field) {
  830. $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
  831. if (empty($instances)) {
  832. field_purge_field($field);
  833. }
  834. }
  835. }
  836. /**
  837. * Purges the field data for a single field on a single pseudo-entity.
  838. *
  839. * This is basically the same as field_attach_delete() except it only applies
  840. * to a single field. The entity itself is not being deleted, and it is quite
  841. * possible that other field data will remain attached to it.
  842. *
  843. * @param $entity_type
  844. * The type of $entity; e.g. 'node' or 'user'.
  845. * @param $entity
  846. * The pseudo-entity whose field data is being purged.
  847. * @param $field
  848. * The (possibly deleted) field whose data is being purged.
  849. * @param $instance
  850. * The deleted field instance whose data is being purged.
  851. */
  852. function field_purge_data($entity_type, $entity, $field, $instance) {
  853. // Each field type's hook_field_delete() only expects to operate on a single
  854. // field at a time, so we can use it as-is for purging.
  855. $options = array('field_id' => $instance['field_id'], 'deleted' => TRUE);
  856. _field_invoke('delete', $entity_type, $entity, $dummy, $dummy, $options);
  857. // Tell the field storage system to purge the data.
  858. module_invoke($field['storage']['module'], 'field_storage_purge', $entity_type, $entity, $field, $instance);
  859. // Let other modules act on purging the data.
  860. foreach (module_implements('field_attach_purge') as $module) {
  861. $function = $module . '_field_attach_purge';
  862. $function($entity_type, $entity, $field, $instance);
  863. }
  864. }
  865. /**
  866. * Purges a field instance record from the database.
  867. *
  868. * This function assumes all data for the instance has already been purged, and
  869. * should only be called by field_purge_batch().
  870. *
  871. * @param $instance
  872. * The instance record to purge.
  873. */
  874. function field_purge_instance($instance) {
  875. db_delete('field_config_instance')
  876. ->condition('id', $instance['id'])
  877. ->execute();
  878. // Notify the storage engine.
  879. $field = field_info_field_by_id($instance['field_id']);
  880. module_invoke($field['storage']['module'], 'field_storage_purge_instance', $instance);
  881. // Clear the cache.
  882. field_info_cache_clear();
  883. // Invoke external hooks after the cache is cleared for API consistency.
  884. module_invoke_all('field_purge_instance', $instance);
  885. }
  886. /**
  887. * Purges a field record from the database.
  888. *
  889. * This function assumes all instances for the field has already been purged,
  890. * and should only be called by field_purge_batch().
  891. *
  892. * @param $field
  893. * The field record to purge.
  894. */
  895. function field_purge_field($field) {
  896. $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
  897. if (count($instances) > 0) {
  898. throw new FieldException(t('Attempt to purge a field @field_name that still has instances.', array('@field_name' => $field['field_name'])));
  899. }
  900. db_delete('field_config')
  901. ->condition('id', $field['id'])
  902. ->execute();
  903. // Notify the storage engine.
  904. module_invoke($field['storage']['module'], 'field_storage_purge_field', $field);
  905. // Clear the cache.
  906. field_info_cache_clear();
  907. // Invoke external hooks after the cache is cleared for API consistency.
  908. module_invoke_all('field_purge_field', $field);
  909. }
  910. /**
  911. * @} End of "defgroup field_purge".
  912. */

Functions

Namesort descending Description
field_create_field Creates a field.
field_create_instance Creates an instance of a field, binding it to a bundle.
field_delete_field Marks a field and its instances and data for deletion.
field_delete_instance Marks a field instance and its data for deletion.
field_purge_batch Purges a batch of deleted Field API data, instances, or fields.
field_purge_data Purges the field data for a single field on a single pseudo-entity.
field_purge_field Purges a field record from the database.
field_purge_instance Purges a field instance record from the database.
field_read_field Reads a single field record directly from the database.
field_read_fields Reads in fields that match an array of conditions.
field_read_instance Reads a single instance record from the database.
field_read_instances Reads in field instances that match an array of conditions.
field_update_field Updates a field.
field_update_instance Updates an instance of a field.
_field_write_instance Stores an instance record in the field configuration database.