Development

.env.example

@@ -1,10 +1,56 @@
+# App
+APP_NAME=SproutPHP
 APP_ENV=local
 APP_DEBUG=true
 APP_URL=http://localhost:9090
+APP_TIMEZONE=UTC
+APP_LOCALE=en
+APP_KEY=your-secret-key-here
+
+# Repo Info For Versioning
 SPROUT_REPO=SproutPHP/framework
 SPROUT_USER_AGENT=sproutphp-app
 
+# Database
+DB_CONNECTION=mysql
 DB_HOST=localhost
+DB_PORT=3306
 DB_NAME=sprout
 DB_USER=root
 DB_PASS=
+
+# Mail
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.mailgun.org
+MAIL_PORT=587
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_ENCRYPTION=tls
+MAIL_FROM_ADDRESS=noreply@sproutphp.com
+MAIL_FROM_NAME=SproutPHP
+
+# Cache
+CACHE_DRIVER=file
+CACHE_PATH=/storage/cache
+
+# Session Configuration
+SESSION_NAME=sprout_session
+SESSION_DRIVER=file
+SESSION_LIFETIME=120
+SESSION_PATH=/storage/sessions
+
+# Storage
+STORAGE_DISK=public
+STORAGE_PUBLIC_ROOT=storage/app/public
+STORAGE_PUBLIC_URL=/storage
+STORAGE_PRIVATE_ROOT=storage/app/private
+
+# Security
+CSRF_ENABLED=true
+XSS_PROTECTION=true
+CORS_ENABLED=false
+
+# View
+VIEW_ENGINE=twig
+TWIG_CACHE=false
+TWIG_DEBUG=true

.gitignore

@@ -58,4 +58,5 @@ composer.lock
 
 # Application specific
 /public/uploads/
-/public/storage/
+/public/storage/
+/docs

CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This project uses [Semantic Versioning](https://semver.org/) beginning with version `v0.1.7-alpha.2` (or `v0.1.7-beta.1`).  
+Earlier releases (`v0.1.0-alpha.1` to `v0.1.7-alpha.1`) were experimental and do not strictly follow SemVer conventions.
+
+---
+
+## [v0.1.7-alpha.3] - 2024-06-13
+
+### Added
+- Storage root is now set to an absolute path by default for reliability (no .env needed)
+- Improved Storage helper documentation and usage
+- Enhanced symlink command for better cross-platform compatibility
+- Updated documentation for new storage system and best practices
+
+### Fixed
+- Prevented duplicate/nested storage paths in uploads
+- General codebase and documentation improvements
+
+---
+
+## [v0.1.7-alpha.2] - 2025-07-15
+
+### Added
+- Storage helper for file uploads, saving to `public/uploads` and generating URLs.
+- Modern file access in controllers: `$request->file('avatar')`, `$request->hasFile('avatar')`.
+- Unified request data: merges `$_GET`, `$_POST`, and JSON body.
+- `mimes` and `image` validation rules for secure file uploads.
+- HTMX-powered file upload with progress bar in the main form (no JS required).
+- Generic error-clearing script for all form fields.
+
+### Changed
+- File uploads are now web-accessible by default.
+- Improved documentation for file upload, validation, and request handling.
+
+### Fixed
+- No more duplicate `/uploads/uploads/...` in file URLs.
+
+---
+
+## Legacy Experimental Releases
+
+These were single-shot development releases with no progressive alpha/beta cycle.
+
+| Version Tag      | Notes                                     |
+| ---------------- | ----------------------------------------- |
+| `v0.1.0-alpha.1` | Initial experimental release              |
+| `v0.1.1-alpha.1` | Feature/bug updates without SemVer phases |
+| `v0.1.2-alpha.1` | Same as above                             |
+| `v0.1.3-alpha.1` | —                                         |
+| `v0.1.4-alpha.1` | —                                         |
+| `v0.1.5-alpha.1` | —                                         |
+| `v0.1.6-alpha.1` | —                                         |
+| `v0.1.7-alpha.1` | Final experimental/unstable release       |
+
+---
+
+**From v0.1.7-alpha.2 onward, all releases will follow a structured, progressive SemVer pre-release cycle.**
+
+## [v0.1.7-beta.1] - 2024-06-09
+
+### Added
+- Dynamic route parameter support (e.g., `/user/{id}`, `/blog/{slug}`) for CRUD and flexible routing
+- Robust CSRF protection via middleware and helpers (works for forms, AJAX, and HTMX)
+- SPA-like file upload and form handling with HTMX (including indicators and grid UI)
+- Secure private file upload/download (no direct links, internal access only)
+- Consistent CSRF token management (single session key, helpers, and middleware)
+
+### Improved
+- UI/UX for validation and file upload forms (two-column grid, spinner, SPA feel)
+- Path resolution for storage (public/private separation, symlink support)
+- Code structure: CSRF logic moved to helpers/middleware, no raw PHP in entry
+
+### Fixed
+- Issues with file download on PHP built-in server (now uses query param for compatibility)
+- Consistency in CSRF token usage across the framework
+
+### Removed
+- Exposed raw CSRF logic from entry point
+
+---

CONFIGURATION.md

@@ -0,0 +1,156 @@
+# SproutPHP Configuration Guide
+
+This document outlines all available configuration options for SproutPHP framework.
+
+## Environment Variables (.env file)
+
+### Application Configuration
+```env
+APP_NAME=SproutPHP
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:9090
+APP_TIMEZONE=UTC
+APP_LOCALE=en
+APP_KEY=your-secret-key-here
+```
+
+### Database Configuration
+```env
+DB_CONNECTION=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_NAME=sprout
+DB_USER=root
+DB_PASS=
+DB_PREFIX=
+```
+
+### Security Configuration
+```env
+# CSRF Protection
+CSRF_ENABLED=true
+CSRF_TOKEN_NAME=_token
+CSRF_EXPIRE=3600
+
+# XSS Protection
+XSS_PROTECTION=true
+XSS_MODE=block  # 'block', 'sanitize', or '0' to disable
+
+# Content Security Policy
+CSP_ENABLED=true
+CSP_REPORT_ONLY=false
+CSP_REPORT_URI=
+
+# CORS
+CORS_ENABLED=false
+CORS_ALLOWED_ORIGINS=*
+CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE
+CORS_ALLOWED_HEADERS=Content-Type,Authorization
+```
+
+### Mail Configuration
+```env
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.mailgun.org
+MAIL_PORT=587
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_ENCRYPTION=tls
+MAIL_FROM_ADDRESS=noreply@sproutphp.com
+MAIL_FROM_NAME=SproutPHP
+```
+
+### Cache Configuration
+```env
+CACHE_DRIVER=file
+CACHE_PATH=/storage/cache
+```
+
+### Session Configuration
+```env
+SESSION_NAME=sprout_session
+SESSION_DRIVER=file
+SESSION_LIFETIME=120
+SESSION_PATH=/storage/sessions
+```
+
+### Logging Configuration
+```env
+LOG_DRIVER=file
+LOG_LEVEL=debug
+LOG_PATH=/storage/logs
+```
+
+### View Configuration
+```env
+VIEW_ENGINE=twig
+TWIG_CACHE=false
+TWIG_DEBUG=true
+TWIG_AUTO_RELOAD=true
+TWIG_STRICT_VARIABLES=false
+```
+
+### Framework Configuration
+```env
+SPROUT_REPO=SproutPHP/framework
+SPROUT_USER_AGENT=sproutphp-app
+```
+
+## Configuration Usage
+
+### In PHP Code
+```php
+// Get app name
+$appName = config('app.name');
+
+// Get database host
+$dbHost = config('database.connections.mysql.host');
+
+// Check if XSS protection is enabled
+$xssEnabled = config('security.xss.enabled');
+
+// Get CSP mode
+$cspMode = config('security.csp.report_only');
+```
+
+### In Twig Templates
+```twig
+{# Get app name #}
+<h1>{{ config('app.name') }}</h1>
+
+{# Check environment #}
+{% if config('app.env') == 'local' %}
+    <div class="debug-info">Development Mode</div>
+{% endif %}
+```
+
+## Security Features
+
+### XSS Protection
+The framework automatically adds XSS protection headers based on your configuration:
+
+- **Development**: Relaxed CSP policy allowing inline styles and external images
+- **Production**: Strict CSP policy for maximum security
+
+### CSRF Protection
+CSRF tokens are automatically generated and validated for state-changing requests (POST, PUT, PATCH, DELETE).
+
+### Content Security Policy
+CSP headers are automatically set based on your environment:
+- **Local/Debug**: Allows `unsafe-inline` for styles and external images
+- **Production**: Strict policy with no unsafe directives
+
+## Environment-Specific Behavior
+
+### Local Environment
+- Debug information displayed
+- Relaxed security policies
+- Detailed error messages
+- HTMX debug indicator
+
+### Production Environment
+- No debug information
+- Strict security policies
+- Generic error pages
+- Optimized performance settings