merge

Author: henderkes

.github/workflows/tests.yaml

@@ -68,7 +68,7 @@ jobs:
       - name: Run integrations tests
         run: ./reload_test.sh
       - name: Lint Go code
-        uses: golangci/golangci-lint-action@v6
+        uses: golangci/golangci-lint-action@v7
         if: matrix.php-versions == '8.4'
         with:
           version: latest

README.md

@@ -88,6 +88,7 @@ frankenphp php-server
 * [Worker mode](https://frankenphp.dev/docs/worker/)
 * [Early Hints support (103 HTTP status code)](https://frankenphp.dev/docs/early-hints/)
 * [Real-time](https://frankenphp.dev/docs/mercure/)
+* [Efficiently Serving Large Static Files](https://frankenphp.dev/docs/x-sendfile/)
 * [Configuration](https://frankenphp.dev/docs/config/)
 * [Docker images](https://frankenphp.dev/docs/docker/)
 * [Deploy in production](https://frankenphp.dev/docs/production/)

build-static.sh

@@ -138,9 +138,9 @@ if type "brew" >/dev/null 2>&1; then
 fi
 
 if [ "${SPC_REL_TYPE}" = "binary" ]; then
-	mkdir static-php-cli/
+	mkdir -p static-php-cli/
 	cd static-php-cli/
-	curl -o spc -fsSL "https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-$(uname -m)"
+	curl -o spc -fsSL "https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-${arch}"
 	chmod +x spc
 	spcCommand="./spc"
 elif [ -d "static-php-cli/src" ]; then

caddy/admin.go

@@ -44,7 +44,7 @@ func (admin *FrankenPHPAdmin) restartWorkers(w http.ResponseWriter, r *http.Requ
 	return nil
 }
 
-func (admin *FrankenPHPAdmin) threads(w http.ResponseWriter, r *http.Request) error {
+func (admin *FrankenPHPAdmin) threads(w http.ResponseWriter, _ *http.Request) error {
 	debugState := frankenphp.DebugState()
 	prettyJson, err := json.MarshalIndent(debugState, "", "    ")
 	if err != nil {

caddy/frankenphp/Caddyfile

@@ -19,7 +19,7 @@
 	#	}
 	#}
 
-	root * public/
+	root public/
 	encode zstd br gzip
 
 	# Uncomment the following lines to enable Mercure and Vulcain modules

cgi.go

@@ -168,7 +168,7 @@ func packCgiVariable(key *C.zend_string, value string) C.ht_key_value_pair {
 	return C.ht_key_value_pair{key, toUnsafeChar(value), C.size_t(len(value))}
 }
 
-func addHeadersToServer(thread *phpThread, fc *frankenPHPContext, trackVarsArray *C.zval) {
+func addHeadersToServer(fc *frankenPHPContext, trackVarsArray *C.zval) {
 	for field, val := range fc.request.Header {
 		if k := mainThread.commonHeaders[field]; k != nil {
 			v := strings.Join(val, ", ")
@@ -197,7 +197,7 @@ func go_register_variables(threadIndex C.uintptr_t, trackVarsArray *C.zval) {
 	fc := thread.getRequestContext()
 
 	addKnownVariablesToServer(thread, fc, trackVarsArray)
-	addHeadersToServer(thread, fc, trackVarsArray)
+	addHeadersToServer(fc, trackVarsArray)
 
 	// The Prepared Environment is registered last and can overwrite any previous values
 	addPreparedEnvToServer(fc, trackVarsArray)

docs/config.md

@@ -2,8 +2,7 @@
 
 FrankenPHP, Caddy as well as the Mercure and Vulcain modules can be configured using [the formats supported by Caddy](https://caddyserver.com/docs/getting-started#your-first-config).
 
-In [the Docker images](docker.md), the `Caddyfile` is located at `/etc/caddy/Caddyfile`.
-The static binary will look for the `Caddyfile` in the directory in which it is started.
+In [the Docker images](docker.md), the `Caddyfile` is located at `/etc/caddy/Caddyfile`. The static binary will look for the `Caddyfile` in the directory where the `frankenphp run` command is executed. You can specify a custom path with the `-c` or `--config` option.
 
 PHP itself can be configured [using a `php.ini` file](https://www.php.net/manual/en/configuration.file.php).
 
@@ -103,7 +102,9 @@ other.example.com {
 ```
 
 Using the `php_server` directive is generally what you need,
-but if you need full control, you can use the lower level `php` directive:
+but if you need full control, you can use the lower-level `php` directive.
+The `php` directive passes all input to PHP, instead of first checking whether
+it's a PHP file or not. Read more about it in the [performance page](performance.md).
 
 Using the `php_server` directive is equivalent to this configuration:
 

docs/fr/config.md

@@ -104,6 +104,8 @@ other.example.com {
 
 L'utilisation de la directive `php_server` est généralement suffisante,
 mais si vous avez besoin d'un contrôle total, vous pouvez utiliser la directive `php`, qui permet un plus grand niveau de finesse dans la configuration.
+La directive `php` transmet toutes les entrées à PHP, au lieu de vérifier d'abord si
+c'est un fichier PHP ou pas. En savoir plus à ce sujet dans la [page performances](performance.md).
 
 Utiliser la directive `php_server` est équivalent à cette configuration :
 

docs/fr/x-sendfile.md

@@ -0,0 +1,71 @@
+# Servir efficacement les gros fichiers statiques (`X-Sendfile`/`X-Accel-Redirect`)
+
+Habituellement, les fichiers statiques peuvent être servis directement par le serveur web,
+mais parfois, il est nécessaire d'exécuter du code PHP avant de les envoyer :
+contrôle d'accès, statistiques, en-têtes HTTP personnalisés...
+
+Malheureusement, utiliser PHP pour servir de gros fichiers statiques est inefficace comparé à
+à l'utilisation directe du serveur web (surcharge mémoire, diminution des performances...).
+
+FrankenPHP permet de déléguer l'envoi des fichiers statiques au serveur web
+**après** avoir exécuté du code PHP personnalisé.
+
+Pour ce faire, votre application PHP n'a qu'à définir un en-tête HTTP personnalisé
+contenant le chemin du fichier à servir. FrankenPHP se chargera du reste.
+
+Cette fonctionnalité est connue sous le nom de **`X-Sendfile`** pour Apache, et **`X-Accel-Redirect`** pour NGINX.
+
+Dans les exemples suivants, nous supposons que le "document root" du projet est le répertoire `public/`
+et que nous voulons utiliser PHP pour servir des fichiers stockés en dehors du dossier `public/`,
+depuis un répertoire nommé `private-files/`.
+
+## Configuration
+
+Tout d'abord, ajoutez la configuration suivante à votre `Caddyfile` pour activer cette fonctionnalité :
+
+```patch
+	root public/
+	# ...
+
++	# Needed for Symfony, Laravel and other projects using the Symfony HttpFoundation component
++	request_header X-Sendfile-Type x-accel-redirect
++	request_header X-Accel-Mapping ../private-files=/private-files
++
++	intercept {
++		@accel header X-Accel-Redirect *
++		handle_response @accel {
++			root private-files/
++			rewrite * {resp.header.X-Accel-Redirect}
++			method * GET
++
++			# Remove the X-Accel-Redirect header set by PHP for increased security
++			header -X-Accel-Redirect
++
++			file_server
++		}
++	}
+
+	php_server
+```
+
+## PHP simple
+
+Définissez le chemin relatif du fichier (à partir de `private-files/`) comme valeur de l'en-tête `X-Accel-Redirect` :
+
+```php
+header('X-Accel-Redirect: file.txt') ;
+```
+
+## Projets utilisant le composant Symfony HttpFoundation (Symfony, Laravel, Drupal...)
+
+Symfony HttpFoundation [supporte nativement cette fonctionnalité](https://symfony.com/doc/current/components/http_foundation.html#serving-files).
+Il va automatiquement déterminer la bonne valeur pour l'en-tête `X-Accel-Redirect` et l'ajoutera à la réponse.
+
+```php
+use Symfony\Component\HttpFoundation\BinaryFileResponse;
+
+BinaryFileResponse::trustXSendfileTypeHeader();
+$response = new BinaryFileResponse(__DIR__.'/../private-files/file.txt');
+
+// ...
+```

docs/x-sendfile.md

@@ -0,0 +1,71 @@
+# Efficiently Serving Large Static Files (`X-Sendfile`/`X-Accel-Redirect`)
+
+Usually, static files can be served directly by the web server,
+but sometimes it's necessary to execute some PHP code before sending them:
+access control, statistics, custom HTTP headers...
+
+Unfortunately, using PHP to serve large static files is inefficient compared to
+direct use of the web server (memory overload, reduced performance...).
+
+FrankenPHP lets you delegate the sending of static files to the web server
+**after** executing customized PHP code.
+
+To do this, your PHP application simply needs to define a custom HTTP header
+containing the path of the file to be served. FrankenPHP takes care of the rest.
+
+This feature is known as **`X-Sendfile`** for Apache, and **`X-Accel-Redirect`** for NGINX.
+
+In the following examples, we assume that the document root of the project is the `public/` directory.
+and that we want to use PHP to serve files stored outside the `public/` directory,
+from a directory named `private-files/`.
+
+## Configuration
+
+First, add the following configuration to your `Caddyfile` to enable this feature:
+
+```patch
+	root public/
+	# ...
+
++	# Needed for Symfony, Laravel and other projects using the Symfony HttpFoundation component
++	request_header X-Sendfile-Type x-accel-redirect
++	request_header X-Accel-Mapping ../private-files=/private-files
++
++	intercept {
++		@accel header X-Accel-Redirect *
++		handle_response @accel {
++			root private-files/
++			rewrite * {resp.header.X-Accel-Redirect}
++			method * GET
++
++			# Remove the X-Accel-Redirect header set by PHP for increased security
++			header -X-Accel-Redirect
++
++			file_server
++		}
++	}
+
+	php_server
+```
+
+## Plain PHP
+
+Set the relative file path (from `private-files/`) as the value of the `X-Accel-Redirect` header:
+
+```php
+header('X-Accel-Redirect: file.txt');
+```
+
+## Projects using the Symfony HttpFoundation component (Symfony, Laravel, Drupal...)
+
+Symfony HttpFoundation [natively supports this feature](https://symfony.com/doc/current/components/http_foundation.html#serving-files).
+It will automatically determine the correct value for the `X-Accel-Redirect` header and add it to the response.
+
+```php
+use Symfony\Component\HttpFoundation\BinaryFileResponse;
+
+BinaryFileResponse::trustXSendfileTypeHeader();
+$response = new BinaryFileResponse(__DIR__.'/../private-files/file.txt');
+
+// ...
+```