PHPSemapForm/README.md

# PHP Deployment Guide for SemapForm

## Requirements

- PHP 7.4 or higher (PHP 8+ recommended)
- PHP extensions:
  - `dom` (for XML generation)
  - `mbstring` (for string handling)
  - `openssl` (for SMTP if using SSL/TLS)
- Web server (Apache, Nginx, or any PHP-capable server)
- Optional: PHPMailer library for advanced SMTP support

## Installation Steps

1. **Upload files to your PHP server:**
   ```
   php/
   ├── index.php
   ├── semesterapparat.php
   ├── submit_semesterapparat.php
   ├── config.php
   ├── functions.php
   ├── .htaccess (if using Apache)
   └── static/
       └── styles.css
   ```

2. **Configure email settings:**
   
   Edit `config.php` or set environment variables:
   - `MAIL_ENABLED`: Set to `true` to enable email sending
   - `SMTP_HOST`: Your SMTP server (e.g., smtp.ph-freiburg.de)
   - `SMTP_PORT`: SMTP port (465 for SSL, 587 for TLS, 25 for plain)
   - `SMTP_USERNAME`: Your SMTP username
   - `SMTP_PASSWORD`: Your SMTP password
   - `MAIL_FROM`: Sender email address
   - `MAIL_TO`: Recipient email address

3. **Set permissions:**
   ```bash
   chmod 755 *.php
   chmod 644 config.php
   chmod 644 static/styles.css
   ```

4. **Test the installation:**
   - Navigate to your server URL (e.g., `https://yourserver.com/php/`)
   - Try submitting a test form
   - Check email delivery or server logs

## Email Configuration Options

### Option 1: PHP's built-in mail() function
- Simplest setup
- Requires server to have mail transfer agent (MTA) configured
- No additional configuration needed in PHP

### Option 2: SMTP with PHP's native functions
- Configure SMTP settings in `config.php`
- Works with basic authentication
- Current implementation in `functions.php`

### Option 3: PHPMailer (Recommended for production)
- Install PHPMailer via Composer:
  ```bash
  composer require phpmailer/phpmailer
  ```
- Better error handling and SMTP support
- Already integrated in `functions.php` (will auto-detect if available)

## Server-Specific Notes

### Apache
- The `.htaccess` file is included for URL rewriting and security
- Ensure `mod_rewrite` is enabled

### Nginx
- Add this to your nginx.conf:
  ```nginx
  location /php {
      index index.php;
      try_files $uri $uri/ /index.php?$query_string;
      
      location ~ \.php$ {
          fastcgi_pass unix:/var/run/php/php-fpm.sock;
          fastcgi_index index.php;
          include fastcgi_params;
      }
  }
  ```

### Shared Hosting
- Most shared hosts have PHP and mail() pre-configured
- Upload files via FTP/SFTP
- Set environment variables through hosting control panel
- Test mail() function first before adding SMTP

## Email Logging

The application now includes comprehensive email logging:

- **Log Location**: `php/mail.log`
- **Log Format**: `[YYYY-MM-DD HH:MM:SS] [LEVEL] Message`
- **Configuration**: 
  - Set `LOG_ENABLED = true` in `config.php` to enable logging
  - Logs are also written to PHP error_log with `[MAIL]` prefix

### What Gets Logged

- Email send attempts with from/to/subject
- Email content length
- SMTP connection details (host, port, encryption)
- PHPMailer initialization and configuration steps
- Success/failure status for each send attempt
- Detailed error messages for failed sends
- When mail is disabled (includes full XML content)

### Viewing Logs

```bash
# View recent log entries
tail -f php/mail.log

# View last 50 lines
tail -n 50 php/mail.log

# Search for errors
grep ERROR php/mail.log

# Search for successful sends
grep SUCCESS php/mail.log
```

### Log File Management

The log file is automatically created when needed. To rotate logs:

```bash
# Manual rotation
mv php/mail.log php/mail.log.$(date +%Y%m%d)
touch php/mail.log
chmod 666 php/mail.log
```

## Troubleshooting

### Emails not sending
1. Check `MAIL_ENABLED` is set to `true`
2. **Check `php/mail.log`** for detailed error messages
3. Verify SMTP credentials are correct
4. Check server error logs: `tail -f /var/log/apache2/error.log`
5. Test with `MAIL_ENABLED=false` to see XML output in logs

### Form validation errors
- Ensure all required fields have values
- Check email format validation
- Verify POST data is being received

### Permission errors
- Ensure PHP has read access to all files
- Check web server user/group permissions

## Security Recommendations

1. **Move config.php outside web root** if possible
2. **Use environment variables** for sensitive data
3. **Enable HTTPS** for form submissions
4. **Sanitize all inputs** (already implemented in `functions.php`)
5. **Set production error reporting** in `config.php`:
   ```php
   error_reporting(0);
   ini_set('display_errors', 0);
   ```
6. **Regular updates**: Keep PHP and server software updated

## Migrating from Docker/Python

The PHP version maintains feature parity with the Python/FastAPI version:
- ✅ Same form fields and validation
- ✅ XML generation with identical structure
- ✅ Email sending with SMTP support
- ✅ Same CSS and frontend behavior
- ✅ Theme toggle functionality
- ✅ Multi-book/media support
- ✅ Optional fields (title, signature, Dauerapparat)

## Environment Variables

You can set these as server environment variables instead of editing `config.php`:

```bash
export MAIL_ENABLED=true
export SMTP_HOST=smtp.ph-freiburg.de
export SMTP_PORT=465
export MAIL_USERNAME=your_username
export MAIL_PASSWORD=your_password
export MAIL_FROM=alexander.kirchner@ph-freiburg.de
export MAIL_TO=semesterapparate@ph-freiburg.de
```

## Support

For issues specific to your hosting environment, consult your hosting provider's PHP documentation.