ItemInterface.php 1.7 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465
  1. <?php
  2. /*
  3. * This file is part of the Symfony package.
  4. *
  5. * (c) Fabien Potencier <fabien@symfony.com>
  6. *
  7. * For the full copyright and license information, please view the LICENSE
  8. * file that was distributed with this source code.
  9. */
  10. namespace Symfony\Contracts\Cache;
  11. use Psr\Cache\CacheException;
  12. use Psr\Cache\CacheItemInterface;
  13. use Psr\Cache\InvalidArgumentException;
  14. /**
  15. * Augments PSR-6's CacheItemInterface with support for tags and metadata.
  16. *
  17. * @author Nicolas Grekas <p@tchwork.com>
  18. */
  19. interface ItemInterface extends CacheItemInterface
  20. {
  21. /**
  22. * References the Unix timestamp stating when the item will expire.
  23. */
  24. public const METADATA_EXPIRY = 'expiry';
  25. /**
  26. * References the time the item took to be created, in milliseconds.
  27. */
  28. public const METADATA_CTIME = 'ctime';
  29. /**
  30. * References the list of tags that were assigned to the item, as string[].
  31. */
  32. public const METADATA_TAGS = 'tags';
  33. /**
  34. * Reserved characters that cannot be used in a key or tag.
  35. */
  36. public const RESERVED_CHARACTERS = '{}()/\@:';
  37. /**
  38. * Adds a tag to a cache item.
  39. *
  40. * Tags are strings that follow the same validation rules as keys.
  41. *
  42. * @param string|string[] $tags A tag or array of tags
  43. *
  44. * @return $this
  45. *
  46. * @throws InvalidArgumentException When $tag is not valid
  47. * @throws CacheException When the item comes from a pool that is not tag-aware
  48. */
  49. public function tag($tags): self;
  50. /**
  51. * Returns a list of metadata info that were saved alongside with the cached value.
  52. *
  53. * See ItemInterface::METADATA_* consts for keys potentially found in the returned array.
  54. */
  55. public function getMetadata(): array;
  56. }