From 47fbe90ea2b766d63adee5d26be6ea7c1f59ce1d Mon Sep 17 00:00:00 2001
From: Alexander Shabunevich <loonar@gmail.com>
Date: Sat, 24 Oct 2026 19:03:58 +0300
Subject: [PATCH] Add caddyfile-snippets.d for custom snippets

---
 .../docs/2.image-variations/frankenphp.md     | 20 +++++++++++++++++++
 .../frankenphp/etc/frankenphp/Caddyfile       |  3 +++
 .../caddyfile-snippets.d/README.caddyfile     |  9 +++++++++
 3 files changed, 32 insertions(+)
 create mode 100644 src/variations/frankenphp/etc/frankenphp/caddyfile-snippets.d/README.caddyfile

diff --git a/docs/content/docs/2.image-variations/frankenphp.md b/docs/content/docs/2.image-variations/frankenphp.md
index 910f7e6a..9792a1db 100644
--- a/docs/content/docs/2.image-variations/frankenphp.md
+++ b/docs/content/docs/2.image-variations/frankenphp.md
@@ -447,6 +447,7 @@ Most changes only need one of the [environment variables](#frankenphpcaddy-confi
 |-------|----------------|----------------------|--------|
 | Global | [Global options](https://caddyserver.com/docs/caddyfile/options){target="_blank"}, including Caddy's `servers` option | `CADDY_GLOBAL_OPTIONS` | `/etc/frankenphp/caddyfile-global.d/` |
 | Server | [Directives](https://caddyserver.com/docs/caddyfile/directives){target="_blank"} for your app, like `header`, `redir`, and request matchers | `CADDY_SERVER_EXTRA_DIRECTIVES` | `/etc/frankenphp/caddyfile-server.d/` |
+| Snippets | [Snippets](https://caddyserver.com/docs/caddyfile/concepts#snippets){target="_blank"} for your app | None | `/etc/frankenphp/caddyfile-snippets.d/` |
 | New sites | Extra site blocks, like a second domain or a reverse proxy | None | `/etc/frankenphp/caddyfile.d/` |
 
 Every `.caddyfile` file in a folder is imported at that level. Use the environment variables for a quick one-liner and the folders for anything longer. The folders also work with [Laravel Octane](/docs/framework-guides/laravel/octane#octane-options), which replaces `CADDY_GLOBAL_OPTIONS` and `CADDY_SERVER_EXTRA_DIRECTIVES` with its own values.
@@ -520,6 +521,25 @@ basic_auth @protected {
 Generate the password hash with `docker run --rm -it serversideup/php:8.5-frankenphp frankenphp hash-password`.
 ::
 
+#### Add custom snippet
+
+Files in `caddyfile-snippets.d/` sit at the top of the Caddyfile, outside your app's site, before any other snippets. Use them to create custom snippets:
+
+```caddyfile [logging.caddyfile]
+(logging) {
+	log {
+		output file /var/log/caddy.log
+		format json
+	}
+}
+```
+
+Then use this snippet anywhere you need, for example in your server config:
+
+```caddyfile [caddyfile-server.d/app.caddyfile]
+import logging
+```
+
 #### Add another site
 Files in `caddyfile.d/` sit at the top level of the Caddyfile, outside your app's site. Use them for a whole new site block:
 
diff --git a/src/variations/frankenphp/etc/frankenphp/Caddyfile b/src/variations/frankenphp/etc/frankenphp/Caddyfile
index 4c3103c6..f417ae00 100644
--- a/src/variations/frankenphp/etc/frankenphp/Caddyfile
+++ b/src/variations/frankenphp/etc/frankenphp/Caddyfile
@@ -1,3 +1,6 @@
+# Add additional Caddy configuration files from the caddyfile-snippets.d directory
+import caddyfile-snippets.d/*.caddyfile
+
 ########################################################
 # Global Caddy configuration
 ########################################################
diff --git a/src/variations/frankenphp/etc/frankenphp/caddyfile-snippets.d/README.caddyfile b/src/variations/frankenphp/etc/frankenphp/caddyfile-snippets.d/README.caddyfile
new file mode 100644
index 00000000..4dc65b00
--- /dev/null
+++ b/src/variations/frankenphp/etc/frankenphp/caddyfile-snippets.d/README.caddyfile
@@ -0,0 +1,9 @@
+# Add your own .caddyfile files to this directory. They are imported at
+# the top of /etc/frankenphp/Caddyfile, so you can define custom snippets.
+# Use caddyfile-global.d/ for global options.
+# Use caddyfile-server.d/ to add directives to your app's site instead.
+# Use caddyfile.d/ to define extra site blocks.
+#
+# This file only exists so the import glob matches something. Caddy logs
+# "No files matching import glob pattern" on every start when a directory
+# like this one is empty.