Documentation Index
Fetch the complete documentation index at: https://mintlify.com/MonishAMPT/fastroute-code/llms.txt
Use this file to discover all available pages before exploring further.
Overview
FastRoute requires Nginx configuration to route all requests through index.php. Unlike Apache, Nginx does not support .htaccess files, so all routing configuration must be done in the server block configuration.
Prerequisites
- Nginx web server installed
- PHP-FPM installed and configured
- Access to Nginx configuration files
Configuration Steps
Locate Configuration File
Nginx configurations are typically located in:
/etc/nginx/sites-available/default (Debian/Ubuntu)/etc/nginx/conf.d/default.conf (CentOS/RHEL)/etc/nginx/nginx.conf (main configuration)
Open your site configuration file:sudo nano /etc/nginx/sites-available/default
Configure Server Block
Add or modify your server block with the following configuration:server {
listen 80;
server_name example.com;
root /var/www/html;
index index.php index.html;
# Logging
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
# Main location block for FastRoute
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# PHP-FPM configuration
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
# Deny access to hidden files
location ~ /\. {
deny all;
}
}
Test Configuration
Before restarting Nginx, test the configuration for syntax errors:You should see:nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Restart Nginx
Apply the configuration changes:sudo systemctl restart nginx
sudo systemctl reload nginx
Verify PHP-FPM
Ensure PHP-FPM is running:sudo systemctl status php8.1-fpm
sudo systemctl start php8.1-fpm
sudo systemctl enable php8.1-fpm
Configuration for Subdirectory Installation
If your FastRoute application is installed in a subdirectory (e.g., /apitest), use this configuration:
server {
listen 80;
server_name example.com;
root /var/www/html;
index index.php;
# FastRoute in subdirectory
location /apitest {
try_files $uri $uri/ /apitest/index.php?$query_string;
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
# Deny access to hidden files
location ~ /\. {
deny all;
}
}
Understanding the Configuration
try_files Directive
try_files $uri $uri/ /index.php?$query_string;
$uri - Checks if the requested file exists (e.g., CSS, JS, images)$uri/ - Checks if the requested directory exists/index.php?$query_string - If neither exists, route to FastRoute dispatcher
This ensures static files are served directly while dynamic routes are handled by PHP.
PHP Processing Block
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ \.php$ - Matches all PHP filesfastcgi_pass - Forwards PHP requests to PHP-FPM (adjust socket path for your PHP version)SCRIPT_FILENAME - Ensures the correct file path is passed to PHP
The PHP-FPM socket path varies by PHP version. Common paths:
- PHP 8.1:
/var/run/php/php8.1-fpm.sock
- PHP 8.0:
/var/run/php/php8.0-fpm.sock
- PHP 7.4:
/var/run/php/php7.4-fpm.sock
Adjust the fastcgi_pass directive to match your installed PHP version. Advanced Configuration
Enable HTTPS
server {
listen 443 ssl http2;
server_name example.com;
root /var/www/html;
index index.php;
ssl_certificate /etc/ssl/certs/example.com.crt;
ssl_certificate_key /etc/ssl/private/example.com.key;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
# Redirect HTTP to HTTPS
server {
listen 80;
server_name example.com;
return 301 https://$server_name$request_uri;
}
Enable Gzip Compression
server {
# ... other configuration ...
# Gzip compression
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml text/javascript
application/json application/javascript application/xml+rss
application/rss+xml font/truetype font/opentype
application/vnd.ms-fontobject image/svg+xml;
}
Static File Caching
server {
# ... other configuration ...
# Cache static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
Common Issues
502 Bad Gateway
This usually indicates PHP-FPM is not running or the socket path is incorrect:
- Check PHP-FPM status:
sudo systemctl status php8.1-fpm
- Verify socket path exists:
ls -la /var/run/php/
- Check Nginx error log:
sudo tail -f /var/log/nginx/error.log
404 Errors on Routes
If routes return 404:
- Verify
try_files directive is correct
- Check
root directive points to correct path
- Ensure
index.php exists in the document root
- Review error logs for clues
Permission Denied
Set proper permissions for your application:
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
File Not Found in Logs
If you see “File not found” in PHP-FPM logs:
- Verify
SCRIPT_FILENAME parameter is set correctly
- Check
root directive matches your application path
- Ensure PHP-FPM has read permissions
Testing Your Configuration
After configuration, test with curl:
# Test a route
curl http://localhost/api/test
# Test with subdirectory
curl http://localhost/apitest/api/test
# Check response headers
curl -I http://localhost/api/test
index.php.
Always use sudo nginx -t before restarting Nginx to catch configuration errors. An invalid configuration can prevent Nginx from starting.