ItemInterface.php 8.76 KB
Newer Older
1 2 3 4
<?php

namespace Drupal\search_api\Item;

5
use Drupal\Core\Session\AccountInterface;
6 7
use Drupal\Core\TypedData\ComplexDataInterface;

8
/**
9
 * Represents a search item being indexed or returned as a search result.
10
 *
11
 * Traversing the object retrieves all its fields.
12
 */
13
interface ItemInterface extends \Traversable {
14 15

  /**
16
   * Returns the item's ID.
17 18
   *
   * @return string
19
   *   The ID of this item.
20 21 22 23
   */
  public function getId();

  /**
24
   * Returns the original complex data object this Search API item is based on.
25
   *
26 27 28 29 30
   * @param bool $load
   *   (optional) If TRUE, the object will be loaded if necessary. Otherwise,
   *   NULL will be returned if the object isn't available.
   *
   * @return \Drupal\Core\TypedData\ComplexDataInterface|null
31
   *   The wrapped object if it was previously set or could be loaded. NULL
32 33
   *   if it wasn't set previously and $load is FALSE.
   *
34
   * @throws \Drupal\search_api\SearchApiException
35
   *   Thrown if $load is TRUE but the object could not be loaded.
36
   */
37
  public function getOriginalObject($load = TRUE);
38 39

  /**
40 41 42 43 44
   * Sets the original complex data object this item should be based on.
   *
   * @param \Drupal\Core\TypedData\ComplexDataInterface $original_object
   *   The object that should be wrapped.
   *
45
   * @return $this
46 47 48
   */
  public function setOriginalObject(ComplexDataInterface $original_object);

49 50 51 52 53 54 55 56
  /**
   * Returns the ID of this item's datasource.
   *
   * @return string
   *   The plugin ID of this item's datasource.
   */
  public function getDatasourceId();

57 58
  /**
   * Returns the datasource of this item.
59
   *
60
   * @return \Drupal\search_api\Datasource\DatasourceInterface
61 62
   *   The datasource to which this item belongs.
   *
63
   * @throws \Drupal\search_api\SearchApiException
64
   *   Thrown if the item's datasource wasn't set before and couldn't be loaded.
65 66 67 68
   */
  public function getDatasource();

  /**
69
   * Returns the index of this item.
70
   *
71
   * @return \Drupal\search_api\IndexInterface
72
   *   The index to which this item belongs.
73 74 75
   */
  public function getIndex();

76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
  /**
   * Retrieves the item language.
   *
   * @return string
   *   The item language.
   */
  public function getLanguage();

  /**
   * Sets the item language.
   *
   * @param string $language
   *   The new item language.
   *
   * @return $this
   */
  public function setLanguage($language);

94
  /**
95
   * Retrieves a single field of this item.
96
   *
97 98 99
   * @param string $field_id
   *   The identifier of the field to retrieve.
   * @param bool $extract
100 101 102
   *   (optional) If FALSE, only returns the field if it was previously set or
   *   extracted. Defaults to extracting all fields from the original object if
   *   necessary.
103 104 105
   *
   * @return \Drupal\search_api\Item\FieldInterface|null
   *   The field object with this identifier, or NULL if the field is unknown.
106
   */
107
  public function getField($field_id, $extract = TRUE);
108

109 110 111 112
  /**
   * Returns the item's fields.
   *
   * @param bool $extract
113 114 115
   *   (optional) If FALSE, only returns the fields that were previously set or
   *   extracted. Defaults to extracting the fields from the original object if
   *   necessary.
116 117 118 119
   *
   * @return \Drupal\search_api\Item\FieldInterface[]
   *   An array with the fields of this item, keyed by field identifier.
   */
120
  public function getFields($extract = TRUE);
121

das-peter's avatar
das-peter committed
122
  /**
123
   * Sets one of the item's fields.
das-peter's avatar
das-peter committed
124
   *
125 126 127 128 129 130
   * @param string $field_id
   *   The field's identifier.
   * @param \Drupal\search_api\Item\FieldInterface|null $field
   *   (optional) The information and contents of this field. Or NULL to remove
   *   the field from the item.
   *
131
   * @return $this
132 133
   *
   * @throws \InvalidArgumentException
134 135
   *   Thrown if a $field is passed but has another field identifier than given
   *   as $field_id.
136 137 138 139 140 141 142 143 144
   */
  public function setField($field_id, FieldInterface $field = NULL);

  /**
   * Sets the item's fields.
   *
   * @param \Drupal\search_api\Item\FieldInterface[] $fields
   *   An array with the fields of this item, keyed by field identifier.
   *
145
   * @return $this
146 147 148
   */
  public function setFields(array $fields);

149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
  /**
   * Determines whether fields have been extracted already for this item.
   *
   * @return bool
   *   TRUE if all field values have been extracted already for this item. FALSE
   *   otherwise.
   */
  public function isFieldsExtracted();

