field.crud.inc 39 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010
  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(), 'foreign keys' => array());
  228. // 'columns' are hardcoded in the field type.
  229. $field['columns'] = $schema['columns'];
  230. // 'foreign keys' are hardcoded in the field type.
  231. $field['foreign keys'] = $schema['foreign keys'];
  232. // 'indexes' can be both hardcoded in the field type, and specified in the
  233. // incoming $field definition.
  234. $field += array(
  235. 'indexes' => array(),
  236. );
  237. $field['indexes'] += $schema['indexes'];
  238. $has_data = field_has_data($field);
  239. // See if any module forbids the update by throwing an exception.
  240. foreach (module_implements('field_update_forbid') as $module) {
  241. $function = $module . '_field_update_forbid';
  242. $function($field, $prior_field, $has_data);
  243. }
  244. // Tell the storage engine to update the field. Do this before
  245. // saving the new definition since it still might fail.
  246. $storage_type = field_info_storage_types($field['storage']['type']);
  247. module_invoke($storage_type['module'], 'field_storage_update_field', $field, $prior_field, $has_data);
  248. // Save the new field definition. @todo: refactor with
  249. // field_create_field.
  250. // The serialized 'data' column contains everything from $field that does not
  251. // have its own column and is not automatically populated when the field is
  252. // read.
  253. $data = $field;
  254. unset($data['columns'], $data['field_name'], $data['type'], $data['locked'], $data['module'], $data['cardinality'], $data['active'], $data['deleted']);
  255. // Additionally, do not save the 'bundles' property populated by
  256. // field_info_field().
  257. unset($data['bundles']);
  258. $field['data'] = $data;
  259. // Store the field and create the id.
  260. $primary_key = array('id');
  261. drupal_write_record('field_config', $field, $primary_key);
  262. // Clear caches
  263. field_cache_clear(TRUE);
  264. // Invoke external hooks after the cache is cleared for API consistency.
  265. module_invoke_all('field_update_field', $field, $prior_field, $has_data);
  266. }
  267. /**
  268. * Reads a single field record directly from the database.
  269. *
  270. * Generally, you should use the field_info_field() instead.
  271. *
  272. * This function will not return deleted fields. Use
  273. * field_read_fields() instead for this purpose.
  274. *
  275. * @param $field_name
  276. * The field name to read.
  277. * @param array $include_additional
  278. * The default behavior of this function is to not return a field that
  279. * is inactive. Setting
  280. * $include_additional['include_inactive'] to TRUE will override this
  281. * behavior.
  282. * @return
  283. * A field definition array, or FALSE.
  284. */
  285. function field_read_field($field_name, $include_additional = array()) {
  286. $fields = field_read_fields(array('field_name' => $field_name), $include_additional);
  287. return $fields ? current($fields) : FALSE;
  288. }
  289. /**
  290. * Reads in fields that match an array of conditions.
  291. *
  292. * @param array $params
  293. * An array of conditions to match against. Keys are columns from the
  294. * 'field_config' table, values are conditions to match. Additionally,
  295. * conditions on the 'entity_type' and 'bundle' columns from the
  296. * 'field_config_instance' table are supported (select fields having an
  297. * instance on a given bundle).
  298. * @param array $include_additional
  299. * The default behavior of this function is to not return fields that
  300. * are inactive or have been deleted. Setting
  301. * $include_additional['include_inactive'] or
  302. * $include_additional['include_deleted'] to TRUE will override this
  303. * behavior.
  304. * @return
  305. * An array of fields matching $params. If
  306. * $include_additional['include_deleted'] is TRUE, the array is keyed
  307. * by field id, otherwise it is keyed by field name.
  308. */
  309. function field_read_fields($params = array(), $include_additional = array()) {
  310. $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));
  311. $query->fields('fc');
  312. // Turn the conditions into a query.
  313. foreach ($params as $key => $value) {
  314. // Allow filtering on the 'entity_type' and 'bundle' columns of the
  315. // field_config_instance table.
  316. if ($key == 'entity_type' || $key == 'bundle') {
  317. if (empty($fci_join)) {
  318. $fci_join = $query->join('field_config_instance', 'fci', 'fc.id = fci.field_id');
  319. }
  320. $key = 'fci.' . $key;
  321. }
  322. else {
  323. $key = 'fc.' . $key;
  324. }
  325. $query->condition($key, $value);
  326. }
  327. if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) {
  328. $query
  329. ->condition('fc.active', 1)
  330. ->condition('fc.storage_active', 1);
  331. }
  332. $include_deleted = (isset($include_additional['include_deleted']) && $include_additional['include_deleted']);
  333. if (!$include_deleted) {
  334. $query->condition('fc.deleted', 0);
  335. }
  336. $fields = array();
  337. $results = $query->execute();
  338. foreach ($results as $record) {
  339. $field = unserialize($record['data']);
  340. $field['id'] = $record['id'];
  341. $field['field_name'] = $record['field_name'];
  342. $field['type'] = $record['type'];
  343. $field['module'] = $record['module'];
  344. $field['active'] = $record['active'];
  345. $field['storage']['type'] = $record['storage_type'];
  346. $field['storage']['module'] = $record['storage_module'];
  347. $field['storage']['active'] = $record['storage_active'];
  348. $field['locked'] = $record['locked'];
  349. $field['cardinality'] = $record['cardinality'];
  350. $field['translatable'] = $record['translatable'];
  351. $field['deleted'] = $record['deleted'];
  352. module_invoke_all('field_read_field', $field);
  353. // Populate storage information.
  354. module_load_install($field['module']);
  355. $schema = (array) module_invoke($field['module'], 'field_schema', $field);
  356. $schema += array('columns' => array(), 'indexes' => array());
  357. $field['columns'] = $schema['columns'];
  358. $field_name = $field['field_name'];
  359. if ($include_deleted) {
  360. $field_name = $field['id'];
  361. }
  362. $fields[$field_name] = $field;
  363. }
  364. return $fields;
  365. }
  366. /**
  367. * Marks a field and its instances and data for deletion.
  368. *
  369. * @param $field_name
  370. * The field name to delete.
  371. */
  372. function field_delete_field($field_name) {
  373. // Delete all non-deleted instances.
  374. $field = field_info_field($field_name);
  375. if (isset($field['bundles'])) {
  376. foreach ($field['bundles'] as $entity_type => $bundles) {
  377. foreach ($bundles as $bundle) {
  378. $instance = field_info_instance($entity_type, $field_name, $bundle);
  379. field_delete_instance($instance, FALSE);
  380. }
  381. }
  382. }
  383. // Mark field data for deletion.
  384. module_invoke($field['storage']['module'], 'field_storage_delete_field', $field);
  385. // Mark the field for deletion.
  386. db_update('field_config')
  387. ->fields(array('deleted' => 1))
  388. ->condition('field_name', $field_name)
  389. ->execute();
  390. // Clear the cache.
  391. field_cache_clear(TRUE);
  392. module_invoke_all('field_delete_field', $field);
  393. }
  394. /**
  395. * Creates an instance of a field, binding it to a bundle.
  396. *
  397. * @param $instance
  398. * A field instance definition array. The field_name, entity_type and
  399. * bundle properties are required. Other properties, if omitted,
  400. * will be given the following default values:
  401. * - label: the field name
  402. * - description: empty string
  403. * - required: FALSE
  404. * - default_value_function: empty string
  405. * - settings: each omitted setting is given the default value specified in
  406. * hook_field_info().
  407. * - widget:
  408. * - type: the default widget specified in hook_field_info().
  409. * - settings: each omitted setting is given the default value specified in
  410. * hook_field_widget_info().
  411. * - display:
  412. * Settings for the 'default' view mode will be added if not present, and
  413. * each view mode in the definition will be completed with the following
  414. * default values:
  415. * - label: 'above'
  416. * - type: the default formatter specified in hook_field_info().
  417. * - settings: each omitted setting is given the default value specified in
  418. * hook_field_formatter_info().
  419. * View modes not present in the definition are left empty, and the field
  420. * will not be displayed in this mode.
  421. *
  422. * @return
  423. * The $instance array with the id property filled in.
  424. *
  425. * @throws FieldException
  426. *
  427. * See: @link field Field API data structures @endlink.
  428. */
  429. function field_create_instance($instance) {
  430. $field = field_read_field($instance['field_name']);
  431. if (empty($field)) {
  432. 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'])));
  433. }
  434. // Check that the required properties exists.
  435. if (empty($instance['entity_type'])) {
  436. throw new FieldException(t('Attempt to create an instance of field @field_name without an entity type.', array('@field_name' => $instance['field_name'])));
  437. }
  438. if (empty($instance['bundle'])) {
  439. throw new FieldException(t('Attempt to create an instance of field @field_name without a bundle.', array('@field_name' => $instance['field_name'])));
  440. }
  441. // Check that the field can be attached to this entity type.
  442. if (!empty($field['entity_types']) && !in_array($instance['entity_type'], $field['entity_types'])) {
  443. 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'])));
  444. }
  445. // Set the field id.
  446. $instance['field_id'] = $field['id'];
  447. // Note that we do *not* prevent creating a field on non-existing bundles,
  448. // because that would break the 'Body as field' upgrade for contrib
  449. // node types.
  450. // TODO: Check that the widget type is known and can handle the field type ?
  451. // TODO: Check that the formatters are known and can handle the field type ?
  452. // TODO: Check that the display view modes are known for the entity type ?
  453. // Those checks should probably happen in _field_write_instance() ?
  454. // Problem : this would mean that a UI module cannot update an instance with a disabled formatter.
  455. // Ensure the field instance is unique within the bundle.
  456. // We only check for instances of active fields, since adding an instance of
  457. // a disabled field is not supported.
  458. $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle']);
  459. if (!empty($prior_instance)) {
  460. $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']));
  461. throw new FieldException($message);
  462. }
  463. _field_write_instance($instance);
  464. // Clear caches
  465. field_cache_clear();
  466. // Invoke external hooks after the cache is cleared for API consistency.
  467. module_invoke_all('field_create_instance', $instance);
  468. return $instance;
  469. }
  470. /**
  471. * Updates an instance of a field.
  472. *
  473. * @param $instance
  474. * An associative array representing an instance structure. The following
  475. * required array elements specify which field instance is being updated:
  476. * - entity_type: The type of the entity the field is attached to.
  477. * - bundle: The bundle this field belongs to.
  478. * - field_name: The name of an existing field.
  479. * The other array elements represent properties of the instance, and all
  480. * properties must be specified or their default values will be used (except
  481. * internal-use properties, which are assigned automatically). To avoid
  482. * losing the previously stored properties of the instance when making a
  483. * change, first load the instance with field_info_instance(), then override
  484. * the values you want to override, and finally save using this function.
  485. * Example:
  486. * @code
  487. * // Fetch an instance info array.
  488. * $instance_info = field_info_instance($entity_type, $field_name, $bundle_name);
  489. * // Change a single property in the instance definition.
  490. * $instance_info['definition']['required'] = TRUE;
  491. * // Write the changed definition back.
  492. * field_update_instance($instance_info['definition']);
  493. * @endcode
  494. *
  495. * @throws FieldException
  496. *
  497. * @see field_info_instance()
  498. * @see field_create_instance()
  499. */
  500. function field_update_instance($instance) {
  501. // Check that the specified field exists.
  502. $field = field_read_field($instance['field_name']);
  503. if (empty($field)) {
  504. throw new FieldException(t('Attempt to update an instance of a nonexistent field @field.', array('@field' => $instance['field_name'])));
  505. }
  506. // Check that the field instance exists (even if it is inactive, since we
  507. // want to be able to replace inactive widgets with new ones).
  508. $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE));
  509. if (empty($prior_instance)) {
  510. 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'])));
  511. }
  512. $instance['id'] = $prior_instance['id'];
  513. $instance['field_id'] = $prior_instance['field_id'];
  514. _field_write_instance($instance, TRUE);
  515. // Clear caches.
  516. field_cache_clear();
  517. module_invoke_all('field_update_instance', $instance, $prior_instance);
  518. }
  519. /**
  520. * Stores an instance record in the field configuration database.
  521. *
  522. * @param $instance
  523. * An instance structure.
  524. * @param $update
  525. * Whether this is a new or existing instance.
  526. */
  527. function _field_write_instance($instance, $update = FALSE) {
  528. $field = field_read_field($instance['field_name']);
  529. $field_type = field_info_field_types($field['type']);
  530. // Set defaults.
  531. $instance += array(
  532. 'settings' => array(),
  533. 'display' => array(),
  534. 'widget' => array(),
  535. 'required' => FALSE,
  536. 'label' => $instance['field_name'],
  537. 'description' => '',
  538. 'deleted' => 0,
  539. );
  540. // Set default instance settings.
  541. $instance['settings'] += field_info_instance_settings($field['type']);
  542. // Set default widget and settings.
  543. $instance['widget'] += array(
  544. // TODO: what if no 'default_widget' specified ?
  545. 'type' => $field_type['default_widget'],
  546. 'settings' => array(),
  547. );
  548. // If no weight specified, make sure the field sinks at the bottom.
  549. if (!isset($instance['widget']['weight'])) {
  550. $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], 'form');
  551. $instance['widget']['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
  552. }
  553. // Check widget module.
  554. $widget_type = field_info_widget_types($instance['widget']['type']);
  555. $instance['widget']['module'] = $widget_type['module'];
  556. $instance['widget']['settings'] += field_info_widget_settings($instance['widget']['type']);
  557. // Make sure there are at least display settings for the 'default' view mode,
  558. // and fill in defaults for each view mode specified in the definition.
  559. $instance['display'] += array(
  560. 'default' => array(),
  561. );
  562. foreach ($instance['display'] as $view_mode => $display) {
  563. $display += array(
  564. 'label' => 'above',
  565. 'type' => isset($field_type['default_formatter']) ? $field_type['default_formatter'] : 'hidden',
  566. 'settings' => array(),
  567. );
  568. if ($display['type'] != 'hidden') {
  569. $formatter_type = field_info_formatter_types($display['type']);
  570. $display['module'] = $formatter_type['module'];
  571. $display['settings'] += field_info_formatter_settings($display['type']);
  572. }
  573. // If no weight specified, make sure the field sinks at the bottom.
  574. if (!isset($display['weight'])) {
  575. $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], $view_mode);
  576. $display['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
  577. }
  578. $instance['display'][$view_mode] = $display;
  579. }
  580. // The serialized 'data' column contains everything from $instance that does
  581. // not have its own column and is not automatically populated when the
  582. // instance is read.
  583. $data = $instance;
  584. unset($data['id'], $data['field_id'], $data['field_name'], $data['entity_type'], $data['bundle'], $data['deleted']);
  585. $record = array(
  586. 'field_id' => $instance['field_id'],
  587. 'field_name' => $instance['field_name'],
  588. 'entity_type' => $instance['entity_type'],
  589. 'bundle' => $instance['bundle'],
  590. 'data' => $data,
  591. 'deleted' => $instance['deleted'],
  592. );
  593. // We need to tell drupal_update_record() the primary keys to trigger an
  594. // update.
  595. if ($update) {
  596. $record['id'] = $instance['id'];
  597. $primary_key = array('id');
  598. }
  599. else {
  600. $primary_key = array();
  601. }
  602. drupal_write_record('field_config_instance', $record, $primary_key);
  603. }
  604. /**
  605. * Reads a single instance record from the database.
  606. *
  607. * Generally, you should use field_info_instance() instead, as it
  608. * provides caching and allows other modules the opportunity to
  609. * append additional formatters, widgets, and other information.
  610. *
  611. * @param $entity_type
  612. * The type of entity to which the field is bound.
  613. * @param $field_name
  614. * The field name to read.
  615. * @param $bundle
  616. * The bundle to which the field is bound.
  617. * @param array $include_additional
  618. * The default behavior of this function is to not return an instance that
  619. * has been deleted, or whose field is inactive. Setting
  620. * $include_additional['include_inactive'] or
  621. * $include_additional['include_deleted'] to TRUE will override this
  622. * behavior.
  623. * @return
  624. * An instance structure, or FALSE.
  625. */
  626. function field_read_instance($entity_type, $field_name, $bundle, $include_additional = array()) {
  627. $instances = field_read_instances(array('entity_type' => $entity_type, 'field_name' => $field_name, 'bundle' => $bundle), $include_additional);
  628. return $instances ? current($instances) : FALSE;
  629. }
  630. /**
  631. * Reads in field instances that match an array of conditions.
  632. *
  633. * @param $param
  634. * An array of properties to use in selecting a field
  635. * instance. Valid keys include any column of the
  636. * field_config_instance table. If NULL, all instances will be returned.
  637. * @param $include_additional
  638. * The default behavior of this function is to not return field
  639. * instances that have been marked deleted, or whose field is inactive.
  640. * Setting $include_additional['include_inactive'] or
  641. * $include_additional['include_deleted'] to TRUE will override this
  642. * behavior.
  643. * @return
  644. * An array of instances matching the arguments.
  645. */
  646. function field_read_instances($params = array(), $include_additional = array()) {
  647. $include_inactive = isset($include_additional['include_inactive']) && $include_additional['include_inactive'];
  648. $include_deleted = isset($include_additional['include_deleted']) && $include_additional['include_deleted'];
  649. $query = db_select('field_config_instance', 'fci', array('fetch' => PDO::FETCH_ASSOC));
  650. $query->join('field_config', 'fc', 'fc.id = fci.field_id');
  651. $query->fields('fci');
  652. // Turn the conditions into a query.
  653. foreach ($params as $key => $value) {
  654. $query->condition('fci.' . $key, $value);
  655. }
  656. if (!$include_inactive) {
  657. $query
  658. ->condition('fc.active', 1)
  659. ->condition('fc.storage_active', 1);
  660. }
  661. if (!$include_deleted) {
  662. $query->condition('fc.deleted', 0);
  663. $query->condition('fci.deleted', 0);
  664. }
  665. $instances = array();
  666. $results = $query->execute();
  667. foreach ($results as $record) {
  668. // Filter out instances on unknown entity types (for instance because the
  669. // module exposing them was disabled).
  670. $entity_info = entity_get_info($record['entity_type']);
  671. if ($include_inactive || $entity_info) {
  672. $instance = unserialize($record['data']);
  673. $instance['id'] = $record['id'];
  674. $instance['field_id'] = $record['field_id'];
  675. $instance['field_name'] = $record['field_name'];
  676. $instance['entity_type'] = $record['entity_type'];
  677. $instance['bundle'] = $record['bundle'];
  678. $instance['deleted'] = $record['deleted'];
  679. module_invoke_all('field_read_instance', $instance);
  680. $instances[] = $instance;
  681. }
  682. }
  683. return $instances;
  684. }
  685. /**
  686. * Marks a field instance and its data for deletion.
  687. *
  688. * @param $instance
  689. * An instance structure.
  690. * @param $field_cleanup
  691. * If TRUE, the field will be deleted as well if its last instance is being
  692. * deleted. If FALSE, it is the caller's responsibility to handle the case of
  693. * fields left without instances. Defaults to TRUE.
  694. */
  695. function field_delete_instance($instance, $field_cleanup = TRUE) {
  696. // Mark the field instance for deletion.
  697. db_update('field_config_instance')
  698. ->fields(array('deleted' => 1))
  699. ->condition('field_name', $instance['field_name'])
  700. ->condition('entity_type', $instance['entity_type'])
  701. ->condition('bundle', $instance['bundle'])
  702. ->execute();
  703. // Clear the cache.
  704. field_cache_clear();
  705. // Mark instance data for deletion.
  706. $field = field_info_field($instance['field_name']);
  707. module_invoke($field['storage']['module'], 'field_storage_delete_instance', $instance);
  708. // Let modules react to the deletion of the instance.
  709. module_invoke_all('field_delete_instance', $instance);
  710. // Delete the field itself if we just deleted its last instance.
  711. if ($field_cleanup && count($field['bundles']) == 0) {
  712. field_delete_field($field['field_name']);
  713. }
  714. }
  715. /**
  716. * @} End of "defgroup field_crud".
  717. */
  718. /**
  719. * @defgroup field_purge Field API bulk data deletion
  720. * @{
  721. * Clean up after Field API bulk deletion operations.
  722. *
  723. * Field API provides functions for deleting data attached to individual
  724. * entities as well as deleting entire fields or field instances in a single
  725. * operation.
  726. *
  727. * Deleting field data items for an entity with field_attach_delete() involves
  728. * three separate operations:
  729. * - Invoking the Field Type API hook_field_delete() for each field on the
  730. * entity. The hook for each field type receives the entity and the specific
  731. * field being deleted. A file field module might use this hook to delete
  732. * uploaded files from the filesystem.
  733. * - Invoking the Field Storage API hook_field_storage_delete() to remove
  734. * data from the primary field storage. The hook implementation receives the
  735. * entity being deleted and deletes data for all of the entity's bundle's
  736. * fields.
  737. * - Invoking the global Field Attach API hook_field_attach_delete() for all
  738. * modules that implement it. Each hook implementation receives the entity
  739. * being deleted and can operate on whichever subset of the entity's bundle's
  740. * fields it chooses to.
  741. *
  742. * These hooks are invoked immediately when field_attach_delete() is
  743. * called. Similar operations are performed for field_attach_delete_revision().
  744. *
  745. * When a field, bundle, or field instance is deleted, it is not practical to
  746. * invoke these hooks immediately on every affected entity in a single page
  747. * request; there could be thousands or millions of them. Instead, the
  748. * appropriate field data items, instances, and/or fields are marked as deleted
  749. * so that subsequent load or query operations will not return them. Later, a
  750. * separate process cleans up, or "purges", the marked-as-deleted data by going
  751. * through the three-step process described above and, finally, removing
  752. * deleted field and instance records.
  753. *
  754. * Purging field data is made somewhat tricky by the fact that, while
  755. * field_attach_delete() has a complete entity to pass to the various deletion
  756. * hooks, the Field API purge process only has the field data it has previously
  757. * stored. It cannot reconstruct complete original entities to pass to the
  758. * deletion hooks. It is even possible that the original entity to which some
  759. * Field API data was attached has been itself deleted before the field purge
  760. * operation takes place.
  761. *
  762. * Field API resolves this problem by using "pseudo-entities" during purge
  763. * operations. A pseudo-entity contains only the information from the original
  764. * entity that Field API knows about: entity type, id, revision id, and
  765. * bundle. It also contains the field data for whichever field instance is
  766. * currently being purged. For example, suppose that the node type 'story' used
  767. * to contain a field called 'subtitle' but the field was deleted. If node 37
  768. * was a story with a subtitle, the pseudo-entity passed to the purge hooks
  769. * would look something like this:
  770. *
  771. * @code
  772. * $entity = stdClass Object(
  773. * [nid] => 37,
  774. * [vid] => 37,
  775. * [type] => 'story',
  776. * [subtitle] => array(
  777. * [0] => array(
  778. * 'value' => 'subtitle text',
  779. * ),
  780. * ),
  781. * );
  782. * @endcode
  783. *
  784. * See @link field Field API @endlink for information about the other parts of
  785. * the Field API.
  786. */
  787. /**
  788. * Purges a batch of deleted Field API data, instances, or fields.
  789. *
  790. * This function will purge deleted field data in batches. The batch size
  791. * is defined as an argument to the function, and once each batch is finished,
  792. * it continues with the next batch until all have completed. If a deleted field
  793. * instance with no remaining data records is found, the instance itself will
  794. * be purged. If a deleted field with no remaining field instances is found, the
  795. * field itself will be purged.
  796. *
  797. * @param $batch_size
  798. * The maximum number of field data records to purge before returning.
  799. */
  800. function field_purge_batch($batch_size) {
  801. // Retrieve all deleted field instances. We cannot use field_info_instances()
  802. // because that function does not return deleted instances.
  803. $instances = field_read_instances(array('deleted' => 1), array('include_deleted' => 1));
  804. foreach ($instances as $instance) {
  805. // field_purge_data() will need the field array.
  806. $field = field_info_field_by_id($instance['field_id']);
  807. // Retrieve some entities.
  808. $query = new EntityFieldQuery();
  809. $results = $query
  810. ->fieldCondition($field)
  811. ->entityCondition('bundle', $instance['bundle'])
  812. ->deleted(TRUE)
  813. ->range(0, $batch_size)
  814. ->execute();
  815. if ($results) {
  816. foreach ($results as $entity_type => $stub_entities) {
  817. field_attach_load($entity_type, $stub_entities, FIELD_LOAD_CURRENT, array('field_id' => $field['id'], 'deleted' => 1));
  818. foreach ($stub_entities as $stub_entity) {
  819. // Purge the data for the entity.
  820. field_purge_data($entity_type, $stub_entity, $field, $instance);
  821. }
  822. }
  823. }
  824. else {
  825. // No field data remains for the instance, so we can remove it.
  826. field_purge_instance($instance);
  827. }
  828. }
  829. // Retrieve all deleted fields. Any that have no instances can be purged.
  830. $fields = field_read_fields(array('deleted' => 1), array('include_deleted' => 1));
  831. foreach ($fields as $field) {
  832. $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
  833. if (empty($instances)) {
  834. field_purge_field($field);
  835. }
  836. }
  837. }
  838. /**
  839. * Purges the field data for a single field on a single pseudo-entity.
  840. *
  841. * This is basically the same as field_attach_delete() except it only applies
  842. * to a single field. The entity itself is not being deleted, and it is quite
  843. * possible that other field data will remain attached to it.
  844. *
  845. * @param $entity_type
  846. * The type of $entity; e.g. 'node' or 'user'.
  847. * @param $entity
  848. * The pseudo-entity whose field data is being purged.
  849. * @param $field
  850. * The (possibly deleted) field whose data is being purged.
  851. * @param $instance
  852. * The deleted field instance whose data is being purged.
  853. */
  854. function field_purge_data($entity_type, $entity, $field, $instance) {
  855. // Each field type's hook_field_delete() only expects to operate on a single
  856. // field at a time, so we can use it as-is for purging.
  857. $options = array('field_id' => $instance['field_id'], 'deleted' => TRUE);
  858. _field_invoke('delete', $entity_type, $entity, $dummy, $dummy, $options);
  859. // Tell the field storage system to purge the data.
  860. module_invoke($field['storage']['module'], 'field_storage_purge', $entity_type, $entity, $field, $instance);
  861. // Let other modules act on purging the data.
  862. foreach (module_implements('field_attach_purge') as $module) {
  863. $function = $module . '_field_attach_purge';
  864. $function($entity_type, $entity, $field, $instance);
  865. }
  866. }
  867. /**
  868. * Purges a field instance record from the database.
  869. *
  870. * This function assumes all data for the instance has already been purged, and
  871. * should only be called by field_purge_batch().
  872. *
  873. * @param $instance
  874. * The instance record to purge.
  875. */
  876. function field_purge_instance($instance) {
  877. db_delete('field_config_instance')
  878. ->condition('id', $instance['id'])
  879. ->execute();
  880. // Notify the storage engine.
  881. $field = field_info_field_by_id($instance['field_id']);
  882. module_invoke($field['storage']['module'], 'field_storage_purge_instance', $instance);
  883. // Clear the cache.
  884. field_info_cache_clear();
  885. // Invoke external hooks after the cache is cleared for API consistency.
  886. module_invoke_all('field_purge_instance', $instance);
  887. }
  888. /**
  889. * Purges a field record from the database.
  890. *
  891. * This function assumes all instances for the field has already been purged,
  892. * and should only be called by field_purge_batch().
  893. *
  894. * @param $field
  895. * The field record to purge.
  896. */
  897. function field_purge_field($field) {
  898. $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
  899. if (count($instances) > 0) {
  900. throw new FieldException(t('Attempt to purge a field @field_name that still has instances.', array('@field_name' => $field['field_name'])));
  901. }
  902. db_delete('field_config')
  903. ->condition('id', $field['id'])
  904. ->execute();
  905. // Notify the storage engine.
  906. module_invoke($field['storage']['module'], 'field_storage_purge_field', $field);
  907. // Clear the cache.
  908. field_info_cache_clear();
  909. // Invoke external hooks after the cache is cleared for API consistency.
  910. module_invoke_all('field_purge_field', $field);
  911. }
  912. /**
  913. * @} End of "defgroup field_purge".
  914. */