Skip to content

Commit 213ea4e

Browse files
linawolflinawolf
authored
[TASK] Improve caching frontend page (#6015)
* Autogenerate API * Rephrase * make headlines more concise
1 parent f84ef93 commit 213ea4e

File tree

3 files changed

+179
-96
lines changed

3 files changed

+179
-96
lines changed

‎Documentation/ApiOverview/CachingFramework/Frontends/Index.rst‎

Lines changed: 53 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,83 @@
1-
.. include:: /Includes.rst.txt
1+
.. include:: /Includes.rst.txt
22

3-
.. _caching-frontend:
3+
.. _caching-frontend:
44

55
===============
66
Cache frontends
77
===============
88

9+
A *cache frontend* is the public API for interacting with a cache. It defines
10+
which value types are accepted and how they are prepared for storage
11+
(for example serialization or compilation), while delegating persistence to the
12+
assigned backend. In everyday use, extensions should work with the frontend
13+
only — direct access to the caching backend is discouraged.
914

10-
.. _caching-frontend-api:
15+
.. _caching-frontend-api:
1116

12-
Frontend API
13-
============
17+
Caching frontend API
18+
====================
1419

15-
All frontends must implement the API defined in interface :code:`TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`.
16-
All operations on a specific cache must be done with these methods. The frontend object of a cache is the main object
17-
any cache manipulation is done with, usually the assigned backend object should not be used directly.
20+
All caching frontends must implement the interface
21+
:php:`\TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`.
1822

19-
.. t3-field-list-table::
20-
:header-rows: 1
23+
.. include:: /CodeSnippets/Manual/Cache/FrontendInterface.rst.txt
2124

22-
- :Method,30: Method
23-
:Description,70: Description
25+
The specific cache frontend implementation migth offer additional methods.
2426

25-
- :Method:
26-
getIdentifier
27-
:Description:
28-
Returns the cache identifier.
27+
.. _caching-frontend-avalaible:
2928

30-
- :Method:
31-
getBackend
32-
:Description:
33-
Returns the backend instance of this cache. It is seldom needed in usual code.
29+
Available cache frontend implementations
30+
========================================
3431

35-
- :Method:
36-
set
37-
:Description:
38-
Sets/overwrites an entry in the cache.
32+
Two frontends are currently available. They primarily differ in the data
33+
types they accept and how values are handled before they are passed to
34+
the backend.
3935

40-
- :Method:
41-
get
42-
:Description:
43-
Returns the cache entry for the given identifier.
36+
.. _caching-frontend-variable:
4437

45-
- :Method:
46-
has
47-
:Description:
48-
Checks for existence of a cache entry.
49-
Do no use this prior to :code:`get()` since :code:`get()`
50-
returns NULL if an entry does not exist.
51-
52-
- :Method:
53-
remove
54-
:Description:
55-
Removes the entry for the given identifier from the cache.
56-
57-
- :Method:
58-
flushByTag
59-
:Description:
60-
Flushes all cache entries which are tagged with the given tag.
61-
62-
- :Method:
63-
collectGarbage
64-
:Description:
65-
Calls the garbage collection method of the backend.
66-
This is important for backends which are unable to do this internally
67-
(like the DB backend).
68-
69-
- :Method:
70-
isValidEntryIdentifier
71-
:Description:
72-
Checks if a given identifier is valid.
73-
74-
- :Method:
75-
isValidTag
76-
:Description:
77-
Checks if a given tag is valid.
78-
79-
- :Method:
80-
requireOnce
81-
:Description:
82-
**PhpFrontend only** Requires a cached PHP file directly.
83-
84-
85-
.. _caching-frontend-avalaible:
38+
Variable frontend
39+
-----------------
8640

87-
Available Frontends
88-
===================
41+
This frontend accepts strings, arrays, and objects.
42+
Values are serialized before they are written to the caching backend.
8943

90-
Currently two different frontends are implemented. The main difference are
91-
the data types which can be stored using a specific frontend.
44+
It is implemented in :php:`TYPO3\CMS\Core\Cache\Frontend\VariableFrontend`.
9245

46+
.. tip::
47+
The variable frontend is the most frequently used frontend and handles
48+
the widest range of data types.
9349

94-
.. _caching-frontend-variable:
9550

96-
Variable Frontend
97-
-----------------
51+
.. _caching-frontend-php:
9852

99-
Strings, arrays and objects are accepted by this frontend.
100-
Data is serialized before it is passed to the backend.
53+
PHP frontend
54+
------------
10155

102-
.. tip::
103-
The variable frontend is the most frequently used frontend and handles
104-
the widest range of data types.
56+
This frontend is specialized for caching executable PHP files. It adds the
57+
methods :php:`requireOnce()` and :php:`require()` to load a cached file
58+
directly. This is useful for extensions that generate PHP code at runtime,
59+
for example when heavy reflection or dynamic class construction is involved.
10560

61+
It is implemented in :php:`TYPO3\CMS\Core\Cache\Frontend\PhpFrontend`.
10662

107-
.. _caching-frontend-php:
63+
A backend used with the PHP frontend must implement
64+
:php:`\TYPO3\CMS\Core\Cache\Backend\PhpCapableBackendInterface`. The file
65+
backend and the simple file backend currently fulfill this requirement.
10866

109-
PHP Frontend
110-
------------
67+
In addition to the methods defined by
68+
:php:`\TYPO3\CMS\Core\Cache\Frontend\FrontendInterface`, it provides:
11169

112-
This is a special frontend to cache PHP files. It extends the string frontend
113-
with the method :code:`requireOnce()` which allows PHP files to be :code:`require()`'d
114-
if a cache entry exists. This can be used by extensions to cache and speed up loading
115-
of calculated PHP code and becomes handy if a lot of reflection and
116-
dynamic PHP class construction is done.
70+
`requireOnce($entryIdentifier)`
71+
Loads PHP code from the cache and :php:`require_once` it right away.
72+
`require(string $entryIdentifier)`
73+
Loads PHP code from the cache and `require()` it right away.
11774

118-
A backend to be used in combination with the PHP frontend must implement the interface
119-
:code:`TYPO3\CMS\Core\Cache\Backend\PhpCapableBackendInterface`. Currently the file backend and
120-
the simple file backend fulfill this requirement.
75+
Unlike `require_once()`, `require()` is safe **only** when the cached code can be
76+
included multiple times within a single request. Files that declare classes,
77+
functions, or constants may trigger redeclaration errors.
12178

122-
.. note::
79+
.. note::
12380

124-
The PHP frontend can **only** be used to cache PHP files.
125-
It does not work with strings, arrays or objects.
126-
It is **not** intended as a page content cache.
81+
The PHP caching frontend can **only** be used to cache PHP files.
82+
It does not work with strings, arrays or objects.
83+
It is **not** intended as a page content cache.

‎Documentation/CodeSnippets/Config/Api/Cache.php‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,18 @@
77
'targetFileName' => 'CodeSnippets/Manual/Cache/CacheDataCollector.rst.txt',
88
'withCode' => false,
99
],
10+
[
11+
'action' => 'createPhpClassDocs',
12+
'class' => \TYPO3\CMS\Core\Cache\Frontend\FrontendInterface::class,
13+
'targetFileName' => 'CodeSnippets/Manual/Cache/FrontendInterface.rst.txt',
14+
'withCode' => false,
15+
],
16+
[
17+
'action' => 'createPhpClassDocs',
18+
'class' => \TYPO3\CMS\Core\Cache\Frontend\FrontendInterface::class,
19+
'targetFileName' => 'CodeSnippets/Manual/Cache/FrontendInterface.rst.txt',
20+
'withCode' => false,
21+
],
1022
[
1123
'action' => 'createPhpClassDocs',
1224
'class' => \TYPO3\CMS\Core\Cache\Backend\BackendInterface::class,

‎Documentation/CodeSnippets/Manual/Cache/FrontendInterface.rst.txt‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
2+
.. php:namespace:: TYPO3\CMS\Core\Cache\Frontend
3+
4+
.. php:interface:: FrontendInterface
5+
6+
Contract for a Cache (frontend)
7+
8+
.. php:const:: TAG_CLASS
9+
:public:
10+
11+
:php:`'%CLASS%'`, type string
12+
13+
"Magic" tag for class-related entries
14+
15+
.. php:const:: TAG_PACKAGE
16+
:public:
17+
18+
:php:`'%PACKAGE%'`, type string
19+
20+
"Magic" tag for package-related entries
21+
22+
.. php:const:: PATTERN_ENTRYIDENTIFIER
23+
:public:
24+
25+
:php:`'/^[a-zA-Z0-9_%\\-&]{1,250}$/'`, type string
26+
27+
Pattern an entry identifier must match.
28+
29+
.. php:const:: PATTERN_TAG
30+
:public:
31+
32+
:php:`'/^[a-zA-Z0-9_%\\-&]{1,250}$/'`, type string
33+
34+
Pattern a tag must match.
35+
36+
.. php:method:: getIdentifier()
37+
:returns: `string`
38+
39+
Returns this cache's identifier
40+
41+
:Return description: The identifier for this cache
42+
43+
.. php:method:: getBackend()
44+
:returns: `\TYPO3\CMS\Core\Cache\Backend\BackendInterface`
45+
46+
Returns the backend used by this cache
47+
48+
:Return description: The backend used by this cache
49+
50+
.. php:method:: set(?string $entryIdentifier, ?mixed $data, array $tags = [], ?int $lifetime = NULL)
51+
52+
Saves data in the cache.
53+
54+
:param $entryIdentifier: Something which identifies the data - depends on concrete cache
55+
:param $data: The data to cache - also depends on the concrete cache implementation
56+
:param $tags: Tags to associate with this cache entry, default: []
57+
:param $lifetime: Lifetime of this cache entry in seconds. If NULL is specified, the default lifetime is used. "0" means unlimited lifetime., default: NULL
58+
59+
.. php:method:: get(?string $entryIdentifier)
60+
:returns: `mixed`
61+
62+
Finds and returns data from the cache.
63+
64+
:param $entryIdentifier: Something which identifies the cache entry - depends on concrete cache
65+
66+
.. php:method:: has(?string $entryIdentifier)
67+
:returns: `bool`
68+
69+
Checks if a cache entry with the specified identifier exists.
70+
71+
:param $entryIdentifier: An identifier specifying the cache entry
72+
:Return description: TRUE if such an entry exists, FALSE if not
73+
74+
.. php:method:: remove(?string $entryIdentifier)
75+
:returns: `bool`
76+
77+
Removes the given cache entry from the cache.
78+
79+
:param $entryIdentifier: An identifier specifying the cache entry
80+
:Return description: TRUE if such an entry exists, FALSE if not
81+
82+
.. php:method:: flush()
83+
84+
Removes all cache entries of this cache.
85+
86+
.. php:method:: flushByTag(?string $tag)
87+
88+
Removes all cache entries of this cache which are tagged by the specified tag.
89+
90+
:param $tag: The tag the entries must have
91+
92+
.. php:method:: flushByTags(array $tags)
93+
94+
Removes all cache entries of this cache which are tagged by any of the specified tags.
95+
96+
:param $tags: List of tags
97+
98+
.. php:method:: collectGarbage()
99+
100+
Does garbage collection
101+
102+
.. php:method:: isValidEntryIdentifier(?string $identifier)
103+
:returns: `bool`
104+
105+
Checks the validity of an entry identifier. Returns TRUE if it's valid.
106+
107+
:param $identifier: An identifier to be checked for validity
108+
109+
.. php:method:: isValidTag(?string $tag)
110+
:returns: `bool`
111+
112+
Checks the validity of a tag. Returns TRUE if it's valid.
113+
114+
:param $tag: A tag to be checked for validity

0 commit comments

Comments
 (0)