You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This plugin will give you the performance of a static site generator for your regular Kirby installations. Without a huge setup or complex deploy steps, you can just run your Kirby site on any server – cheap shared hosting, VPS, you name it – and switch on the static cache to get incredible speed on demand.
5
+
This plugin will give you the performance of a static site generator for your regular Kirby installations. Without a huge setup or complex deployment steps, you can run your Kirby site on any server – cheap shared hosting, VPS, you name it – and enable the static cache to get incredible speed on demand.
6
6
7
-
With custom ignore rules, you can even mix static and dynamic content. Keep some pages static while others are still served live by Kirby.
7
+
With custom ignore rules, you can even mix static and dynamic content. Keep some pages static while others are still served live by Kirby.
8
8
9
9
The static cache will automatically be flushed whenever content gets updated in the Panel. It's truly the best of both worlds.
10
10
11
-
Rough benchmark comparison for our starterkit home page:
11
+
Rough benchmark comparison for our Starterkit home page:
12
12
13
13
Without page cache: ~70 ms
14
14
With page cache: ~30 ms
15
15
With static cache: ~10 ms
16
16
17
-
## 🚨 Experimental
17
+
## Limitations
18
18
19
-
This plugin is still an experiment. The first results are very promising but it needs to be tested on more servers and has a couple open todos:
19
+
A statically cached page will prevent any Kirby logic from executing. This means that Kirby can no longer differentiate between visitors and logged-in users. Every request will be served directly by your web server, even if the response would differ based on the cookies or other request headers.
20
20
21
-
-[ ] Nginx config example
22
-
-[ ] Caddy config example
23
-
-[x] Publish on Packagist to be installable via composer
24
-
-[x] Hooks to automatically flush the cache when content is updated via the Panel
25
-
-[x] Add options to ignore pages from caching
21
+
If your site has any logic in controllers, page models, templates, snippets or plugins that results in different page responses depending on the request, this logic will naturally not be compatible with Staticache.
22
+
23
+
If only specific pages are affected by this, you can add them to the cache ignore list (see below) and use Staticache for the rest of your site. Otherwise, using Kirby's default page cache will be the better option overall because Kirby will automatically detect which responses can be cached and which caches can be used for the current request.
If you want to keep some of your pages dynamic, you can configure ignore rules like for the native pages cache: https://getkirby.com/docs/guide/cache#caching-pages
66
67
67
68
```php
68
69
// /site/config/config.php
@@ -71,7 +72,7 @@ return [
71
72
'cache' => [
72
73
'pages' => [
73
74
'active' => true,
74
-
'type' => 'static',
75
+
'type' => 'static',
75
76
'ignore' => function ($page) {
76
77
return $page->template()->name() === 'blog';
77
78
}
@@ -80,32 +81,156 @@ return [
80
81
];
81
82
```
82
83
83
-
Kirby will automatically purge the cache when changes are made in the Panel.
84
+
All pages that are not ignored will automatically be cached on their first visit. Kirby will automatically purge the cache when changes are made in the Panel.
85
+
86
+
**Custom cache comment:**
87
+
88
+
Staticache adds an HTML comment like `<!-- static YYYY-MM-DDT01:02:03+00:00 -->` to the end of every cached HTML file by default. You can override or disable this comment in the cache configuration:
The rendered HTML files are stored in the `site/cache/example.com/pages/` folder just like with the native pages cache. The difference is that all paths within this folder match the URL structure of your site. The separate directories for each root URL ensure that links and references in your rendered HTML keep working even in a multi-domain setup.
115
+
116
+
If you are using a custom web server setup, you can override the cache root like so:
117
+
118
+
```php
119
+
// /site/config/config.php
120
+
121
+
return [
122
+
'cache' => [
123
+
'pages' => [
124
+
'active' => true,
125
+
'type' => 'static',
126
+
'root' => '/path/to/your/cache/root',
127
+
'prefix' => null
128
+
]
129
+
]
130
+
];
131
+
```
132
+
133
+
If your site is only served on a single domain, you can disable the root URL prefix like so while keeping the general storage location in the `site/cache` directory:
134
+
135
+
```php
136
+
// /site/config/config.php
137
+
138
+
return [
139
+
'cache' => [
140
+
'pages' => [
141
+
'active' => true,
142
+
'type' => 'static',
143
+
'prefix' => 'pages'
144
+
]
145
+
]
146
+
];
147
+
```
148
+
149
+
If you use a custom root and/or prefix, please modify the following server configuration examples accordingly.
150
+
151
+
### Web server integration
152
+
153
+
This plugin will automatically generate and store the cache files, however you need to configure your web server to pick the files up and prefer them over a dynamic result from PHP.
84
154
85
-
### htaccess rules
155
+
The configuration depends on your used web server:
86
156
87
-
Add the following lines to your Kirby htaccess file, directly after the RewriteBase rule.
157
+
**Apache:**
158
+
159
+
Add the following lines to your Kirby `.htaccess` file, directly after the `RewriteBase` rule.
change it to add `/static/$uri/index.html` before last `/index.php` fallback
201
+
202
+
### Header support
203
+
204
+
Staticache stores only the response bodies by default. The HTTP status code as well as headers set by your pages are not preserved in this mode. This ensures compatibility with all web servers.
205
+
206
+
If your web server supports reading headers from the static files, you can enable header support with the `headers` option:
207
+
208
+
```php
209
+
// /site/config/config.php
210
+
211
+
return [
212
+
'cache' => [
213
+
'pages' => [
214
+
'active' => true,
215
+
'type' => 'static',
216
+
'headers' => true
217
+
]
218
+
]
219
+
];
220
+
```
221
+
222
+
You need to adapt your web server configuration accordingly:
223
+
224
+
**Apache:**
225
+
226
+
Header support in Apache requires [`mod_asis`](https://httpd.apache.org/docs/current/mod/mod_asis.html). Please ensure that your Apache installation has this module installed and enabled.
227
+
228
+
Afterwards add the following block to your `.htaccess` file to make Apache use `mod_asis` for cached files:
0 commit comments