entity.property.inc 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657
  1. <?php
  2. /**
  3. * @file
  4. * Provides API functions around hook_entity_property_info(). Also see
  5. * entity.info.inc, which cares for providing entity property info for all core
  6. * entity types.
  7. */
  8. /**
  9. * Get the entity property info array of an entity type.
  10. *
  11. * @param $entity_type
  12. * The entity type, e.g. node, for which the info shall be returned, or NULL
  13. * to return an array with info about all types.
  14. *
  15. * @see hook_entity_property_info()
  16. * @see hook_entity_property_info_alter()
  17. */
  18. function entity_get_property_info($entity_type = NULL) {
  19. // Use the advanced drupal_static() pattern, since this is called very often.
  20. static $drupal_static_fast;
  21. if (!isset($drupal_static_fast)) {
  22. $drupal_static_fast['info'] = &drupal_static(__FUNCTION__);
  23. }
  24. $info = &$drupal_static_fast['info'];
  25. // hook_entity_property_info() includes translated strings, so each language
  26. // is cached separately.
  27. $langcode = $GLOBALS['language']->language;
  28. if (empty($info)) {
  29. if ($cache = cache_get("entity_property_info:$langcode")) {
  30. $info = $cache->data;
  31. }
  32. else {
  33. $info = module_invoke_all('entity_property_info');
  34. // Let other modules alter the entity info.
  35. drupal_alter('entity_property_info', $info);
  36. cache_set("entity_property_info:$langcode", $info);
  37. }
  38. }
  39. return empty($entity_type) ? $info : (isset($info[$entity_type]) ? $info[$entity_type] : array());
  40. }
  41. /**
  42. * Returns the default information for an entity property.
  43. *
  44. * @return
  45. * An array of optional property information keys mapped to their defaults.
  46. *
  47. * @see hook_entity_property_info()
  48. */
  49. function entity_property_info_defaults() {
  50. return array(
  51. 'type' => 'text',
  52. 'getter callback' => 'entity_property_verbatim_get',
  53. );
  54. }
  55. /**
  56. * Gets an array of info about all properties of a given entity type.
  57. *
  58. * In contrast to entity_get_property_info(), this function returns info about
  59. * all properties the entity might have, thus it adds an all properties assigned
  60. * to entity bundles.
  61. *
  62. * @param $entity_type
  63. * (optiona) The entity type to return properties for.
  64. *
  65. * @return
  66. * An array of info about properties. If the type is ommitted, all known
  67. * properties are returned.
  68. */
  69. function entity_get_all_property_info($entity_type = NULL) {
  70. if (!isset($entity_type)) {
  71. // Retrieve all known properties.
  72. $properties = array();
  73. foreach (entity_get_info() as $entity_type => $info) {
  74. $properties += entity_get_all_property_info($entity_type);
  75. }
  76. return $properties;
  77. }
  78. // Else retrieve the properties of the given entity type only.
  79. $info = entity_get_property_info($entity_type);
  80. $info += array('properties' => array(), 'bundles' => array());
  81. // Add all bundle properties.
  82. foreach ($info['bundles'] as $bundle => $bundle_info) {
  83. $bundle_info += array('properties' => array());
  84. $info['properties'] += $bundle_info['properties'];
  85. }
  86. return $info['properties'];
  87. }
  88. /**
  89. * Queries for entities having the given property value.
  90. *
  91. * @param $entity_type
  92. * The type of the entity.
  93. * @param $property
  94. * The name of the property to query for.
  95. * @param $value
  96. * A single property value or an array of possible values to query for.
  97. * @param $limit
  98. * Limit the numer of results. Defaults to 30.
  99. *
  100. * @return
  101. * An array of entity ids or NULL if there is no information how to query for
  102. * the given property.
  103. */
  104. function entity_property_query($entity_type, $property, $value, $limit = 30) {
  105. $properties = entity_get_all_property_info($entity_type);
  106. $info = $properties[$property] + array('type' => 'text', 'queryable' => !empty($properties[$property]['schema field']));
  107. // We still support the deprecated query callback, so just add in EFQ-based
  108. // callbacks in case 'queryable' is set to TRUE and make use of the callback.
  109. if ($info['queryable'] && empty($info['query callback'])) {
  110. $info['query callback'] = !empty($info['field']) ? 'entity_metadata_field_query' : 'entity_metadata_table_query';
  111. }
  112. $type = $info['type'];
  113. // Make sure an entity or a list of entities are passed on as identifiers
  114. // with the help of the wrappers. For that ensure the data type matches the
  115. // passed on value(s).
  116. if (is_array($value) && !entity_property_list_extract_type($type)) {
  117. $type = 'list<' . $type . '>';
  118. }
  119. elseif (!is_array($value) && entity_property_list_extract_type($type)) {
  120. $type = entity_property_list_extract_type($type);
  121. }
  122. $wrapper = entity_metadata_wrapper($type, $value);
  123. $value = $wrapper->value(array('identifier' => TRUE));
  124. if (!empty($info['query callback'])) {
  125. return $info['query callback']($entity_type, $property, $value, $limit);
  126. }
  127. }
  128. /**
  129. * Resets the cached information of hook_entity_property_info().
  130. */
  131. function entity_property_info_cache_clear() {
  132. drupal_static_reset('entity_get_property_info');
  133. // Clear all languages.
  134. cache_clear_all('entity_property_info:', 'cache', TRUE);
  135. }
  136. /**
  137. * Implements hook_hook_info().
  138. */
  139. function entity_hook_info() {
  140. $hook_info['entity_property_info'] = array(
  141. 'group' => 'info',
  142. );
  143. $hook_info['entity_property_info_alter'] = array(
  144. 'group' => 'info',
  145. );
  146. return $hook_info;
  147. }
  148. /**
  149. * Implements hook_field_info_alter().
  150. * Defines default property types for core field types.
  151. */
  152. function entity_field_info_alter(&$field_info) {
  153. if (module_exists('number')) {
  154. $field_info['number_integer']['property_type'] = 'integer';
  155. $field_info['number_decimal']['property_type'] = 'decimal';
  156. $field_info['number_float']['property_type'] = 'decimal';
  157. }
  158. if (module_exists('text')) {
  159. $field_info['text']['property_type'] = 'text';
  160. $field_info['text']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
  161. $field_info['text_long']['property_type'] = 'text';
  162. $field_info['text_long']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
  163. $field_info['text_with_summary']['property_type'] = 'field_item_textsummary';
  164. $field_info['text_with_summary']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
  165. }
  166. if (module_exists('list')) {
  167. $field_info['list_integer']['property_type'] = 'integer';
  168. $field_info['list_boolean']['property_type'] = 'boolean';
  169. $field_info['list_float']['property_type'] = 'decimal';
  170. $field_info['list_text']['property_type'] = 'text';
  171. }
  172. if (module_exists('taxonomy')) {
  173. $field_info['taxonomy_term_reference']['property_type'] = 'taxonomy_term';
  174. $field_info['taxonomy_term_reference']['property_callbacks'][] = 'entity_metadata_field_term_reference_callback';
  175. }
  176. if (module_exists('file')) {
  177. // The callback specifies a custom data structure matching the file field
  178. // items. We introduce a custom type name for this data structure.
  179. $field_info['file']['property_type'] = 'field_item_file';
  180. $field_info['file']['property_callbacks'][] = 'entity_metadata_field_file_callback';
  181. }
  182. if (module_exists('image')) {
  183. // The callback specifies a custom data structure matching the image field
  184. // items. We introduce a custom type name for this data structure.
  185. $field_info['image']['property_type'] = 'field_item_image';
  186. $field_info['image']['property_callbacks'][] = 'entity_metadata_field_file_callback';
  187. $field_info['image']['property_callbacks'][] = 'entity_metadata_field_image_callback';
  188. }
  189. }
  190. /**
  191. * Implements hook_field_create_instance().
  192. * Clear the cache when a field instance changed.
  193. */
  194. function entity_field_create_instance() {
  195. entity_property_info_cache_clear();
  196. }
  197. /**
  198. * Implements hook_field_delete_instance().
  199. * Clear the cache when a field instance changed.
  200. */
  201. function entity_field_delete_instance() {
  202. entity_property_info_cache_clear();
  203. }
  204. /**
  205. * Implements hook_field_update_instance().
  206. * Clear the cache when a field instance changed.
  207. */
  208. function entity_field_update_instance() {
  209. entity_property_info_cache_clear();
  210. }
  211. /**
  212. * Verifies that the given data can be safely used as the given type regardless
  213. * of the PHP variable type of $data. Example: the string "15" is a valid
  214. * integer, but "15nodes" is not.
  215. *
  216. * @return
  217. * Whether the data is valid for the given type.
  218. */
  219. function entity_property_verify_data_type($data, $type) {
  220. // As this may be called very often statically cache the entity info using
  221. // the fast pattern.
  222. static $drupal_static_fast;
  223. if (!isset($drupal_static_fast)) {
  224. // Make use of the same static as entity info.
  225. entity_get_info();
  226. $drupal_static_fast['entity_info'] = &drupal_static('entity_get_info');
  227. }
  228. $info = &$drupal_static_fast['entity_info'];
  229. // First off check for entities, which may be represented by their ids too.
  230. if (isset($info[$type])) {
  231. if (is_object($data)) {
  232. return TRUE;
  233. }
  234. elseif (isset($info[$type]['entity keys']['name'])) {
  235. // Read the data type of the name key from the metadata if available.
  236. $key = $info[$type]['entity keys']['name'];
  237. $property_info = entity_get_property_info($type);
  238. $property_type = isset($property_info['properties'][$key]['type']) ? $property_info['properties'][$key]['type'] : 'token';
  239. return entity_property_verify_data_type($data, $property_type);
  240. }
  241. return entity_property_verify_data_type($data, empty($info[$type]['fieldable']) ? 'text' : 'integer');
  242. }
  243. switch ($type) {
  244. case 'site':
  245. case 'unknown':
  246. return TRUE;
  247. case 'date':
  248. case 'duration':
  249. case 'integer':
  250. return is_numeric($data) && strpos($data, '.') === FALSE;
  251. case 'decimal':
  252. return is_numeric($data);
  253. case 'text':
  254. return is_scalar($data);
  255. case 'token':
  256. return is_scalar($data) && preg_match('!^[a-z][a-z0-9_]*$!', $data);
  257. case 'boolean':
  258. return is_scalar($data) && (is_bool($data) || $data == 0 || $data == 1);
  259. case 'uri':
  260. return valid_url($data, TRUE);
  261. case 'list':
  262. return (is_array($data) && array_values($data) == $data) || (is_object($data) && $data instanceof EntityMetadataArrayObject);
  263. case 'entity':
  264. return is_object($data) && $data instanceof EntityDrupalWrapper;
  265. default:
  266. case 'struct':
  267. return is_object($data) || is_array($data);
  268. }
  269. }
  270. /**
  271. * Creates the entity object for an array of given property values.
  272. *
  273. * @param $entity_type
  274. * The entity type to create an entity for.
  275. * @param $values
  276. * An array of values as described by the entity's property info. All entity
  277. * properties of the given entity type that are marked as required, must be
  278. * present.
  279. * If the passed values have no matching property, their value will be
  280. * assigned to the entity directly, without the use of the metadata-wrapper
  281. * property.
  282. *
  283. * @return EntityDrupalWrapper
  284. * An EntityDrupalWrapper wrapping the newly created entity or FALSE, if
  285. * there were no information how to create the entity.
  286. */
  287. function entity_property_values_create_entity($entity_type, $values = array()) {
  288. if (entity_type_supports($entity_type, 'create')) {
  289. $info = entity_get_info($entity_type);
  290. // Create the initial entity by passing the values for all 'entity keys'
  291. // to entity_create().
  292. $entity_keys = array_filter($info['entity keys']);
  293. $creation_values = array_intersect_key($values, array_flip($entity_keys));
  294. // In case the bundle key does not match the property that sets it, ensure
  295. // the bundle key is initialized somehow, so entity_extract_ids()
  296. // does not bail out during wrapper creation.
  297. if (!empty($info['entity keys']['bundle'])) {
  298. $creation_values += array($info['entity keys']['bundle'] => FALSE);
  299. }
  300. $entity = entity_create($entity_type, $creation_values);
  301. // Now set the remaining values using the wrapper.
  302. $wrapper = entity_metadata_wrapper($entity_type, $entity);
  303. foreach ($values as $key => $value) {
  304. if (!in_array($key, $info['entity keys'])) {
  305. if (isset($wrapper->$key)) {
  306. $wrapper->$key->set($value);
  307. }
  308. else {
  309. $entity->$key = $value;
  310. }
  311. }
  312. }
  313. // @todo: Once we require Drupal 7.7 or later, verify the entity has
  314. // now a valid bundle and throw the EntityMalformedException if not.
  315. return $wrapper;
  316. }
  317. return FALSE;
  318. }
  319. /**
  320. * Extracts the contained type for a list type string like list<date>.
  321. *
  322. * @return
  323. * The contained type or FALSE, if the given type string is no list.
  324. */
  325. function entity_property_list_extract_type($type) {
  326. if (strpos($type, 'list<') === 0 && $type[strlen($type)-1] == '>') {
  327. return substr($type, 5, -1);
  328. }
  329. return FALSE;
  330. }
  331. /**
  332. * Extracts the innermost type for a type string like list<list<date>>.
  333. *
  334. * @param $type
  335. * The type to examine.
  336. *
  337. * @return
  338. * For list types, the innermost type. The type itself otherwise.
  339. */
  340. function entity_property_extract_innermost_type($type) {
  341. while (strpos($type, 'list<') === 0 && $type[strlen($type)-1] == '>') {
  342. $type = substr($type, 5, -1);
  343. }
  344. return $type;
  345. }
  346. /**
  347. * Gets the property just as it is set in the data.
  348. */
  349. function entity_property_verbatim_get($data, array $options, $name, $type, $info) {
  350. $name = isset($info['schema field']) ? $info['schema field'] : $name;
  351. if ((is_array($data) || (is_object($data) && $data instanceof ArrayAccess)) && isset($data[$name])) {
  352. return $data[$name];
  353. }
  354. elseif (is_object($data) && isset($data->$name)) {
  355. // Incorporate i18n_string translations. We may rely on the entity class
  356. // here as its usage is required by the i18n integration.
  357. if (isset($options['language']) && !empty($info['i18n string'])) {
  358. return $data->getTranslation($name, $options['language']->language);
  359. }
  360. else {
  361. return $data->$name;
  362. }
  363. }
  364. return NULL;
  365. }
  366. /**
  367. * Date values are converted from ISO strings to timestamp if needed.
  368. */
  369. function entity_property_verbatim_date_get($data, array $options, $name, $type, $info) {
  370. $name = isset($info['schema field']) ? $info['schema field'] : $name;
  371. if (is_array($data) || (is_object($data) && $data instanceof ArrayAccess)) {
  372. return is_numeric($data[$name]) ? $data[$name] : strtotime($data[$name], REQUEST_TIME);
  373. }
  374. elseif (is_object($data)) {
  375. return is_numeric($data->$name) ? $data->$name : strtotime($data->$name, REQUEST_TIME);
  376. }
  377. }
  378. /**
  379. * Sets the property to the given value. May be used as 'setter callback'.
  380. */
  381. function entity_property_verbatim_set(&$data, $name, $value, $langcode, $type, $info) {
  382. $name = isset($info['schema field']) ? $info['schema field'] : $name;
  383. if (is_array($data) || (is_object($data) && $data instanceof ArrayAccess)) {
  384. $data[$name] = $value;
  385. }
  386. elseif (is_object($data)) {
  387. $data->$name = $value;
  388. }
  389. }
  390. /**
  391. * Gets the property using the getter method (named just like the property).
  392. */
  393. function entity_property_getter_method($object, array $options, $name) {
  394. // Remove any underscores as classes are expected to use CamelCase.
  395. $method = strtr($name, array('_' => ''));
  396. return $object->$method();
  397. }
  398. /**
  399. * Sets the property to the given value using the setter method. May be used as
  400. * 'setter callback'.
  401. */
  402. function entity_property_setter_method($object, $name, $value) {
  403. // Remove any underscores as classes are expected to use CamelCase.
  404. $method = 'set' . strtr($name, array('_' => ''));
  405. // Invoke the setProperty() method where 'Property' is the property name.
  406. $object->$method($value);
  407. }
  408. /**
  409. * Getter callback for getting an array. Makes sure it's numerically indexed.
  410. */
  411. function entity_property_get_list($data, array $options, $name) {
  412. return isset($data->$name) ? array_values($data->$name) : array();
  413. }
  414. /**
  415. * A validation callback ensuring the passed integer is positive.
  416. */
  417. function entity_property_validate_integer_positive($value) {
  418. return $value > 0;
  419. }
  420. /**
  421. * A validation callback ensuring the passed integer is non-negative.
  422. */
  423. function entity_property_validate_integer_non_negative($value) {
  424. return $value >= 0;
  425. }
  426. /**
  427. * A simple auto-creation callback for array based data structures.
  428. */
  429. function entity_property_create_array($property_name, $context) {
  430. return array();
  431. }
  432. /**
  433. * Flattens the given options in single dimensional array.
  434. * We don't depend on options module, so we cannot use options_array_flatten().
  435. *
  436. * @see options_array_flatten()
  437. */
  438. function entity_property_options_flatten($options) {
  439. $result = array();
  440. foreach ($options as $key => $value) {
  441. if (is_array($value)) {
  442. $result += $value;
  443. }
  444. else {
  445. $result[$key] = $value;
  446. }
  447. }
  448. return $result;
  449. }
  450. /**
  451. * Defines info for the properties of the text_formatted data structure.
  452. */
  453. function entity_property_text_formatted_info() {
  454. return array(
  455. 'value' => array(
  456. 'type' => 'text',
  457. 'label' => t('Text'),
  458. 'sanitized' => TRUE,
  459. 'getter callback' => 'entity_metadata_field_text_get',
  460. 'setter callback' => 'entity_property_verbatim_set',
  461. 'setter permission' => 'administer nodes',
  462. 'raw getter callback' => 'entity_property_verbatim_get',
  463. ),
  464. 'summary' => array(
  465. 'type' => 'text',
  466. 'label' => t('Summary'),
  467. 'sanitized' => TRUE,
  468. 'getter callback' => 'entity_metadata_field_text_get',
  469. 'setter callback' => 'entity_property_verbatim_set',
  470. 'setter permission' => 'administer nodes',
  471. 'raw getter callback' => 'entity_property_verbatim_get',
  472. ),
  473. 'format' => array(
  474. 'type' => 'token',
  475. 'label' => t('Text format'),
  476. 'options list' => 'entity_metadata_field_text_formats',
  477. 'getter callback' => 'entity_property_verbatim_get',
  478. 'setter callback' => 'entity_property_verbatim_set',
  479. 'setter permissions' => 'administer filters',
  480. ),
  481. );
  482. }
  483. /**
  484. * Defines info for the properties of the field_item_textsummary data structure.
  485. */
  486. function entity_property_field_item_textsummary_info() {
  487. return array(
  488. 'value' => array(
  489. 'type' => 'text',
  490. 'label' => t('Text'),
  491. 'setter callback' => 'entity_property_verbatim_set',
  492. ),
  493. 'summary' => array(
  494. 'type' => 'text',
  495. 'label' => t('Summary'),
  496. 'setter callback' => 'entity_property_verbatim_set',
  497. ),
  498. );
  499. }
  500. /**
  501. * Defines info for the properties of the file-field item data structure.
  502. */
  503. function entity_property_field_item_file_info() {
  504. $properties['file'] = array(
  505. 'type' => 'file',
  506. 'label' => t('The file.'),
  507. 'getter callback' => 'entity_metadata_field_file_get',
  508. 'setter callback' => 'entity_metadata_field_file_set',
  509. 'required' => TRUE,
  510. );
  511. $properties['description'] = array(
  512. 'type' => 'text',
  513. 'label' => t('The file description'),
  514. 'setter callback' => 'entity_property_verbatim_set',
  515. );
  516. $properties['display'] = array(
  517. 'type' => 'boolean',
  518. 'label' => t('Whether the file is being displayed.'),
  519. 'setter callback' => 'entity_property_verbatim_set',
  520. );
  521. return $properties;
  522. }
  523. /**
  524. * Defines info for the properties of the image-field item data structure.
  525. */
  526. function entity_property_field_item_image_info() {
  527. $properties['file'] = array(
  528. 'type' => 'file',
  529. 'label' => t('The image file.'),
  530. 'getter callback' => 'entity_metadata_field_file_get',
  531. 'setter callback' => 'entity_metadata_field_file_set',
  532. 'required' => TRUE,
  533. );
  534. $properties['alt'] = array(
  535. 'type' => 'text',
  536. 'label' => t('The "Alt" attribute text'),
  537. 'setter callback' => 'entity_property_verbatim_set',
  538. );
  539. $properties['title'] = array(
  540. 'type' => 'text',
  541. 'label' => t('The "Title" attribute text'),
  542. 'setter callback' => 'entity_property_verbatim_set',
  543. );
  544. return $properties;
  545. }
  546. /**
  547. * Previously, hook_entity_property_info() has been provided by the removed
  548. * entity metadata module. To provide backward compatibility for provided
  549. * helpers that may be specified in hook_entity_property_info(), the following
  550. * (deprecated) functions are provided.
  551. */
  552. /**
  553. * Deprecated.
  554. * Do not make use of this function, instead use the new one.
  555. */
  556. function entity_metadata_verbatim_get($data, array $options, $name) {
  557. return entity_property_verbatim_get($data, $options, $name);
  558. }
  559. /**
  560. * Deprecated.
  561. * Do not make use of this function, instead use the new one.
  562. */
  563. function entity_metadata_verbatim_set($data, $name, $value) {
  564. return entity_property_verbatim_set($data, $name, $value);
  565. }
  566. /**
  567. * Deprecated.
  568. * Do not make use of this function, instead use the new one.
  569. */
  570. function entity_metadata_getter_method($object, array $options, $name) {
  571. return entity_property_getter_method($object, $options, $name);
  572. }
  573. /**
  574. * Deprecated.
  575. * Do not make use of this function, instead use the new one.
  576. */
  577. function entity_metadata_setter_method($object, $name, $value) {
  578. entity_property_setter_method($object, $name, $value);
  579. }
  580. /**
  581. * Deprecated.
  582. * Do not make use of this function, instead use the new one.
  583. */
  584. function entity_metadata_get_list($data, array $options, $name) {
  585. return entity_property_get_list($data, $options, $name);
  586. }
  587. /**
  588. * Deprecated.
  589. * Do not make use of this function, instead use the new one.
  590. */
  591. function entity_metadata_validate_integer_positive($value) {
  592. return entity_property_validate_integer_positive($value);
  593. }
  594. /**
  595. * Deprecated.
  596. * Do not make use of this function, instead use the new one.
  597. */
  598. function entity_metadata_validate_integer_non_negative($value) {
  599. return entity_property_validate_integer_non_negative($value);
  600. }
  601. /**
  602. * Deprecated.
  603. * Do not make use of this function, instead use the new one.
  604. */
  605. function entity_metadata_text_formatted_properties() {
  606. return entity_property_text_formatted_info();
  607. }