FlexCollectionInterface.php 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @package Grav\Framework\Flex
  5. *
  6. * @copyright Copyright (c) 2015 - 2021 Trilby Media, LLC. All rights reserved.
  7. * @license MIT License; see LICENSE file for details.
  8. */
  9. namespace Grav\Framework\Flex\Interfaces;
  10. use Grav\Framework\Flex\Flex;
  11. use Grav\Framework\Object\Interfaces\NestedObjectInterface;
  12. use Grav\Framework\Object\Interfaces\ObjectCollectionInterface;
  13. use Grav\Framework\Flex\FlexDirectory;
  14. use InvalidArgumentException;
  15. /**
  16. * Defines a collection of Flex Objects.
  17. *
  18. * @used-by \Grav\Framework\Flex\FlexCollection
  19. * @since 1.6
  20. * @template T
  21. * @extends ObjectCollectionInterface<string,T>
  22. */
  23. interface FlexCollectionInterface extends FlexCommonInterface, ObjectCollectionInterface, NestedObjectInterface
  24. {
  25. /**
  26. * Creates a Flex Collection from an array.
  27. *
  28. * @used-by FlexDirectory::createCollection() Official method to create a Flex Collection.
  29. *
  30. * @param FlexObjectInterface[] $entries Associated array of Flex Objects to be included in the collection.
  31. * @param FlexDirectory $directory Flex Directory where all the objects belong into.
  32. * @param string|null $keyField Key field used to index the collection.
  33. * @return static Returns a new Flex Collection.
  34. */
  35. public static function createFromArray(array $entries, FlexDirectory $directory, string $keyField = null);
  36. /**
  37. * Creates a new Flex Collection.
  38. *
  39. * @used-by FlexDirectory::createCollection() Official method to create Flex Collection.
  40. *
  41. * @param FlexObjectInterface[] $entries Associated array of Flex Objects to be included in the collection.
  42. * @param FlexDirectory|null $directory Flex Directory where all the objects belong into.
  43. * @throws InvalidArgumentException
  44. */
  45. public function __construct(array $entries = [], FlexDirectory $directory = null);
  46. /**
  47. * Search a string from the collection.
  48. *
  49. * @param string $search Search string.
  50. * @param string|string[]|null $properties Properties to search for, defaults to configured properties.
  51. * @param array|null $options Search options, defaults to configured options.
  52. * @return FlexCollectionInterface Returns a Flex Collection with only matching objects.
  53. * @phpstan-return static<T>
  54. * @api
  55. */
  56. public function search(string $search, $properties = null, array $options = null);
  57. /**
  58. * Sort the collection.
  59. *
  60. * @param array $orderings Pair of [property => 'ASC'|'DESC', ...].
  61. *
  62. * @return FlexCollectionInterface Returns a sorted version from the collection.
  63. * @phpstan-return static<T>
  64. */
  65. public function sort(array $orderings);
  66. /**
  67. * Filter collection by filter array with keys and values.
  68. *
  69. * @param array $filters
  70. * @return FlexCollectionInterface
  71. * @phpstan-return static<T>
  72. */
  73. public function filterBy(array $filters);
  74. /**
  75. * Get timestamps from all the objects in the collection.
  76. *
  77. * This method can be used for example in caching.
  78. *
  79. * @return int[] Returns [key => timestamp, ...] pairs.
  80. */
  81. public function getTimestamps(): array;
  82. /**
  83. * Get storage keys from all the objects in the collection.
  84. *
  85. * @see FlexDirectory::getObject() If you want to get Flex Object from the Flex Directory.
  86. *
  87. * @return string[] Returns [key => storage_key, ...] pairs.
  88. */
  89. public function getStorageKeys(): array;
  90. /**
  91. * Get Flex keys from all the objects in the collection.
  92. *
  93. * @see Flex::getObjects() If you want to get list of Flex Objects from any Flex Directory.
  94. *
  95. * @return string[] Returns[key => flex_key, ...] pairs.
  96. */
  97. public function getFlexKeys(): array;
  98. /**
  99. * Return new collection with a different key.
  100. *
  101. * @param string|null $keyField Switch key field of the collection.
  102. * @return FlexCollectionInterface Returns a new Flex Collection with new key field.
  103. * @phpstan-return static<T>
  104. * @api
  105. */
  106. public function withKeyField(string $keyField = null);
  107. /**
  108. * Get Flex Index from the Flex Collection.
  109. *
  110. * @return FlexIndexInterface Returns a Flex Index from the current collection.
  111. * @phpstan-return FlexIndexInterface<T>
  112. */
  113. public function getIndex();
  114. /**
  115. * Load all the objects into memory,
  116. *
  117. * @return FlexCollectionInterface
  118. * @phpstan-return static<T>
  119. */
  120. public function getCollection();
  121. /**
  122. * Get metadata associated to the object
  123. *
  124. * @param string $key Key.
  125. * @return array
  126. */
  127. public function getMetaData(string $key): array;
  128. }