# Environment Configuration Guide

This directory contains environment templates for different deployment environments of the Custom PHP Framework.

## Environment Templates

### `.env.production.template`
Production environment template with security-focused configurations:
- APP_DEBUG=false
- Strict session fingerprinting
- Xdebug disabled
- Production logging levels
- Strong password requirements

### `.env.staging.template` 
Staging environment template for testing:
- APP_DEBUG=true
- Moderate security settings
- Xdebug enabled for debugging
- Verbose logging
- Test API configurations

## Usage

1. **Copy the appropriate template:**
   ```bash
   cp .env.production.template .env.production
   # or
   cp .env.staging.template .env.staging
   ```

2. **Fill in required values:**
   - Replace all `*** REQUIRED ***` placeholders with actual values
   - Generate strong passwords for database credentials
   - Configure API keys and service credentials
   - Set proper domain names and SSL certificate paths

3. **Security Considerations:**
   - Never commit actual `.env.production` or `.env.staging` files to version control
   - Use strong, unique passwords for each environment
   - Rotate credentials regularly
   - Enable appropriate session fingerprinting for security

## Environment-Specific Settings

### Development → Staging Changes
- Enable Xdebug but remove IDE configurations
- Use staging database and credentials
- Enable detailed logging for debugging
- Use test API endpoints where available

### Staging → Production Changes
- Disable all debug features (APP_DEBUG=false, XDEBUG_MODE=off)
- Enable strict security settings
- Use production database with strong credentials
- Set warning-level logging only
- Configure production SSL certificates
- Use production API keys and webhooks

## Required Values by Environment

### Production Requirements
- **Database:** Strong passwords, production database name
- **APIs:** Production webhook secrets, SMTP credentials
- **SSL:** Valid SSL certificate paths
- **Monitoring:** Production-grade logging configuration

### Staging Requirements  
- **Database:** Separate staging database credentials
- **APIs:** Test/staging API keys where available
- **SSL:** Test certificates or self-signed certificates
- **Monitoring:** Verbose logging for debugging

## Environment Variable Categories

### Core Application
- `APP_ENV`, `APP_DEBUG`, `APP_URL`, `APP_DOMAIN`

### Database Configuration
- `DB_HOST`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `DB_ROOT_PASSWORD`

### Security & Session
- Session fingerprinting settings
- SSL certificate paths
- Authentication configurations

### External Services
- SMTP configuration for emails
- Third-party API credentials
- Webhook secrets

### Performance & Caching
- OPcache settings
- Redis configuration
- Worker process limits

### Monitoring & Logging
- Log levels and channels
- Error reporting settings
- Analytics configuration

## Deployment Integration

These environment files are used by:
- Docker Compose overlays (`docker-compose.production.yml`, `docker-compose.staging.yml`)
- Ansible deployment playbooks
- Application deployment scripts

## Security Best Practices

1. **Credential Management:**
   - Use strong, unique passwords for each environment
   - Consider using a password manager or secrets management service
   - Rotate credentials regularly

2. **Environment Isolation:**
   - Keep staging and production completely separate
   - Use different database servers and API keys
   - Monitor access to production credentials

3. **File Permissions:**
   - Set restrictive permissions on environment files (600)
   - Ensure only necessary users can read the files
   - Never include in version control

4. **SSL/TLS Configuration:**
   - Use valid SSL certificates in production
   - Enable HTTPS everywhere
   - Configure proper cipher suites

## Troubleshooting

### Common Issues
- **Missing required values:** Check for `*** REQUIRED ***` placeholders
- **Database connection failures:** Verify database credentials and host
- **SSL certificate errors:** Check certificate paths and permissions
- **API failures:** Verify API keys and endpoint configurations

### Environment-Specific Debugging
- **Staging:** Enable verbose logging and Xdebug
- **Production:** Check application logs and monitoring systems
- **Both:** Verify environment variable loading in application

## Integration with Deployment

The environment templates integrate with:
1. **Docker Compose overlays** for environment-specific container configuration
2. **Ansible playbooks** for automated environment setup
3. **Application deployment scripts** for environment validation and deployment