badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity

Add FastCGI Plugin for PHP-FPM support with examples, tests, and documentation

Browse source 
- 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.
This commit is contained in:
Joao Gilberto Magalhaes 2025-12-01 13:04:32 -05:00
parent a993025718
commit 883521e7e1
12 changed files with 1029 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

151
examples/docker/php-app/README.md Normal file
View file

@ -0,0 +1,151 @@
# 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)

152
examples/docker/php-app/index.php Normal file
View file

@ -0,0 +1,152 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PHP-FPM with EasyHAProxy</title>
<style>
body {
font-family: Arial, sans-serif;
max-width: 800px;
margin: 50px auto;
padding: 20px;
background: #f5f5f5;
}
.container {
background: white;
padding: 30px;
border-radius: 8px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
h1 {
color: #333;
border-bottom: 3px solid #4CAF50;
padding-bottom: 10px;
}
.success {
background: #d4edda;
border: 1px solid #c3e6cb;
color: #155724;
padding: 15px;
border-radius: 4px;
margin: 20px 0;
}
.info-table {
width: 100%;
border-collapse: collapse;
margin: 20px 0;
}
.info-table th,
.info-table td {
padding: 12px;
text-align: left;
border-bottom: 1px solid #ddd;
}
.info-table th {
background: #f8f9fa;
font-weight: bold;
width: 200px;
}
.info-table tr:hover {
background: #f8f9fa;
}
a {
color: #4CAF50;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
code {
background: #f4f4f4;
padding: 2px 6px;
border-radius: 3px;
font-family: 'Courier New', monospace;
}
</style>
</head>
<body>
<div class="container">
<h1>PHP-FPM with EasyHAProxy FastCGI Plugin</h1>
<div class="success">
<strong>Success!</strong> PHP is running via FastCGI protocol through HAProxy.
</div>
<h2>FastCGI Environment</h2>
<table class="info-table">
<tr>
<th>PHP Version</th>
<td><?php echo PHP_VERSION; ?></td>
</tr>
<tr>
<th>Server Software</th>
<td><?php echo $_SERVER['SERVER_SOFTWARE'] ?? 'N/A'; ?></td>
</tr>
<tr>
<th>Document Root</th>
<td><code><?php echo $_SERVER['DOCUMENT_ROOT'] ?? 'N/A'; ?></code></td>
</tr>
<tr>
<th>Script Filename</th>
<td><code><?php echo $_SERVER['SCRIPT_FILENAME'] ?? 'N/A'; ?></code></td>
</tr>
<tr>
<th>Request URI</th>
<td><code><?php echo $_SERVER['REQUEST_URI'] ?? 'N/A'; ?></code></td>
</tr>
<tr>
<th>Request Method</th>
<td><?php echo $_SERVER['REQUEST_METHOD'] ?? 'N/A'; ?></td>
</tr>
<tr>
<th>Server Name</th>
<td><?php echo $_SERVER['SERVER_NAME'] ?? 'N/A'; ?></td>
</tr>
<tr>
<th>Server Port</th>
<td><?php echo $_SERVER['SERVER_PORT'] ?? 'N/A'; ?></td>
</tr>
<tr>
<th>HTTPS</th>
<td><?php echo ($_SERVER['HTTPS'] ?? 'off') === 'on' ? 'Yes' : 'No'; ?></td>
</tr>
<tr>
<th>PATH_INFO</th>
<td><code><?php echo $_SERVER['PATH_INFO'] ?? 'Not set'; ?></code></td>
</tr>
<tr>
<th>Gateway Interface</th>
<td><?php echo $_SERVER['GATEWAY_INTERFACE'] ?? 'N/A'; ?></td>
</tr>
</table>
<h2>Test Links</h2>
<ul>
<li><a href="/info.php">View PHP Info</a></li>
<li><a href="/test-path-info.php/extra/path">Test PATH_INFO support</a></li>
</ul>
<h2>How This Works</h2>
<p>
This setup uses HAProxy with EasyHAProxy to proxy requests to PHP-FPM via the FastCGI protocol:
</p>
<ol>
<li>HAProxy receives HTTP request on port 80</li>
<li>The FastCGI plugin generates an <code>fcgi-app</code> configuration that defines CGI parameters (SCRIPT_FILENAME, DOCUMENT_ROOT, etc.)</li>
<li>HAProxy uses this configuration to communicate with PHP-FPM via the FastCGI protocol</li>
<li>HAProxy connects to PHP-FPM (via TCP port 9000 or Unix socket, depending on configuration)</li>
<li>PHP-FPM processes the PHP script and returns the response</li>
<li>HAProxy sends the response back to the client</li>
</ol>
<h2>Configuration</h2>
<p>The FastCGI plugin is configured in <code>docker-compose-php-fpm.yml</code>:</p>
<ul>
<li><strong>document_root:</strong> <code>/var/www/html</code></li>
<li><strong>index_file:</strong> <code>index.php</code></li>
<li><strong>path_info:</strong> <code>true</code> (enables PATH_INFO support)</li>
</ul>
</div>
</body>
</html>

9
examples/docker/php-app/info.php Normal file
View file

@ -0,0 +1,9 @@
<?php
/**
* PHP Info Page
*
* This page displays comprehensive PHP configuration information
* including FastCGI environment variables set by EasyHAProxy.
*/
phpinfo();

106
examples/docker/php-app/test-path-info.php Normal file
View file

@ -0,0 +1,106 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PATH_INFO Test</title>
<style>
body {
font-family: Arial, sans-serif;
max-width: 800px;
margin: 50px auto;
padding: 20px;
background: #f5f5f5;
}
.container {
background: white;
padding: 30px;
border-radius: 8px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
h1 {
color: #333;
border-bottom: 3px solid #2196F3;
padding-bottom: 10px;
}
.success {
background: #d4edda;
border: 1px solid #c3e6cb;
color: #155724;
padding: 15px;
border-radius: 4px;
margin: 20px 0;
}
.info {
background: #d1ecf1;
border: 1px solid #bee5eb;
color: #0c5460;
padding: 15px;
border-radius: 4px;
margin: 20px 0;
}
code {
background: #f4f4f4;
padding: 2px 6px;
border-radius: 3px;
font-family: 'Courier New', monospace;
}
pre {
background: #f4f4f4;
padding: 15px;
border-radius: 4px;
overflow-x: auto;
}
a {
color: #2196F3;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div class="container">
<h1>PATH_INFO Test</h1>
<?php if (isset($_SERVER['PATH_INFO']) && !empty($_SERVER['PATH_INFO'])): ?>
<div class="success">
<strong>Success!</strong> PATH_INFO is working correctly.
</div>
<h2>PATH_INFO Value</h2>
<pre><?php echo htmlspecialchars($_SERVER['PATH_INFO']); ?></pre>
<h2>Parsed Path Segments</h2>
<pre><?php
$segments = explode('/', trim($_SERVER['PATH_INFO'], '/'));
print_r(array_filter($segments));
?></pre>
<?php else: ?>
<div class="info">
<strong>Note:</strong> PATH_INFO is not set. Try accessing this page with additional path segments.
</div>
<?php endif; ?>
<h2>Request Information</h2>
<pre><?php
echo "SCRIPT_NAME: " . ($_SERVER['SCRIPT_NAME'] ?? 'N/A') . "\n";
echo "REQUEST_URI: " . ($_SERVER['REQUEST_URI'] ?? 'N/A') . "\n";
echo "PATH_INFO: " . ($_SERVER['PATH_INFO'] ?? 'N/A') . "\n";
echo "QUERY_STRING: " . ($_SERVER['QUERY_STRING'] ?? 'N/A') . "\n";
?></pre>
<h2>Example Usage</h2>
<p>PATH_INFO enables RESTful URL routing. Try these URLs:</p>
<ul>
<li><a href="/test-path-info.php/users">/test-path-info.php/users</a></li>
<li><a href="/test-path-info.php/users/123">/test-path-info.php/users/123</a></li>
<li><a href="/test-path-info.php/api/v1/products">/test-path-info.php/api/v1/products</a></li>
</ul>
<p><a href="/">← Back to Home</a></p>
</div>
</body>
</html>