authorizer / vendor / psr / cache / src / CacheItemInterface.php

CacheItemInterface.php in Authorizer 3.14.2, at vendor/psr/cache/src/CacheItemInterface.php

106 lines 3.8 KB

Raw Download Zip

1	<?php
2
3	namespace Psr\Cache;
4
5	/**
6	* CacheItemInterface defines an interface for interacting with objects inside a cache.
7	*
8	* Each Item object MUST be associated with a specific key, which can be set
9	* according to the implementing system and is typically passed by the
10	* Cache\CacheItemPoolInterface object.
11	*
12	* The Cache\CacheItemInterface object encapsulates the storage and retrieval of
13	* cache items. Each Cache\CacheItemInterface is generated by a
14	* Cache\CacheItemPoolInterface object, which is responsible for any required
15	* setup as well as associating the object with a unique Key.
16	* Cache\CacheItemInterface objects MUST be able to store and retrieve any type
17	* of PHP value defined in the Data section of the specification.
18	*
19	* Calling Libraries MUST NOT instantiate Item objects themselves. They may only
20	* be requested from a Pool object via the getItem() method. Calling Libraries
21	* SHOULD NOT assume that an Item created by one Implementing Library is
22	* compatible with a Pool from another Implementing Library.
23	*/
24	interface CacheItemInterface
25	{
26	/**
27	* Returns the key for the current cache item.
28	*
29	* The key is loaded by the Implementing Library, but should be available to
30	* the higher level callers when needed.
31	*
32	* @return string
33	* The key string for this cache item.
34	*/
35	public function getKey(): string;
36
37	/**
38	* Retrieves the value of the item from the cache associated with this object's key.
39	*
40	* The value returned must be identical to the value originally stored by set().
41	*
42	* If isHit() returns false, this method MUST return null. Note that null
43	* is a legitimate cached value, so the isHit() method SHOULD be used to
44	* differentiate between "null value was found" and "no value was found."
45	*
46	* @return mixed
47	* The value corresponding to this cache item's key, or null if not found.
48	*/
49	public function get(): mixed;
50
51	/**
52	* Confirms if the cache item lookup resulted in a cache hit.
53	*
54	* Note: This method MUST NOT have a race condition between calling isHit()
55	* and calling get().
56	*
57	* @return bool
58	* True if the request resulted in a cache hit. False otherwise.
59	*/
60	public function isHit(): bool;
61
62	/**
63	* Sets the value represented by this cache item.
64	*
65	* The $value argument may be any item that can be serialized by PHP,
66	* although the method of serialization is left up to the Implementing
67	* Library.
68	*
69	* @param mixed $value
70	* The serializable value to be stored.
71	*
72	* @return static
73	* The invoked object.
74	*/
75	public function set(mixed $value): static;
76
77	/**
78	* Sets the expiration time for this cache item.
79	*
80	* @param ?\DateTimeInterface $expiration
81	* The point in time after which the item MUST be considered expired.
82	* If null is passed explicitly, a default value MAY be used. If none is set,
83	* the value should be stored permanently or for as long as the
84	* implementation allows.
85	*
86	* @return static
87	* The called object.
88	*/
89	public function expiresAt(?\DateTimeInterface $expiration): static;
90
91	/**
92	* Sets the expiration time for this cache item.
93	*
94	* @param int\|\DateInterval\|null $time
95	* The period of time from the present after which the item MUST be considered
96	* expired. An integer parameter is understood to be the time in seconds until
97	* expiration. If null is passed explicitly, a default value MAY be used.
98	* If none is set, the value should be stored permanently or for as long as the
99	* implementation allows.
100	*
101	* @return static
102	* The called object.
103	*/
104	public function expiresAfter(int\|\DateInterval\|null $time): static;
105	}
106