docs: Adjustments for v2.4.6

src/docs/markdown/caddyfile/concepts.md

@@ -252,6 +252,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd
 | `{tls_client_serial}`      | `{http.request.tls.client.serial}`      |
 | `{tls_client_subject}`     | `{http.request.tls.client.subject}`     |
 | `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` |
+| `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
 
 

src/docs/markdown/caddyfile/directives/php_fastcgi.md

@@ -8,7 +8,7 @@ An opinionated directive that proxies requests to a PHP FastCGI server such as p
 
 Caddy's [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. This directive is actually just a convenient way to use a longer, more common configuration (below).
 
-It expects that any `index.php` at the site root acts as a router. If that is not desirable, either perform your own URI rewrite or use something like the [expanded form](#expanded-form) below and customize it to your needs.
+It expects that any `index.php` at the site root acts as a router. If that is not desirable, either reconfigure the `try_files` option to modify the default rewrite behaviour, or take the [expanded form](#expanded-form) below as a basis and customize it to your needs.
 
 It supports all the subdirectives of [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying reverse_proxy handler, plus a few subdirectives that customize the FastCGI transport specifically.
 
@@ -22,6 +22,7 @@ php_fastcgi [<matcher>] <php-fpm_gateways...> {
 	split <substrings...>
 	env [<key> <value>]
 	index <filename>|off
+	try_files <files...>
 	resolve_root_symlink
 	dial_timeout  <duration>
 	read_timeout  <duration>
@@ -36,6 +37,7 @@ php_fastcgi [<matcher>] <php-fpm_gateways...> {
 - **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php`
 - **env** sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables.
 - **index** specifies the filename to treat as the directory index file. This affects the file matcher in the [expanded form](#expanded-form). Default: `index.php`. Can be set to `off` to disable rewriting to `index.php` when a matching file is not found.
+- **try_files** specifies an override for the default try-files rewrite. See the [`try_files` directive](/docs/caddyfile/directives/try_files) for details. Default: `{path} {path}/index.php index.php`.
 - **resolve_root_symlink** enables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists.
 - **dial_timeout** is how long to wait when connecting to the upstream socket. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 - **read_timeout** is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
@@ -104,3 +106,11 @@ root * /var/www/html
 php_fastcgi 127.0.0.1:9000
 file_server
 ```
+
+For a PHP site which does not use `index.php` as an entrypoint, you may fallback to emitting a `404` error instead. The error may be handled with the [`handle_errors` directive](/docs/caddyfile/directives/handle_errors):
+
+```caddy-d
+php_fastcgi localhost:9000 {
+	try_files {path} {path}/index.php =404
+}
+```

src/docs/markdown/caddyfile/directives/try_files.md

@@ -13,7 +13,7 @@ Rewrites the request URI path to the first of the listed files which exists in t
 try_files <files...>
 ```
 
-- **<files...>** is the list of files to try. The URI will be rewritten to the first one that exists. To match directories, append a trailing forward slash `/` to the path. All file paths are relative to the site [root](/docs/caddyfile/directives/root). Each argument may also contain a query string, in which case the query string will also be changed if it matches that particular file.
+- **<files...>** is the list of files to try. The URI will be rewritten to the first one that exists. To match directories, append a trailing forward slash `/` to the path. All file paths are relative to the site [root](/docs/caddyfile/directives/root). Each argument may also contain a query string, in which case the query string will also be changed if it matches that particular file. The last item in the list may be a number prefixed by `=` (e.g. `=404`), which as a fallback, will emit an error with that code; the error can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors).
 
 
 ## Expanded form
@@ -49,3 +49,9 @@ Same, but also match directories:
 ```caddy-d
 try_files {path} {path}/ /index.php?{query}&p={path}
 ```
+
+Attempt to rewrite to a file or directory if it exists, otherwise emit a 404 error (which can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors)):
+
+```caddy-d
+try_files {path} {path}/ =404
+```

src/docs/markdown/caddyfile/matchers.md

@@ -203,6 +203,7 @@ expression {http.error.status_code} == 404
 ```
 
 
+
 ---
 ### file
 
@@ -218,7 +219,7 @@ file {
 By files.
 
 - `root` defines the directory in which to look for files. Default is the current working directory, or the `root` [variable](/docs/modules/http.handlers.vars) (`{http.vars.root}`) if set (can be set via the [`root` directive](/docs/caddyfile/directives/root)).
-- `try_files` checks files in its list that match the try_policy.
+- `try_files` checks files in its list that match the try_policy. If the `try_policy` is `first_exist`, then the last item in the list may be a number prefixed by `=` (e.g. `=404`), which as a fallback, will emit an error with that code; the error can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors).
 - `try_policy` specifies how to choose a file. Default is `first_exist`.
 	- `first_exist` checks for file existence. The first file that exists is selected.
 	- `smallest_size` chooses the file with the smallest size.
@@ -257,6 +258,13 @@ file {
 }
 ```
 
+Same as above, except using the one-line shortcut, and falling back to emitting a 404 error if a file is not found.
+
+```caddy-d
+file {path}.html {path} =404
+```
+
+
 
 ---
 ### header
@@ -301,6 +309,7 @@ Match requests that do not have the `Foo` header field at all:
 ```
 
 
+
 ---
 ### header_regexp
 
@@ -310,6 +319,8 @@ header_regexp [<name>] <field> <regexp>
 
 Like `header`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
+
 Only one regular expression is supported per header field. Multiple different fields will be AND'ed.
 
 #### Example:
@@ -321,6 +332,7 @@ header_regexp login Cookie login_([a-f0-9]+)
 ```
 
 
+
 ---
 ### host
 
@@ -339,6 +351,7 @@ host sub.example.com
 ```
 
 
+
 ---
 ### method
 
@@ -365,6 +378,7 @@ method PUT DELETE
 ```
 
 
+
 ---
 ### not
 
@@ -415,6 +429,7 @@ not {
 ```
 
 
+
 ---
 ### path
 
@@ -429,9 +444,12 @@ By request path, meaning the path component of the request's URI. Path matches a
 - On both sides, for a substring match (`*/contains/*`)
 - In the middle, for a globular match (`/accounts/*/info`)
 
+The request path is URL-decoded, lowercased (to be case insensitive), and cleaned (to collapse doubled-up slashes and directory traversal dots) before matching. For example `/foo*` will also match `/FOO`, `//foo` and `/%2F/foo`.
+
 Multiple `path` matchers will be OR'ed together.
 
 
+
 ---
 ### path_regexp
 
@@ -441,6 +459,10 @@ path_regexp [<name>] <regexp>
 
 Like `path`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+The request path is URL-decoded, and cleaned (to collapse doubled-up slashes and directory traversal dots) before matching. For example `/foo*` will also match `//foo` and `/%2F/foo`.
+
+The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
+
 There can only be one `path_regexp` matcher per named matcher.
 
 #### Example:
@@ -452,6 +474,7 @@ path_regexp static \.([a-f0-9]{6})\.(css|js)$
 ```
 
 
+
 ---
 ### protocol
 
@@ -464,6 +487,7 @@ By request protocol.
 There can only be one `protocol` matcher per named matcher.
 
 
+
 ---
 ### query
 
@@ -484,6 +508,7 @@ query sort=asc
 ```
 
 
+
 ---
 ### remote_ip