LilaPHP — Lightweight Modern PHP Framework

Production Deployment

LilaPHP is production-ready out of the box. Simply set DEBUG=false and deploy to any server—Nginx, Apache, LAMPP, XAMPP, WAMP, VPS, or shared hosting.

Automatic Optimizations (when DEBUG=false)

OPcache RAM Preloading - Automatically pre-compiles and pins all engine classes (`_core/*.php`) and database models (`app/models/*.php`) into RAM via `app/preload.php`.
APCu In-Memory Caching - Direct RAM caching for API rate limits (`Core\Security`), validation dictionaries, and high-frequency SQL query payloads (`O(1)` zero disk I/O).
Redis Cluster & Background Workers - Dual-tier shared caching across multiple servers with asynchronous non-blocking job queues (`Core\Task`).
Environment Variable OPcache Export - Compiles `.env` directly into an OPcache-ready static array (`_core/cache/env.php`) when running `php cli.php optimize`.
Nginx C-Level Direct Routing & JSON 404 - Direct physical file execution (`app/routes/` and `app/routes/api/`) with native C-level JSON `404` error responses (`@json_404`), eliminating PHP worker startup overhead for invalid routes.

Docker Production Stack Command (`docker prod`)

Before deploying to production, launch your container orchestration using our unified style master command. This command builds and starts `php:8.4-fpm` with `preload.php` active, pinning all core framework classes (`Config`, `Database`, `Cache`, `Response`, `Task`) directly into memory:

Terminal

                # Set web server as owner
sudo chown -R www-data:www-data /var/www/your-project

# Set correct permissions
sudo chmod -R 755 /var/www/your-project

# Build and launch optimized production Docker stack (PHP-FPM + Nginx + MySQL + Redis)
php cli.php docker prod

This automatically ensures:

OPcache RAM Preloading (`auto_prepend_file` & pre-compiled shared memory)
APCu In-Memory variable caching (`CACHE_DRIVER=apcu`)
Redis connection pooling & background queues (`DB_CACHE_DRIVER=redis`)
Disabled logger output by default for high-throughput performance (`LOG_ENABLED=false`)

Security Checklist

