SemapForm/php/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:

   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:

  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:

  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

Troubleshooting

Emails not sending

1. Check MAIL_ENABLED is set to true
2. Verify SMTP credentials are correct
3. Check server error logs: tail -f /var/log/apache2/error.log
4. 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:

   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:

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.