File

modules/field/field.info.class.inc
View source
  1. <?php
  2. /*
  3. * @file
  4. * Definition of the FieldInfo class.
  5. */
  6. /**
  7. * Provides field and instance definitions for the current runtime environment.
  8. *
  9. * A FieldInfo object is created and statically persisted through the request
  10. * by the _field_info_field_cache() function. The object properties act as a
  11. * "static cache" of fields and instances definitions.
  12. *
  13. * The preferred way to access definitions is through the getBundleInstances()
  14. * method, which keeps cache entries per bundle, storing both fields and
  15. * instances for a given bundle. Fields used in multiple bundles are duplicated
  16. * in several cache entries, and are merged into a single list in the memory
  17. * cache. Cache entries are loaded for bundles as a whole, optimizing memory
  18. * and CPU usage for the most common pattern of iterating over all instances of
  19. * a bundle rather than accessing a single instance.
  20. *
  21. * The getFields() and getInstances() methods, which return all existing field
  22. * and instance definitions, are kept mainly for backwards compatibility, and
  23. * should be avoided when possible, since they load and persist in memory a
  24. * potentially large array of information. In many cases, the lightweight
  25. * getFieldMap() method should be preferred.
  26. */
  27. class FieldInfo {
  28. /**
  29. * Lightweight map of fields across entity types and bundles.
  30. *
  31. * @var array
  32. */
  33. protected $fieldMap;
  34. /**
  35. * List of $field structures keyed by ID. Includes deleted fields.
  36. *
  37. * @var array
  38. */
  39. protected $fieldsById = array();
  40. /**
  41. * Mapping of field names to the ID of the corresponding non-deleted field.
  42. *
  43. * @var array
  44. */
  45. protected $fieldIdsByName = array();
  46. /**
  47. * Whether $fieldsById contains all field definitions or a subset.
  48. *
  49. * @var bool
  50. */
  51. protected $loadedAllFields = FALSE;
  52. /**
  53. * Separately tracks requested field names or IDs that do not exist.
  54. *
  55. * @var array
  56. */
  57. protected $unknownFields = array();
  58. /**
  59. * Instance definitions by bundle.
  60. *
  61. * @var array
  62. */
  63. protected $bundleInstances = array();
  64. /**
  65. * Whether $bundleInstances contains all instances definitions or a subset.
  66. *
  67. * @var bool
  68. */
  69. protected $loadedAllInstances = FALSE;
  70. /**
  71. * Separately tracks requested bundles that are empty (or do not exist).
  72. *
  73. * @var array
  74. */
  75. protected $emptyBundles = array();
  76. /**
  77. * Extra fields by bundle.
  78. *
  79. * @var array
  80. */
  81. protected $bundleExtraFields = array();
  82. /**
  83. * Clears the "static" and persistent caches.
  84. */
  85. public function flush() {
  86. $this->fieldMap = NULL;
  87. $this->fieldsById = array();
  88. $this->fieldIdsByName = array();
  89. $this->loadedAllFields = FALSE;
  90. $this->unknownFields = array();
  91. $this->bundleInstances = array();
  92. $this->loadedAllInstances = FALSE;
  93. $this->emptyBundles = array();
  94. $this->bundleExtraFields = array();
  95. cache_clear_all('field_info:', 'cache_field', TRUE);
  96. }
  97. /**
  98. * Collects a lightweight map of fields across bundles.
  99. *
  100. * @return
  101. * An array keyed by field name. Each value is an array with two entries:
  102. * - type: The field type.
  103. * - bundles: The bundles in which the field appears, as an array with
  104. * entity types as keys and the array of bundle names as values.
  105. */
  106. public function getFieldMap() {
  107. // Read from the "static" cache.
  108. if ($this->fieldMap !== NULL) {
  109. return $this->fieldMap;
  110. }
  111. // Read from persistent cache.
  112. if ($cached = cache_get('field_info:field_map', 'cache_field')) {
  113. $map = $cached->data;
  114. // Save in "static" cache.
  115. $this->fieldMap = $map;
  116. return $map;
  117. }
  118. $map = array();
  119. $query = db_query('SELECT fc.type, fci.field_name, fci.entity_type, fci.bundle FROM {field_config_instance} fci INNER JOIN {field_config} fc ON fc.id = fci.field_id WHERE fc.active = 1 AND fc.storage_active = 1 AND fc.deleted = 0 AND fci.deleted = 0');
  120. foreach ($query as $row) {
  121. $map[$row->field_name]['bundles'][$row->entity_type][] = $row->bundle;
  122. $map[$row->field_name]['type'] = $row->type;
  123. }
  124. // Save in "static" and persistent caches.
  125. $this->fieldMap = $map;
  126. if (lock_acquire('field_info:field_map')) {
  127. cache_set('field_info:field_map', $map, 'cache_field');
  128. lock_release('field_info:field_map');
  129. }
  130. return $map;
  131. }
  132. /**
  133. * Returns all active fields, including deleted ones.
  134. *
  135. * @return
  136. * An array of field definitions, keyed by field ID.
  137. */
  138. public function getFields() {
  139. // Read from the "static" cache.
  140. if ($this->loadedAllFields) {
  141. return $this->fieldsById;
  142. }
  143. // Read from persistent cache.
  144. if ($cached = cache_get('field_info:fields', 'cache_field')) {
  145. $this->fieldsById = $cached->data;
  146. }
  147. else {
  148. // Collect and prepare fields.
  149. foreach (field_read_fields(array(), array('include_deleted' => TRUE)) as $field) {
  150. $this->fieldsById[$field['id']] = $this->prepareField($field);
  151. }
  152. // Store in persistent cache.
  153. if (lock_acquire('field_info:fields')) {
  154. cache_set('field_info:fields', $this->fieldsById, 'cache_field');
  155. lock_release('field_info:fields');
  156. }
  157. }
  158. // Fill the name/ID map.
  159. foreach ($this->fieldsById as $field) {
  160. if (!$field['deleted']) {
  161. $this->fieldIdsByName[$field['field_name']] = $field['id'];
  162. }
  163. }
  164. $this->loadedAllFields = TRUE;
  165. return $this->fieldsById;
  166. }
  167. /**
  168. * Retrieves all active, non-deleted instances definitions.
  169. *
  170. * @param $entity_type
  171. * (optional) The entity type.
  172. *
  173. * @return
  174. * If $entity_type is not set, all instances keyed by entity type and bundle
  175. * name. If $entity_type is set, all instances for that entity type, keyed
  176. * by bundle name.
  177. */
  178. public function getInstances($entity_type = NULL) {
  179. // If the full list is not present in "static" cache yet.
  180. if (!$this->loadedAllInstances) {
  181. // Read from persistent cache.
  182. if ($cached = cache_get('field_info:instances', 'cache_field')) {
  183. $this->bundleInstances = $cached->data;
  184. }
  185. else {
  186. // Collect and prepare instances.
  187. // We also need to populate the static field cache, since it will not
  188. // be set by subsequent getBundleInstances() calls.
  189. $this->getFields();
  190. // Initialize empty arrays for all existing entity types and bundles.
  191. // This is not strictly needed, but is done to preserve the behavior of
  192. // field_info_instances() before http://drupal.org/node/1915646.
  193. foreach (field_info_bundles() as $existing_entity_type => $bundles) {
  194. foreach ($bundles as $bundle => $bundle_info) {
  195. $this->bundleInstances[$existing_entity_type][$bundle] = array();
  196. }
  197. }
  198. foreach (field_read_instances() as $instance) {
  199. $field = $this->getField($instance['field_name']);
  200. $instance = $this->prepareInstance($instance, $field['type']);
  201. $this->bundleInstances[$instance['entity_type']][$instance['bundle']][$instance['field_name']] = $instance;
  202. }
  203. // Store in persistent cache.
  204. if (lock_acquire('field_info:instances')) {
  205. cache_set('field_info:instances', $this->bundleInstances, 'cache_field');
  206. lock_release('field_info:instances');
  207. }
  208. }
  209. $this->loadedAllInstances = TRUE;
  210. }
  211. if (isset($entity_type)) {
  212. return isset($this->bundleInstances[$entity_type]) ? $this->bundleInstances[$entity_type] : array();
  213. }
  214. else {
  215. return $this->bundleInstances;
  216. }
  217. }
  218. /**
  219. * Returns a field definition from a field name.
  220. *
  221. * This method only retrieves active, non-deleted fields.
  222. *
  223. * @param $field_name
  224. * The field name.
  225. *
  226. * @return
  227. * The field definition, or NULL if no field was found.
  228. */
  229. public function getField($field_name) {
  230. // Read from the "static" cache.
  231. if (isset($this->fieldIdsByName[$field_name])) {
  232. $field_id = $this->fieldIdsByName[$field_name];
  233. return $this->fieldsById[$field_id];
  234. }
  235. if (isset($this->unknownFields[$field_name])) {
  236. return;
  237. }
  238. // Do not check the (large) persistent cache, but read the definition.
  239. // Cache miss: read from definition.
  240. if ($field = field_read_field($field_name)) {
  241. $field = $this->prepareField($field);
  242. // Save in the "static" cache.
  243. $this->fieldsById[$field['id']] = $field;
  244. $this->fieldIdsByName[$field['field_name']] = $field['id'];
  245. return $field;
  246. }
  247. else {
  248. $this->unknownFields[$field_name] = TRUE;
  249. }
  250. }
  251. /**
  252. * Returns a field definition from a field ID.
  253. *
  254. * This method only retrieves active fields, deleted or not.
  255. *
  256. * @param $field_id
  257. * The field ID.
  258. *
  259. * @return
  260. * The field definition, or NULL if no field was found.
  261. */
  262. public function getFieldById($field_id) {
  263. // Read from the "static" cache.
  264. if (isset($this->fieldsById[$field_id])) {
  265. return $this->fieldsById[$field_id];
  266. }
  267. if (isset($this->unknownFields[$field_id])) {
  268. return;
  269. }
  270. // No persistent cache, fields are only persistently cached as part of a
  271. // bundle.
  272. // Cache miss: read from definition.
  273. if ($fields = field_read_fields(array('id' => $field_id), array('include_deleted' => TRUE))) {
  274. $field = current($fields);
  275. $field = $this->prepareField($field);
  276. // Store in the static cache.
  277. $this->fieldsById[$field['id']] = $field;
  278. if (!$field['deleted']) {
  279. $this->fieldIdsByName[$field['field_name']] = $field['id'];
  280. }
  281. return $field;
  282. }
  283. else {
  284. $this->unknownFields[$field_id] = TRUE;
  285. }
  286. }
  287. /**
  288. * Retrieves the instances for a bundle.
  289. *
  290. * The function also populates the corresponding field definitions in the
  291. * "static" cache.
  292. *
  293. * @param $entity_type
  294. * The entity type.
  295. * @param $bundle
  296. * The bundle name.
  297. *
  298. * @return
  299. * The array of instance definitions, keyed by field name.
  300. */
  301. public function getBundleInstances($entity_type, $bundle) {
  302. // Read from the "static" cache.
  303. if (isset($this->bundleInstances[$entity_type][$bundle])) {
  304. return $this->bundleInstances[$entity_type][$bundle];
  305. }
  306. if (isset($this->emptyBundles[$entity_type][$bundle])) {
  307. return array();
  308. }
  309. // Read from the persistent cache.
  310. if ($cached = cache_get("field_info:bundle:$entity_type:$bundle", 'cache_field')) {
  311. $info = $cached->data;
  312. // Extract the field definitions and save them in the "static" cache.
  313. foreach ($info['fields'] as $field) {
  314. if (!isset($this->fieldsById[$field['id']])) {
  315. $this->fieldsById[$field['id']] = $field;
  316. if (!$field['deleted']) {
  317. $this->fieldIdsByName[$field['field_name']] = $field['id'];
  318. }
  319. }
  320. }
  321. unset($info['fields']);
  322. // Store the instance definitions in the "static" cache'. Empty (or
  323. // non-existent) bundles are stored separately, so that they do not
  324. // pollute the global list returned by getInstances().
  325. if ($info['instances']) {
  326. $this->bundleInstances[$entity_type][$bundle] = $info['instances'];
  327. }
  328. else {
  329. $this->emptyBundles[$entity_type][$bundle] = TRUE;
  330. }
  331. return $info['instances'];
  332. }
  333. // Cache miss: collect from the definitions.
  334. $instances = array();
  335. // Collect the fields in the bundle.
  336. $params = array('entity_type' => $entity_type, 'bundle' => $bundle);
  337. $fields = field_read_fields($params);
  338. // This iterates on non-deleted instances, so deleted fields are kept out of
  339. // the persistent caches.
  340. foreach (field_read_instances($params) as $instance) {
  341. $field = $fields[$instance['field_name']];
  342. $instance = $this->prepareInstance($instance, $field['type']);
  343. $instances[$field['field_name']] = $instance;
  344. // If the field is not in our global "static" list yet, add it.
  345. if (!isset($this->fieldsById[$field['id']])) {
  346. $field = $this->prepareField($field);
  347. $this->fieldsById[$field['id']] = $field;
  348. $this->fieldIdsByName[$field['field_name']] = $field['id'];
  349. }
  350. }
  351. // Store in the 'static' cache'. Empty (or non-existent) bundles are stored
  352. // separately, so that they do not pollute the global list returned by
  353. // getInstances().
  354. if ($instances) {
  355. $this->bundleInstances[$entity_type][$bundle] = $instances;
  356. }
  357. else {
  358. $this->emptyBundles[$entity_type][$bundle] = TRUE;
  359. }
  360. // The persistent cache additionally contains the definitions of the fields
  361. // involved in the bundle.
  362. $cache = array(
  363. 'instances' => $instances,
  364. 'fields' => array()
  365. );
  366. foreach ($instances as $instance) {
  367. $cache['fields'][] = $this->fieldsById[$instance['field_id']];
  368. }
  369. if (lock_acquire("field_info:bundle:$entity_type:$bundle")) {
  370. cache_set("field_info:bundle:$entity_type:$bundle", $cache, 'cache_field');
  371. lock_release("field_info:bundle:$entity_type:$bundle");
  372. }
  373. return $instances;
  374. }
  375. /**
  376. * Retrieves the "extra fields" for a bundle.
  377. *
  378. * @param $entity_type
  379. * The entity type.
  380. * @param $bundle
  381. * The bundle name.
  382. *
  383. * @return
  384. * The array of extra fields.
  385. */
  386. public function getBundleExtraFields($entity_type, $bundle) {
  387. // Read from the "static" cache.
  388. if (isset($this->bundleExtraFields[$entity_type][$bundle])) {
  389. return $this->bundleExtraFields[$entity_type][$bundle];
  390. }
  391. // Read from the persistent cache.
  392. if ($cached = cache_get("field_info:bundle_extra:$entity_type:$bundle", 'cache_field')) {
  393. $this->bundleExtraFields[$entity_type][$bundle] = $cached->data;
  394. return $this->bundleExtraFields[$entity_type][$bundle];
  395. }
  396. // Cache miss: read from hook_field_extra_fields(). Note: given the current
  397. // shape of the hook, we have no other way than collecting extra fields on
  398. // all bundles.
  399. $info = array();
  400. $extra = module_invoke_all('field_extra_fields');
  401. drupal_alter('field_extra_fields', $extra);
  402. // Merge in saved settings.
  403. if (isset($extra[$entity_type][$bundle])) {
  404. $info = $this->prepareExtraFields($extra[$entity_type][$bundle], $entity_type, $bundle);
  405. }
  406. // Store in the 'static' and persistent caches.
  407. $this->bundleExtraFields[$entity_type][$bundle] = $info;
  408. if (lock_acquire("field_info:bundle_extra:$entity_type:$bundle")) {
  409. cache_set("field_info:bundle_extra:$entity_type:$bundle", $info, 'cache_field');
  410. lock_release("field_info:bundle_extra:$entity_type:$bundle");
  411. }
  412. return $this->bundleExtraFields[$entity_type][$bundle];
  413. }
  414. /**
  415. * Prepares a field definition for the current run-time context.
  416. *
  417. * @param $field
  418. * The raw field structure as read from the database.
  419. *
  420. * @return
  421. * The field definition completed for the current runtime context.
  422. */
  423. public function prepareField($field) {
  424. // Make sure all expected field settings are present.
  425. $field['settings'] += field_info_field_settings($field['type']);
  426. $field['storage']['settings'] += field_info_storage_settings($field['storage']['type']);
  427. // Add storage details.
  428. $details = (array) module_invoke($field['storage']['module'], 'field_storage_details', $field);
  429. drupal_alter('field_storage_details', $details, $field);
  430. $field['storage']['details'] = $details;
  431. // Populate the list of bundles using the field.
  432. $field['bundles'] = array();
  433. if (!$field['deleted']) {
  434. $map = $this->getFieldMap();
  435. if (isset($map[$field['field_name']])) {
  436. $field['bundles'] = $map[$field['field_name']]['bundles'];
  437. }
  438. }
  439. return $field;
  440. }
  441. /**
  442. * Prepares an instance definition for the current run-time context.
  443. *
  444. * @param $instance
  445. * The raw instance structure as read from the database.
  446. * @param $field_type
  447. * The field type.
  448. *
  449. * @return
  450. * The field instance array completed for the current runtime context.
  451. */
  452. public function prepareInstance($instance, $field_type) {
  453. // Make sure all expected instance settings are present.
  454. $instance['settings'] += field_info_instance_settings($field_type);
  455. // Set a default value for the instance.
  456. if (field_behaviors_widget('default value', $instance) == FIELD_BEHAVIOR_DEFAULT && !isset($instance['default_value'])) {
  457. $instance['default_value'] = NULL;
  458. }
  459. // Prepare widget settings.
  460. $instance['widget'] = $this->prepareInstanceWidget($instance['widget'], $field_type);
  461. // Prepare display settings.
  462. foreach ($instance['display'] as $view_mode => $display) {
  463. $instance['display'][$view_mode] = $this->prepareInstanceDisplay($display, $field_type);
  464. }
  465. // Fall back to 'hidden' for view modes configured to use custom display
  466. // settings, and for which the instance has no explicit settings.
  467. $entity_info = entity_get_info($instance['entity_type']);
  468. $view_modes = array_merge(array('default'), array_keys($entity_info['view modes']));
  469. $view_mode_settings = field_view_mode_settings($instance['entity_type'], $instance['bundle']);
  470. foreach ($view_modes as $view_mode) {
  471. if ($view_mode == 'default' || !empty($view_mode_settings[$view_mode]['custom_settings'])) {
  472. if (!isset($instance['display'][$view_mode])) {
  473. $instance['display'][$view_mode] = array(
  474. 'type' => 'hidden',
  475. 'label' => 'above',
  476. 'settings' => array(),
  477. 'weight' => 0,
  478. );
  479. }
  480. }
  481. }
  482. return $instance;
  483. }
  484. /**
  485. * Prepares widget properties for the current run-time context.
  486. *
  487. * @param $widget
  488. * Widget specifications as found in $instance['widget'].
  489. * @param $field_type
  490. * The field type.
  491. *
  492. * @return
  493. * The widget properties completed for the current runtime context.
  494. */
  495. public function prepareInstanceWidget($widget, $field_type) {
  496. $field_type_info = field_info_field_types($field_type);
  497. // Fill in default values.
  498. $widget += array(
  499. 'type' => $field_type_info['default_widget'],
  500. 'settings' => array(),
  501. 'weight' => 0,
  502. );
  503. $widget_type_info = field_info_widget_types($widget['type']);
  504. // Fall back to default formatter if formatter type is not available.
  505. if (!$widget_type_info) {
  506. $widget['type'] = $field_type_info['default_widget'];
  507. $widget_type_info = field_info_widget_types($widget['type']);
  508. }
  509. $widget['module'] = $widget_type_info['module'];
  510. // Fill in default settings for the widget.
  511. $widget['settings'] += field_info_widget_settings($widget['type']);
  512. return $widget;
  513. }
  514. /**
  515. * Adapts display specifications to the current run-time context.
  516. *
  517. * @param $display
  518. * Display specifications as found in $instance['display']['a_view_mode'].
  519. * @param $field_type
  520. * The field type.
  521. *
  522. * @return
  523. * The display properties completed for the current runtime context.
  524. */
  525. public function prepareInstanceDisplay($display, $field_type) {
  526. $field_type_info = field_info_field_types($field_type);
  527. // Fill in default values.
  528. $display += array(
  529. 'label' => 'above',
  530. 'settings' => array(),
  531. 'weight' => 0,
  532. );
  533. if (empty($display['type'])) {
  534. $display['type'] = $field_type_info['default_formatter'];
  535. }
  536. if ($display['type'] != 'hidden') {
  537. $formatter_type_info = field_info_formatter_types($display['type']);
  538. // Fall back to default formatter if formatter type is not available.
  539. if (!$formatter_type_info) {
  540. $display['type'] = $field_type_info['default_formatter'];
  541. $formatter_type_info = field_info_formatter_types($display['type']);
  542. }
  543. $display['module'] = $formatter_type_info['module'];
  544. // Fill in default settings for the formatter.
  545. $display['settings'] += field_info_formatter_settings($display['type']);
  546. }
  547. return $display;
  548. }
  549. /**
  550. * Prepares 'extra fields' for the current run-time context.
  551. *
  552. * @param $extra_fields
  553. * The array of extra fields, as collected in hook_field_extra_fields().
  554. * @param $entity_type
  555. * The entity type.
  556. * @param $bundle
  557. * The bundle name.
  558. *
  559. * @return
  560. * The list of extra fields completed for the current runtime context.
  561. */
  562. public function prepareExtraFields($extra_fields, $entity_type, $bundle) {
  563. $entity_type_info = entity_get_info($entity_type);
  564. $bundle_settings = field_bundle_settings($entity_type, $bundle);
  565. $extra_fields += array('form' => array(), 'display' => array());
  566. $result = array();
  567. // Extra fields in forms.
  568. foreach ($extra_fields['form'] as $name => $field_data) {
  569. $settings = isset($bundle_settings['extra_fields']['form'][$name]) ? $bundle_settings['extra_fields']['form'][$name] : array();
  570. if (isset($settings['weight'])) {
  571. $field_data['weight'] = $settings['weight'];
  572. }
  573. $result['form'][$name] = $field_data;
  574. }
  575. // Extra fields in displayed entities.
  576. $data = $extra_fields['display'];
  577. foreach ($extra_fields['display'] as $name => $field_data) {
  578. $settings = isset($bundle_settings['extra_fields']['display'][$name]) ? $bundle_settings['extra_fields']['display'][$name] : array();
  579. $view_modes = array_merge(array('default'), array_keys($entity_type_info['view modes']));
  580. foreach ($view_modes as $view_mode) {
  581. if (isset($settings[$view_mode])) {
  582. $field_data['display'][$view_mode] = $settings[$view_mode];
  583. }
  584. else {
  585. $field_data['display'][$view_mode] = array(
  586. 'weight' => $field_data['weight'],
  587. 'visible' => TRUE,
  588. );
  589. }
  590. }
  591. unset($field_data['weight']);
  592. $result['display'][$name] = $field_data;
  593. }
  594. return $result;
  595. }
  596. }

Classes

Namesort descending Description
FieldInfo Provides field and instance definitions for the current runtime environment.