docs: try_files performance (#1311)

* Updates most performant file_server solution. * Updates most performant file_server solution. * trigger build * Fixes linting. * Shortens the configuration. * Updates title. * Adds try_files optimization. * Ads file_server docs back in. * Update docs/performance.md Co-authored-by: Kévin Dunglas <[email protected]> * Update docs/performance.md Co-authored-by: Kévin Dunglas <[email protected]> --------- Co-authored-by: Alliballibaba <[email protected]> Co-authored-by: Kévin Dunglas <[email protected]>
dunglas · Jan 17, 2025 · e53ba34 · e53ba34
1 parent 34dfd87
commit e53ba34
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 1 deletion.
diff --git a/docs/laravel.md b/docs/laravel.md
@@ -31,7 +31,9 @@ Alternatively, you can run your Laravel projects with FrankenPHP from your local
     	# Enable compression (optional)
     	encode zstd br gzip
     	# Execute PHP files from the public/ directory and serve assets
-    	php_server
+    	php_server {
+    		try_files {path} index.php
+    	}
     }
     ```
 

diff --git a/docs/performance.md b/docs/performance.md
@@ -66,6 +66,44 @@ php_server {
 }
 ```
 
+## `try_files`
+
+Besides static files and PHP files, `php_server` will also try to serve your application's index
+and directory index files (`/path/` -> `/path/index.php`). If you don't need directory indices,
+you can disable them by explicitly defining `try_files` like this:
+
+```caddyfile
+php_server {
+    try_files {path} index.php
+    root /root/to/your/app # explicitly adding the root here allows for better caching
+}
+```
+
+This can significantly reduce the number of unnecessary file operations.
+
+An alternate approach with 0 unnecessary file system operations would be to instead use the `php` directive and split
+files from PHP by path. This approach works well if your entire application is served by one entry file.
+An example [configuration](config.md#caddyfile-config) that serves static files behind an `/assets` folder could look like this:
+
+```caddyfile
+route {
+    @assets {
+        path /assets/*
+    }
+
+    # everything behind /assets is handled by the file server
+    file_server @assets {
+        root /root/to/your/app
+    }
+
+    # everything that is not in /assets is handled by your index or worker PHP file
+    rewrite index.php
+    php {
+        root /root/to/your/app # explicitly adding the root here allows for better caching
+    }
+}
+```
+
 ## Placeholders
 
 You can use [placeholders](https://caddyserver.com/docs/conventions#placeholders) in the `root` and `env` directives.