883521e7e1
- Introduced `FastcgiPlugin` for automatic HAProxy `fcgi-app` configuration generation. - Added example Docker Compose setup for PHP-FPM with FastCGI. - Updated documentation with detailed examples and usage instructions for FastCGI. - Included test cases to validate plugin behavior and generated configurations. - Enhanced `easymapping` to support `fcgi-app` definitions in global configs.
151 lines
4.5 KiB
Markdown
151 lines
4.5 KiB
Markdown
# Sample PHP Application for FastCGI Plugin
|
|
|
|
This directory contains a sample PHP application that demonstrates the FastCGI plugin functionality with EasyHAProxy.
|
|
|
|
## Files
|
|
|
|
### index.php
|
|
The main page that displays:
|
|
- PHP version and configuration
|
|
- FastCGI environment variables set by EasyHAProxy
|
|
- How the FastCGI plugin works
|
|
- Links to test pages
|
|
|
|
Access: `http://phpapp.local/`
|
|
|
|
### info.php
|
|
Standard `phpinfo()` page showing complete PHP configuration.
|
|
|
|
Access: `http://phpapp.local/info.php`
|
|
|
|
### test-path-info.php
|
|
Demonstrates PATH_INFO support for RESTful URL routing.
|
|
|
|
Examples:
|
|
- `http://phpapp.local/test-path-info.php/users`
|
|
- `http://phpapp.local/test-path-info.php/users/123`
|
|
- `http://phpapp.local/test-path-info.php/api/v1/products`
|
|
|
|
## FastCGI Environment Variables
|
|
|
|
The FastCGI plugin generates an `fcgi-app` configuration that defines these CGI parameters for HAProxy to use:
|
|
|
|
| Variable | Description | Example |
|
|
|----------|-------------|---------|
|
|
| `SCRIPT_FILENAME` | Full path to PHP script | `/var/www/html/index.php` |
|
|
| `DOCUMENT_ROOT` | Document root directory | `/var/www/html` |
|
|
| `SCRIPT_NAME` | Script path | `/index.php` |
|
|
| `REQUEST_URI` | Full request URI with query | `/index.php?page=1` |
|
|
| `QUERY_STRING` | Query string parameters | `page=1&limit=10` |
|
|
| `REQUEST_METHOD` | HTTP method | `GET`, `POST`, etc. |
|
|
| `CONTENT_TYPE` | Request content type | `application/json` |
|
|
| `CONTENT_LENGTH` | Request body length | `1024` |
|
|
| `SERVER_NAME` | Virtual host name | `phpapp.local` |
|
|
| `SERVER_PORT` | Server port | `80` or `443` |
|
|
| `HTTPS` | SSL status | `on` or `off` |
|
|
| `PATH_INFO` | Extra path info (optional) | `/users/123` |
|
|
|
|
## How It Works
|
|
|
|
1. **FastCGI plugin generates configuration** (at startup)
|
|
- Creates an `fcgi-app` section with CGI parameter definitions
|
|
- Includes `docroot`, `index`, and `path-info` settings
|
|
- Adds `use-fcgi-app` directive to the backend
|
|
|
|
2. **Request arrives at HAProxy** (port 80)
|
|
- URL: `http://phpapp.local/index.php`
|
|
|
|
3. **HAProxy uses the fcgi-app configuration**
|
|
- Sets `SCRIPT_FILENAME` to `/var/www/html/index.php`
|
|
- Sets `DOCUMENT_ROOT` to `/var/www/html`
|
|
- Sets all other CGI variables based on the request
|
|
- Handles directory requests (appends `index.php`)
|
|
|
|
4. **HAProxy forwards to PHP-FPM** via FastCGI protocol
|
|
- Host: `php-fpm` (container name)
|
|
- Port: `9000` (TCP) or Unix socket
|
|
- Protocol: `fcgi`
|
|
- Sends CGI parameters in FastCGI format
|
|
|
|
5. **PHP-FPM executes the script**
|
|
- Reads the PHP file from `SCRIPT_FILENAME`
|
|
- Processes the PHP code with CGI environment
|
|
- Returns HTML/JSON response
|
|
|
|
6. **HAProxy sends response to client**
|
|
|
|
## Customizing
|
|
|
|
You can customize the FastCGI plugin configuration in `docker-compose-php-fpm.yml`:
|
|
|
|
```yaml
|
|
labels:
|
|
# Change document root
|
|
easyhaproxy.http.plugin.fastcgi.document_root: /var/www/public
|
|
|
|
# Change default index file
|
|
easyhaproxy.http.plugin.fastcgi.index_file: app.php
|
|
|
|
# Disable PATH_INFO
|
|
easyhaproxy.http.plugin.fastcgi.path_info: "false"
|
|
|
|
# Add custom FastCGI parameters
|
|
easyhaproxy.http.plugin.fastcgi.custom_params: '{"PHP_VALUE":"memory_limit=256M","APP_ENV":"production"}'
|
|
```
|
|
|
|
## Adding Your Own PHP Application
|
|
|
|
Replace the contents of this directory with your own PHP application:
|
|
|
|
```bash
|
|
# Remove sample files
|
|
rm -rf php-app/*
|
|
|
|
# Copy your PHP application
|
|
cp -r /path/to/your/app/* php-app/
|
|
|
|
# Restart the stack
|
|
docker compose -f docker-compose-php-fpm.yml restart
|
|
```
|
|
|
|
Make sure your application's entry point matches the `index_file` configuration (default: `index.php`).
|
|
|
|
## Troubleshooting
|
|
|
|
### "File not found" error
|
|
|
|
Check that:
|
|
1. The file exists in the `php-app/` directory
|
|
2. The `document_root` matches the container path (`/var/www/html`)
|
|
3. The volume mount is correct in docker-compose.yml
|
|
|
|
### PATH_INFO not working
|
|
|
|
Ensure `path_info` is enabled in the plugin configuration:
|
|
```yaml
|
|
easyhaproxy.http.plugin.fastcgi.path_info: "true"
|
|
```
|
|
|
|
### PHP-FPM connection error
|
|
|
|
Verify:
|
|
1. The `localport: 9000` is set correctly
|
|
2. The `proto: fcgi` parameter is set
|
|
3. Both containers are running and can communicate
|
|
|
|
View logs:
|
|
```bash
|
|
docker compose -f docker-compose-php-fpm.yml logs php-fpm
|
|
docker compose -f docker-compose-php-fpm.yml logs haproxy
|
|
```
|
|
|
|
Check connectivity:
|
|
```bash
|
|
docker compose -f docker-compose-php-fpm.yml exec haproxy ping php-fpm
|
|
```
|
|
|
|
## Learn More
|
|
|
|
- [FastCGI Plugin Documentation](../../../docs/plugins.md#fastcgi-plugin)
|
|
- [Container Labels Reference](../../../docs/container-labels.md)
|
|
- [HAProxy FastCGI Documentation](https://docs.haproxy.org/2.8/configuration.html#5.2-proto)
|