search_api.api.php 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Search API module.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Defines one or more search service classes a module offers.
  12. *
  13. * Note: The ids should be valid PHP identifiers.
  14. *
  15. * @return array
  16. * An associative array of search service classes, keyed by a unique
  17. * identifier and containing associative arrays with the following keys:
  18. * - name: The service class' translated name.
  19. * - description: A translated string to be shown to administrators when
  20. * selecting a service class. Should contain all peculiarities of the
  21. * service class, like field type support, supported features (like facets),
  22. * the "direct" parse mode and other specific things to keep in mind. The
  23. * text can contain HTML.
  24. * - class: The service class, which has to implement the
  25. * SearchApiServiceInterface interface.
  26. *
  27. * @see hook_search_api_service_info_alter()
  28. */
  29. function hook_search_api_service_info() {
  30. $services['example_some'] = array(
  31. 'name' => t('Some Service'),
  32. 'description' => t('Service for some search engine.'),
  33. 'class' => 'SomeServiceClass',
  34. // Unknown keys can later be read by the object for additional information.
  35. 'init args' => array('foo' => 'Foo', 'bar' => 42),
  36. );
  37. $services['example_other'] = array(
  38. 'name' => t('Other Service'),
  39. 'description' => t('Service for another search engine.'),
  40. 'class' => 'OtherServiceClass',
  41. );
  42. return $services;
  43. }
  44. /**
  45. * Alter the Search API service info.
  46. *
  47. * Modules may implement this hook to alter the information that defines Search
  48. * API services. All properties that are available in
  49. * hook_search_api_service_info() can be altered here, with the addition of the
  50. * "module" key specifying the module that originally defined the service class.
  51. *
  52. * @param array $service_info
  53. * The Search API service info array, keyed by service id.
  54. *
  55. * @see hook_search_api_service_info()
  56. */
  57. function hook_search_api_service_info_alter(array &$service_info) {
  58. foreach ($service_info as $id => $info) {
  59. $service_info[$id]['class'] = 'MyProxyServiceClass';
  60. $service_info[$id]['example_original_class'] = $info['class'];
  61. }
  62. }
  63. /**
  64. * Define new types of items that can be searched.
  65. *
  66. * This hook allows modules to define their own item types, for which indexes
  67. * can then be created. (Note that the Search API natively provides support for
  68. * all entity types that specify property information, so they should not be
  69. * added here. You should therefore also not use an existing entity type as the
  70. * identifier of a new item type.)
  71. *
  72. * The main part of defining a new item type is implementing its data source
  73. * controller class, which is responsible for loading items, providing metadata
  74. * and tracking existing items. The module defining a certain item type is also
  75. * responsible for observing creations, updates and deletions of items of that
  76. * type and notifying the Search API of them by calling
  77. * search_api_track_item_insert(), search_api_track_item_change() and
  78. * search_api_track_item_delete(), as appropriate.
  79. * The only other restriction for item types is that they have to have a single
  80. * item ID field, with a scalar value. This is, e.g., used to track indexed
  81. * items.
  82. *
  83. * Note, however, that you can also define item types where some of these
  84. * conditions are not met, as long as you are aware that some functionality of
  85. * the Search API and related modules might then not be available for that type.
  86. *
  87. * @return array
  88. * An associative array keyed by item type identifier, and containing type
  89. * information arrays with at least the following keys:
  90. * - name: A human-readable name for the type.
  91. * - datasource controller: A class implementing the
  92. * SearchApiDataSourceControllerInterface interface which will be used as
  93. * the data source controller for this type.
  94. * - entity_type: (optional) If the type represents entities, the entity type.
  95. * This is used by SearchApiAbstractDataSourceController for determining the
  96. * entity type of items. Other datasource controllers might ignore this.
  97. * Other, datasource-specific settings might also be placed here. These should
  98. * be specified with the data source controller in question.
  99. *
  100. * @see hook_search_api_item_type_info_alter()
  101. */
  102. function hook_search_api_item_type_info() {
  103. // Copied from search_api_search_api_item_type_info().
  104. $types = array();
  105. foreach (entity_get_property_info() as $type => $property_info) {
  106. if ($info = entity_get_info($type)) {
  107. $types[$type] = array(
  108. 'name' => $info['label'],
  109. 'datasource controller' => 'SearchApiEntityDataSourceController',
  110. 'entity_type' => $type,
  111. );
  112. }
  113. }
  114. return $types;
  115. }
  116. /**
  117. * Alter the item type info.
  118. *
  119. * Modules may implement this hook to alter the information that defines an
  120. * item type. All properties that are available in
  121. * hook_search_api_item_type_info() can be altered here, with the addition of
  122. * the "module" key specifying the module that originally defined the type.
  123. *
  124. * @param array $infos
  125. * The item type info array, keyed by type identifier.
  126. *
  127. * @see hook_search_api_item_type_info()
  128. */
  129. function hook_search_api_item_type_info_alter(array &$infos) {
  130. // Adds a boolean value is_entity to all type options telling whether the item
  131. // type represents an entity type.
  132. foreach ($infos as $type => $info) {
  133. $info['is_entity'] = (bool) entity_get_info($type);
  134. }
  135. }
  136. /**
  137. * Define new data types for indexed properties.
  138. *
  139. * New data types will appear as new option for the „Type“ field on indexes'
  140. * „Fields“ tabs. Whether choosing a custom data type will have any effect
  141. * depends on the server on which the data is indexed.
  142. *
  143. * @return array
  144. * An array containing custom data type definitions, keyed by their type
  145. * identifier and containing the following keys:
  146. * - name: The human-readable name of the type.
  147. * - fallback: (optional) One of the default data types (the keys from
  148. * search_api_default_field_types()) which should be used as a fallback if
  149. * the server doesn't support this data type. Defaults to "string".
  150. * - conversion callback: (optional) If specified, a callback function for
  151. * converting raw values to the given type, if possible. For the contract
  152. * of such a callback, see example_data_type_conversion().
  153. *
  154. * @see hook_search_api_data_type_info_alter()
  155. * @see search_api_get_data_type_info()
  156. * @see example_data_type_conversion()
  157. */
  158. function hook_search_api_data_type_info() {
  159. return array(
  160. 'example_type' => array(
  161. 'name' => t('Example type'),
  162. // Could be omitted, as "string" is the default.
  163. 'fallback' => 'string',
  164. 'conversion callback' => 'example_data_type_conversion',
  165. ),
  166. );
  167. }
  168. /**
  169. * Alter the data type info.
  170. *
  171. * Modules may implement this hook to alter the information that defines a data
  172. * type, or to add/remove some entirely. All properties that are available in
  173. * hook_search_api_data_type_info() can be altered here.
  174. *
  175. * @param array $infos
  176. * The data type info array, keyed by type identifier.
  177. *
  178. * @see hook_search_api_data_type_info()
  179. */
  180. function hook_search_api_data_type_info_alter(array &$infos) {
  181. $infos['example_type']['name'] .= ' 2';
  182. }
  183. /**
  184. * Define available data alterations.
  185. *
  186. * Registers one or more callbacks that can be called at index time to add
  187. * additional data to the indexed items (e.g. comments or attachments to nodes),
  188. * alter the data in other forms or remove items from the array.
  189. *
  190. * Data-alter callbacks (which are called "Data alterations" in the UI) are
  191. * classes implementing the SearchApiAlterCallbackInterface interface.
  192. *
  193. * @see SearchApiAlterCallbackInterface
  194. *
  195. * @return array
  196. * An associative array keyed by the callback IDs and containing arrays with
  197. * the following keys:
  198. * - name: The name to display for this callback.
  199. * - description: A short description of what the callback does.
  200. * - class: The callback class.
  201. * - weight: (optional) Defines the order in which callbacks are displayed
  202. * (and, therefore, invoked) by default. Defaults to 0.
  203. */
  204. function hook_search_api_alter_callback_info() {
  205. $callbacks['example_random_alter'] = array(
  206. 'name' => t('Random alteration'),
  207. 'description' => t('Alters all passed item data completely randomly.'),
  208. 'class' => 'ExampleRandomAlter',
  209. 'weight' => 100,
  210. );
  211. $callbacks['example_add_comments'] = array(
  212. 'name' => t('Add comments'),
  213. 'description' => t('For nodes and similar entities, adds comments.'),
  214. 'class' => 'ExampleAddComments',
  215. );
  216. return $callbacks;
  217. }
  218. /**
  219. * Alter the available data alterations.
  220. *
  221. * @param array $callbacks
  222. * The callback information to be altered, keyed by callback IDs.
  223. *
  224. * @see hook_search_api_alter_callback_info()
  225. */
  226. function hook_search_api_alter_callback_info_alter(array &$callbacks) {
  227. if (!empty($callbacks['example_random_alter'])) {
  228. $callbacks['example_random_alter']['name'] = t('Even more random alteration');
  229. $callbacks['example_random_alter']['class'] = 'ExampleUltraRandomAlter';
  230. }
  231. }
  232. /**
  233. * Registers one or more processors. These are classes implementing the
  234. * SearchApiProcessorInterface interface which can be used at index and search
  235. * time to pre-process item data or the search query, and at search time to
  236. * post-process the returned search results.
  237. *
  238. * @see SearchApiProcessorInterface
  239. *
  240. * @return array
  241. * An associative array keyed by the processor id and containing arrays
  242. * with the following keys:
  243. * - name: The name to display for this processor.
  244. * - description: A short description of what the processor does at each
  245. * phase.
  246. * - class: The processor class, which has to implement the
  247. * SearchApiProcessorInterface interface.
  248. * - weight: (optional) Defines the order in which processors are displayed
  249. * (and, therefore, invoked) by default. Defaults to 0.
  250. */
  251. function hook_search_api_processor_info() {
  252. $callbacks['example_processor'] = array(
  253. 'name' => t('Example processor'),
  254. 'description' => t('Pre- and post-processes data in really cool ways.'),
  255. 'class' => 'ExampleSearchApiProcessor',
  256. 'weight' => -1,
  257. );
  258. $callbacks['example_processor_minimal'] = array(
  259. 'name' => t('Example processor 2'),
  260. 'description' => t('Processor with minimal description.'),
  261. 'class' => 'ExampleSearchApiProcessor2',
  262. );
  263. return $callbacks;
  264. }
  265. /**
  266. * Alter the available processors.
  267. *
  268. * @param array $processors
  269. * The processor information to be altered, keyed by processor IDs.
  270. *
  271. * @see hook_search_api_processor_info()
  272. */
  273. function hook_search_api_processor_info_alter(array &$processors) {
  274. if (!empty($processors['example_processor'])) {
  275. $processors['example_processor']['weight'] = -20;
  276. }
  277. }
  278. /**
  279. * Allows you to log or alter the items that are indexed.
  280. *
  281. * Please be aware that generally preventing the indexing of certain items is
  282. * deprecated. This is better done with data alterations, which can easily be
  283. * configured and only added to indexes where this behaviour is wanted.
  284. * If your module will use this hook to reject certain items from indexing,
  285. * please document this clearly to avoid confusion.
  286. *
  287. * @param array $items
  288. * The entities that will be indexed (before calling any data alterations).
  289. * @param SearchApiIndex $index
  290. * The search index on which items will be indexed.
  291. */
  292. function hook_search_api_index_items_alter(array &$items, SearchApiIndex $index) {
  293. foreach ($items as $id => $item) {
  294. if ($id % 5 == 0) {
  295. unset($items[$id]);
  296. }
  297. }
  298. example_store_indexed_entity_ids($index->item_type, array_keys($items));
  299. }
  300. /**
  301. * Allows modules to react after items were indexed.
  302. *
  303. * @param SearchApiIndex $index
  304. * The used index.
  305. * @param array $item_ids
  306. * An array containing the indexed items' IDs.
  307. */
  308. function hook_search_api_items_indexed(SearchApiIndex $index, array $item_ids) {
  309. if ($index->getEntityType() == 'node') {
  310. // Flush page cache of the search page.
  311. cache_clear_all(url('search'), 'cache_page');
  312. }
  313. }
  314. /**
  315. * Lets modules alter a search query before executing it.
  316. *
  317. * @param SearchApiQueryInterface $query
  318. * The search query being executed.
  319. */
  320. function hook_search_api_query_alter(SearchApiQueryInterface $query) {
  321. // Exclude entities with ID 0. (Assume the ID field is always indexed.)
  322. if ($query->getIndex()->getEntityType()) {
  323. $info = entity_get_info($query->getIndex()->getEntityType());
  324. $query->condition($info['entity keys']['id'], 0, '!=');
  325. }
  326. }
  327. /**
  328. * Act on search servers when they are loaded.
  329. *
  330. * @param array $servers
  331. * An array of loaded SearchApiServer objects.
  332. */
  333. function hook_search_api_server_load(array $servers) {
  334. foreach ($servers as $server) {
  335. db_insert('example_search_server_access')
  336. ->fields(array(
  337. 'server' => $server->machine_name,
  338. 'access_time' => REQUEST_TIME,
  339. ))
  340. ->execute();
  341. }
  342. }
  343. /**
  344. * A new search server was created.
  345. *
  346. * @param SearchApiServer $server
  347. * The new server.
  348. */
  349. function hook_search_api_server_insert(SearchApiServer $server) {
  350. db_insert('example_search_server')
  351. ->fields(array(
  352. 'server' => $server->machine_name,
  353. 'insert_time' => REQUEST_TIME,
  354. ))
  355. ->execute();
  356. }
  357. /**
  358. * A search server was edited, enabled or disabled.
  359. *
  360. * @param SearchApiServer $server
  361. * The edited server.
  362. */
  363. function hook_search_api_server_update(SearchApiServer $server) {
  364. if ($server->name != $server->original->name) {
  365. db_insert('example_search_server_name_update')
  366. ->fields(array(
  367. 'server' => $server->machine_name,
  368. 'update_time' => REQUEST_TIME,
  369. ))
  370. ->execute();
  371. }
  372. }
  373. /**
  374. * A search server was deleted.
  375. *
  376. * @param SearchApiServer $server
  377. * The deleted server.
  378. */
  379. function hook_search_api_server_delete(SearchApiServer $server) {
  380. db_insert('example_search_server_update')
  381. ->fields(array(
  382. 'server' => $server->machine_name,
  383. 'update_time' => REQUEST_TIME,
  384. ))
  385. ->execute();
  386. db_delete('example_search_server')
  387. ->condition('server', $server->machine_name)
  388. ->execute();
  389. }
  390. /**
  391. * Define default search servers.
  392. *
  393. * @return array
  394. * An array of default search servers, keyed by machine names.
  395. *
  396. * @see hook_default_search_api_server_alter()
  397. */
  398. function hook_default_search_api_server() {
  399. $defaults['main'] = entity_create('search_api_server', array(
  400. 'name' => 'Main server',
  401. 'machine_name' => 'main',// Must be same as the used array key.
  402. // Other properties ...
  403. ));
  404. return $defaults;
  405. }
  406. /**
  407. * Alter default search servers.
  408. *
  409. * @param array $defaults
  410. * An array of default search servers, keyed by machine names.
  411. *
  412. * @see hook_default_search_api_server()
  413. */
  414. function hook_default_search_api_server_alter(array &$defaults) {
  415. $defaults['main']->name = 'Customized main server';
  416. }
  417. /**
  418. * Act on search indexes when they are loaded.
  419. *
  420. * @param array $indexes
  421. * An array of loaded SearchApiIndex objects.
  422. */
  423. function hook_search_api_index_load(array $indexes) {
  424. foreach ($indexes as $index) {
  425. db_insert('example_search_index_access')
  426. ->fields(array(
  427. 'index' => $index->machine_name,
  428. 'access_time' => REQUEST_TIME,
  429. ))
  430. ->execute();
  431. }
  432. }
  433. /**
  434. * A new search index was created.
  435. *
  436. * @param SearchApiIndex $index
  437. * The new index.
  438. */
  439. function hook_search_api_index_insert(SearchApiIndex $index) {
  440. db_insert('example_search_index')
  441. ->fields(array(
  442. 'index' => $index->machine_name,
  443. 'insert_time' => REQUEST_TIME,
  444. ))
  445. ->execute();
  446. }
  447. /**
  448. * A search index was edited in any way.
  449. *
  450. * @param SearchApiIndex $index
  451. * The edited index.
  452. */
  453. function hook_search_api_index_update(SearchApiIndex $index) {
  454. if ($index->name != $index->original->name) {
  455. db_insert('example_search_index_name_update')
  456. ->fields(array(
  457. 'index' => $index->machine_name,
  458. 'update_time' => REQUEST_TIME,
  459. ))
  460. ->execute();
  461. }
  462. }
  463. /**
  464. * A search index was scheduled for reindexing
  465. *
  466. * @param SearchApiIndex $index
  467. * The edited index.
  468. * @param $clear
  469. * Boolean indicating whether the index was also cleared.
  470. */
  471. function hook_search_api_index_reindex(SearchApiIndex $index, $clear = FALSE) {
  472. db_insert('example_search_index_reindexed')
  473. ->fields(array(
  474. 'index' => $index->id,
  475. 'update_time' => REQUEST_TIME,
  476. ))
  477. ->execute();
  478. }
  479. /**
  480. * A search index was deleted.
  481. *
  482. * @param SearchApiIndex $index
  483. * The deleted index.
  484. */
  485. function hook_search_api_index_delete(SearchApiIndex $index) {
  486. db_insert('example_search_index_update')
  487. ->fields(array(
  488. 'index' => $index->machine_name,
  489. 'update_time' => REQUEST_TIME,
  490. ))
  491. ->execute();
  492. db_delete('example_search_index')
  493. ->condition('index', $index->machine_name)
  494. ->execute();
  495. }
  496. /**
  497. * Define default search indexes.
  498. *
  499. * @return array
  500. * An array of default search indexes, keyed by machine names.
  501. *
  502. * @see hook_default_search_api_index_alter()
  503. */
  504. function hook_default_search_api_index() {
  505. $defaults['main'] = entity_create('search_api_index', array(
  506. 'name' => 'Main index',
  507. 'machine_name' => 'main',// Must be same as the used array key.
  508. // Other properties ...
  509. ));
  510. return $defaults;
  511. }
  512. /**
  513. * Alter default search indexes.
  514. *
  515. * @param array $defaults
  516. * An array of default search indexes, keyed by machine names.
  517. *
  518. * @see hook_default_search_api_index()
  519. */
  520. function hook_default_search_api_index_alter(array &$defaults) {
  521. $defaults['main']->name = 'Customized main index';
  522. }
  523. /**
  524. * @} End of "addtogroup hooks".
  525. */
  526. /**
  527. * Convert a raw value from an entity to a custom data type.
  528. *
  529. * This function will be called for fields of the specific data type to convert
  530. * all individual values of the field to the correct format.
  531. *
  532. * @param $value
  533. * The raw, single value, as extracted from an entity wrapper.
  534. * @param $original_type
  535. * The original Entity API type of the value.
  536. * @param $type
  537. * The custom data type to which the value should be converted. Can be ignored
  538. * if the callback is only used for a single data type.
  539. *
  540. * @return
  541. * The converted value, if a conversion could be executed. NULL otherwise.
  542. *
  543. * @see hook_search_api_data_type_info()
  544. */
  545. function example_data_type_conversion($value, $original_type, $type) {
  546. if ($type === 'example_type') {
  547. // The example_type type apparently requires a rather complex data format.
  548. return array(
  549. 'value' => $value,
  550. 'original' => $original_type,
  551. );
  552. }
  553. // Someone used this callback for another, unknown type. Return NULL.
  554. // (Normally, you can just assume that the/a correct type is given.)
  555. return NULL;
  556. }