Set APP_ENV=production and APP_DEBUG=false in .env at the root directory
Ensure external ports are protected by your firewall/load balancer (Nginx handles rate limits via limit_req zone=api_limit)
Enable HTTPS with SSL certificates (e.g., Let's Encrypt / Certbot in Nginx)
Configure secure database credentials and restrict MySQL (`3306`) from public internet exposure
Verify that background worker daemons (`php cli.php task:work`) run under dedicated non-root users inside your container

🐳 Docker Deployment (Highly Recommended)

LilaPHP features a fully optimized, production-ready Docker Compose environment. We highly recommend using this containerized setup as it pre-installs and tunes OPcache, APCu metadata caching, and optimal PHP-FPM pool settings (e.g., static process manager).

1a. MySQL Stack (Default — Recommended for VPS)

Boots Nginx + PHP 8.4-FPM (OPcache preload active) + MySQL 8 + Redis 7 in isolated containers. Automatically detected when DB_TYPE=mysql is set in .env:

# Production MySQL stack
php cli.php docker prod

# Development MySQL stack
php cli.php docker dev

# Check container status & active ports
php cli.php docker ps

# Stop containers when not needed
php cli.php docker stop

1b. SQLite Standalone Stack (Desktop / Lightweight VPS)

When DB_TYPE=sqlite is set in .env (or after running php cli.php db:switch sqlite), the Docker orchestration automatically uses the SQLite override profile — MySQL container is excluded, only Nginx + PHP-FPM + Redis start:

# Switch to SQLite and launch (auto-detected)
php cli.php db:switch sqlite
php cli.php docker dev    # or: docker prod

# Or use the explicit sqlite alias
php cli.php docker sqlite

# Containers started: nginx, php-fpm, redis (NO mysql)
# SQLite database: app/database/app.sqlite (volume-mounted)

2. Reverse Proxy with Host Nginx (Redirecting port 80/443 to Docker)

By default, `docker-compose.yml` maps your HTTP service to `HTTP_PORT=8080` (configured in `.env`). If you expose your app on standard ports (`80/443`), configure a reverse proxy on your host server's Nginx pointing to `http://127.0.0.1:8080`:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com www.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Alternative: Manual Server Setup Guide (Ubuntu/Debian)

1. PHP 8.4 Installation

Add the official PHP repository and install PHP 8.4 with key modules:

# Add official PHP repository (Ondřej Surý)
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP 8.4 and key modules
sudo apt install -y php8.4-fpm php8.4-mysql php8.4-gd php8.4-opcache \
php8.4-curl php8.4-mbstring php8.4-xml php8.4-zip php8.4-bcmath php8.4-apcu

2. Composer Installation

Install the PHP package manager globally:

# 1. Download the installer
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

# 2. Run the installation and move to system binaries
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# 3. Remove the temporary installer
php -r "unlink('composer-setup.php');"

3. Opcache Configuration

Optimize production performance by enabling Opcache in your php.ini:

# Edit your php.ini (e.g., /etc/php/8.4/fpm/php.ini)
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0

4. APCu RAM Cache Configuration

LilaPHP supports ultra-fast RAM caching using APCu. Enable it in your php.ini (or /etc/php/8.4/mods-available/apcu.ini) to completely bypass disk I/O when reading routing metadata:

apc.enabled=1
apc.enable_cli=1
apc.shm_size=64M

5. PHP-FPM Pool Optimization

Optimize /etc/php/8.4/fpm/pool.d/www.conf process management:

# RAM sizing guide (LilaPHP baseline: ~24MB RSS per worker at idle)
# VPS  512MB  → pm=dynamic,  max_children=8
# VPS  1GB    → pm=dynamic,  max_children=15
# VPS  2GB    → pm=static,   max_children=30
# VPS  4GB    → pm=static,   max_children=60
# Dedicated 8GB+ → pm=static, max_children=100 (peak ~80k RPS)
pm = static
pm.max_children = 30
pm.max_requests = 1000
listen.backlog = 1024

6. Nginx Configuration

Full virtual host configuration with SSL and optimized PHP-FPM support:

              

 
# Rate Limiting Zone (Optional: comment out if conducting high-concurrency benchmarks or load tests)
# limit_req_zone $binary_remote_addr zone=api_limit:10m rate=60r/s;

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com www.your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name your-domain.com www.your-domain.com;

    # ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    # include /etc/letsencrypt/options-ssl-nginx.conf;
    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # ssl_certificate /etc/nginx/ssl/your-domain.com/your-domain.com.crt;
    # ssl_certificate_key /etc/nginx/ssl/your-domain.com/your-domain.com.key;

    root /var/www/your-project/public;
    index index.html index.php;

    location ~ /\.(env|git|htaccess) {
        deny all;
        return 403;
    }

    location / {
        try_files $uri @php;
    }

    location @php {
        include fastcgi_params;
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME /var/www/your-project/app/index.php;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param SCRIPT_NAME /index.php;
        fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/your-project/_core/bootstrap.php";
    }

    location @json_404 {
        default_type application/json;
        return 404 '{"error":"Endpoint not found","code":404}';
    }

    error_page 404 = @json_404;

    location ~ ^/(vendor|composer\.json|composer\.lock|package\.json|package-lock\.json|AGENTS\.md|_core) {
        deny all;
        return 404;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires max;
        log_not_found off;
    }
}

7. Folder Permissions

Ensure the web server has the correct ownership and permissions:

                # Set web server as owner
sudo chown -R www-data:www-data /var/www/your-project

# Set correct permissions
sudo chmod -R 755 /var/www/your-project

Configure Nginx

Project Path Domain PHP Version

Previous: CLI Engine & Doctor Diagnostics 🎉 Tour Complete — Back to Overview