From cfc78c29225c3e065f2f2c095ae7576293934559 Mon Sep 17 00:00:00 2001
From: KalimeroMK <zoranbogoevski@gmail.com>
Date: Thu, 20 Aug 2026 11:04:59 +0200
Subject: [PATCH] docs: add Yii 3 page

Add a documentation page for running Yii 3 applications with FrankenPHP:
Docker image, local install, and worker mode via yiisoft/yii-runner-frankenphp.

Closes https://github.com/yiisoft/yii-runner-frankenphp/issues/5.
---
 docs/yii3.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 docs/yii3.md

diff --git a/docs/yii3.md b/docs/yii3.md
new file mode 100644
index 0000000000..cc6234f9f6
--- /dev/null
+++ b/docs/yii3.md
@@ -0,0 +1,93 @@
+---
+title: Running Yii 3 with FrankenPHP (Docker, worker mode)
+description: How to run a Yii 3 application with FrankenPHP using the Docker image, a local install, or worker mode with the yii-runner-frankenphp package.
+---
+
+# Yii 3
+
+## Running Yii 3 with the FrankenPHP Docker image
+
+Serving a [Yii](https://www.yiiframework.com/) web application with FrankenPHP is as easy as mounting the project in the `/app` directory of the official Docker image.
+
+Run this command from the main directory of your Yii app:
+
+```console
+docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp
+```
+
+And enjoy!
+
+## Installing Yii 3 with FrankenPHP locally
+
+Alternatively, you can run your Yii projects with FrankenPHP from your local machine:
+
+1. [Download the binary corresponding to your system](../#standalone-binary)
+2. Add the following configuration to a file named `Caddyfile` in the root directory of your Yii project:
+
+   ```caddyfile
+   {
+   	frankenphp
+   }
+
+   # The domain name of your server
+   localhost {
+   	# Set the webroot to the public/ directory
+   	root public/
+   	# Enable compression (optional)
+   	encode zstd br gzip
+   	# Execute PHP files from the public/ directory and serve assets
+   	php_server {
+   		try_files {path} index.php
+   	}
+   }
+   ```
+
+3. Start FrankenPHP from the root directory of your Yii project: `frankenphp run`
+
+## Yii 3 worker mode
+
+To run your Yii application in [worker mode](worker.md), install the [Yii FrankenPHP runner](https://github.com/yiisoft/yii-runner-frankenphp):
+
+```console
+composer require yiisoft/yii-runner-frankenphp
+```
+
+Then create a file named `worker.php` in the root directory of your application:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yiisoft\Yii\Runner\FrankenPHP\FrankenPHPApplicationRunner;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+(new FrankenPHPApplicationRunner(rootPath: __DIR__))->run();
+```
+
+Update your `Caddyfile` to start the application in worker mode:
+
+```caddyfile
+{
+	frankenphp
+}
+
+localhost {
+	root public/
+	encode zstd br gzip
+	php_server {
+		worker {
+			file ./worker.php
+			# Reload workers when PHP files change (development only)
+			watch ./**/*.php
+		}
+	}
+}
+```
+
+If your application is based on the [official Yii app template](https://github.com/yiisoft/app), see the [package README](https://github.com/yiisoft/yii-runner-frankenphp) for a complete `worker.php` example with debug, environment, and error handler configuration.
+
+To limit the number of requests a worker handles before being restarted (useful to mitigate memory leaks), set the `MAX_REQUESTS` environment variable. By default, workers handle requests indefinitely.
+
+When using worker mode, make sure stateful services are reset after each request. See the [worker mode documentation](worker.md) and the [Yii DI `StateResetter` documentation](https://github.com/yiisoft/di#resetting-services-state) for details.