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