Collection.php 1.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566
  1. <?php
  2. namespace Elgg\Structs;
  3. use Countable;
  4. use Iterator;
  5. /**
  6. * A read-only interface to a (possibly mutable) group of items.
  7. *
  8. * Read-only provides some nice guarantees that can be harnessed for things
  9. * like caching, lazy evaluation, respecting HTTP semantics of GET/HEAD, etc.
  10. *
  11. * We do not extend ArrayAccess, because:
  12. * * Collections aren't writable by default
  13. * * Collections don't have a defined order by default
  14. * * Collections aren't all Maps by default ;)
  15. *
  16. * Extensions may provide one or more of these features.
  17. *
  18. * TODO(ewinslow): If PHP had generics support, we'd add that here.
  19. *
  20. * DO NOT EXTEND OR IMPLEMENT this interface outside of this package.
  21. * Doing so would cause additions to the API to be breaking changes, which is
  22. * not what we want. You have a couple of options for how to proceed:
  23. * * File a feature request
  24. * * Submit a PR
  25. * * Use composition -- http://en.wikipedia.org/wiki/Composition_over_inheritance
  26. *
  27. * @package Elgg.Core
  28. * @subpackage Structs
  29. * @since 1.10
  30. *
  31. * @access private
  32. */
  33. interface Collection extends Countable, Iterator {
  34. /**
  35. * Returns a new collection only containing the elements which pass the filter.
  36. *
  37. * @param callable $filter Receives an item. Return true to keep the item.
  38. *
  39. * @return Collection
  40. */
  41. public function filter(callable $filter);
  42. /**
  43. * Returns true iff the item is in this collection at least once.
  44. *
  45. * @param mixed $item The object or value to check for
  46. *
  47. * @return boolean
  48. */
  49. public function contains($item);
  50. /**
  51. * Take items of the collection and return a new collection
  52. * with all the items having the $mapper applied to them.
  53. *
  54. * The callable is not guaranteed to execute immediately for each item.
  55. *
  56. * @param callable $mapper Returns the mapped value
  57. *
  58. * @return Collection
  59. */
  60. public function map(callable $mapper);
  61. }