  /**
   * Sets the field extraction state of this item.
   *
   * Can be used to tell an item that all its fields have been set already and
   * it shouldn't attempt to extract more when getFields() is called. Or that
   * some of its extracted fields have been removed and that it should extract
   * them again when necessary.
   *
166
   * @param bool $fields_extracted
167 168 169
   *   TRUE if all field values have been extracted already for this item. FALSE
   *   otherwise.
   *
170
   * @return $this
171
   */
172
  public function setFieldsExtracted($fields_extracted);
173

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
  /**
   * Returns the score of the item.
   *
   * Defaults to 1 if not previously set.
   *
   * @return float
   *   The score of the item.
   */
  public function getScore();

  /**
   * Sets the score of the item.
   *
   * @param float $score
   *   The score of the item.
   *
190
   * @return $this
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
   */
  public function setScore($score);

  /**
   * Gets the boost value of this item.
   *
   * Defaults to 1 if not previously set.
   *
   * @return float
   *   The boost value.
   */
  public function getBoost();

  /**
   * Sets the boost value of this item.
   *
   * @param float $boost
   *   The boost value to set.
   *
210
   * @return $this
211 212 213 214 215 216 217
   */
  public function setBoost($boost);

  /**
   * Returns an HTML text with highlighted text-parts that match the query.
   *
   * @return string|null
das-peter's avatar
das-peter committed
218
   *   If set, an HTML text containing highlighted portions of the fulltext that
219
   *   match the query. NULL otherwise.
das-peter's avatar
das-peter committed
220 221 222 223
   */
  public function getExcerpt();

  /**
224
   * Sets an HTML text with highlighted text-parts that match the query.
das-peter's avatar
das-peter committed
225 226 227
   *
   * @param string $excerpt
   *   The HTML text with highlighted text-parts that match the query.
228
   *
229
   * @return $this
das-peter's avatar
das-peter committed
230 231 232
   */
  public function setExcerpt($excerpt);

233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
  /**
   * Determines whether extra data with a specific key is set on this item.
   *
   * @param string $key
   *   The extra data's key.
   *
   * @return bool
   *   TRUE if the data is set, FALSE otherwise.
   */
  public function hasExtraData($key);

  /**
   * Retrieves extra data for this item.
   *
   * @param string $key
248 249
   *   The key of the extra data. The following keys are used in the Search API
   *   project itself:
250 251 252 253 254 255
   *   - highlighted_fields: Contains highlighted fields data for the result.
   *     The structure is an array, keyed by field IDs, mapped to arrays of
   *     values for that field. If possible, the array for a field with
   *     highlighting data should also include any non-highlighted field values,
   *     to avoid having to determine which values are included and which
   *     aren't.
256 257
   *   - highlighted_keys: The exact tokens that matched keys in this item's
   *     text values. The value is an array of strings.
258 259
   *   However, contrib modules can define arbitrary other keys. (Usually they
   *   should be prefixed with the module name, though.)
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
   * @param mixed $default
   *   (optional) The value to return if the data is not set.
   *
   * @return mixed
   *   The data set for that key, or $default if the data is not present.
   */
  public function getExtraData($key, $default = NULL);

  /**
   * Retrieves all extra data set for this item.
   *
   * @return array
   *   An array mapping extra data keys to their data.
   */
  public function getAllExtraData();

  /**
   * Sets some extra data for this item.
   *
   * @param string $key
   *   The key for the extra data.
   * @param mixed $data
   *   (optional) The data to set. If NULL, remove the extra data with the given
   *   key instead.
   *
285
   * @return $this
286 287 288
   */
  public function setExtraData($key, $data = NULL);

289 290 291 292 293 294 295 296 297
  /**
   * Checks whether a user has permission to view this item.
   *
   * @param \Drupal\Core\Session\AccountInterface|null $account
   *   (optional) The user session for which to check access, or NULL to check
   *   access for the current user.
   *
   * @return bool
   *   TRUE if access is granted, FALSE otherwise.
298 299 300 301 302
   *
   * @deprecated in search_api:8.x-1.14 and is removed from search_api:9.x-1.0.
   *   Use getAccessResult() instead.
   *
   * @see https://www.drupal.org/node/3051902
303 304 305
   */
  public function checkAccess(AccountInterface $account = NULL);

306 307 308 309 310 311 312 313 314 315 316 317
  /**
   * Checks whether a user has permission to view this item.
   *
   * @param \Drupal\Core\Session\AccountInterface|null $account
   *   (optional) The user for which to check access, or NULL to check access
   *   for the current user.
   *
   * @return \Drupal\Core\Access\AccessResultInterface
   *   The access result.
   */
  public function getAccessResult(AccountInterface $account = NULL);

318
}