# PHP Apps

App runtime configuration and vhost provisioning.

Host vars (per app):
```yaml
apps:
  - name: shop                 # required
    type: php                  # required
    domain: "demo.example.com www.demo.example.com"  # required
    user: deploy               # optional, defaults to first in users
    php_version: "8.3"         # required
    subtype: shopware6         # optional
    web_root: /var/www/deploy/shop  # optional
    acme_root: /var/www/letsencrypt  # optional
    cert: letsencrypt          # optional
    letsencrypt_email: admin@example.com  # required if cert=letsencrypt
    database:                  # optional
      name: shop_db
      user: shop_user
    php_fpm:                   # optional
      max_children: 40
      start_servers: 20
      min_spare_servers: 10
      max_spare_servers: 20
      max_requests: 500
    backup_dirs:               # optional — directories to include in file backups
      - /var/www/deploy/shared
    cronjobs:                  # optional
      - name: "Run scheduler"
        job: "php /var/www/shop/artisan schedule:run >> /var/log/shop-cron.log 2>&1"
        schedule: "* * * * *"
```

Defaults:
- `user`: first entry in `users`
- `web_root`: /var/www/<user>/<app.name>
- `acme_root`: /var/www/letsencrypt
- `cert`: unset
- `php_fpm.max_children`: 40
- `php_fpm.start_servers`: 20
- `php_fpm.min_spare_servers`: 10
- `php_fpm.max_spare_servers`: 20
- `php_fpm.max_requests`: 500

Notes:
- `subtype: shopware6` installs Shopware CLI on the server.
- Database user passwords are generated automatically and stored in `/etc/ploy/password.json`.
- `backup_dirs` lists directories to archive as `.tar.gz` during daily file backups. Archives are stored in `/var/www/<appname>/backups/web/` and kept for 3 days locally.

## PHP-FPM Status & Ping

Enable the FPM status and ping endpoints via `php_fpm`:

```yaml
apps:
  - name: shop
    type: php
    php_fpm:
      status_path: /php-fpm-status  # optional, omit to disable
      ping_path: /php-fpm-ping      # optional, omit to disable
```

To expose the endpoints via nginx, add a file like `~/.config/nginx/20status.conf` as the app user:

```nginx
location = /php-fpm-status {
  access_log off;
  allow 127.0.0.1;
  allow 1.2.3.4;        # your monitoring IP (IPv4)
  allow 2001:db8::1;    # your monitoring IP (IPv6)
  deny all;

  include fastcgi_params;

  fastcgi_param SCRIPT_FILENAME /dev/null;
  fastcgi_param SCRIPT_NAME /php-fpm-status;

  fastcgi_pass fastcgi_backend_<appname>;
}

location = /php-fpm-ping {
  access_log off;
  allow 127.0.0.1;
  allow 1.2.3.4;        # your monitoring IP (IPv4)
  allow 2001:db8::1;    # your monitoring IP (IPv6)
  deny all;

  include fastcgi_params;

  fastcgi_param SCRIPT_FILENAME /dev/null;
  fastcgi_param SCRIPT_NAME /php-fpm-ping;

  fastcgi_pass fastcgi_backend_<appname>;
}
```

Replace `<appname>` with the app name as configured in `apps[].name`.