Dev

README.md

@@ -1,29 +1,61 @@
 # WebFiori Documentation
 
-Documentation repository for WebFiori framework. Any change to this repo in the `main` branch is reflected directly to the website at https://webfiori.com/docs. The documentation in this repo covers version 3.x.x of the framework.
+Documentation repository for WebFiori framework. Any change to this repo in the `main` branch is reflected directly to the website at https://webfiori.com/docs.
+
+This repo currently covers **version 3.x** of the framework.
 
 ## Quick Start
 
 - **New to WebFiori?** Start with [Introduction](introduction.md)
 - **Ready to install?** Check [Installation Guide](installation.md)
-- **Browse all topics:** See [Learning Center](https://webfiori.com/docs)
+- **Browse all topics:** See [Index](index.md)
 
 ## Documentation Structure
 
-- **Getting Started**: Introduction, Installation, Folder Structure
-- **Core Features**: Routing, Response handling, Web Services
-- **UI Development**: Web Pages, UI Package, Themes
-- **Data Management**: Database, Sessions, JSON handling
-- **Advanced Features**: Middleware, Background Tasks, Email
+| Section | Topics |
+|---------|--------|
+| Getting Started | Introduction, Installation, Folder Structure, Basic Usage |
+| Core Features | Routing, Response, Web Services, Middleware |
+| UI Development | Web Pages, UI Package, Themes, i18n |
+| Data & Storage | Database, Repository Pattern, Migrations, Sessions, Caching, JSON |
+| File Handling | Uploading Files, Streaming Uploads, Resumable Uploads |
+| Advanced | Background Tasks, Job Queue, Email, Event Dispatcher, DI, Security |
+| Infrastructure | CLI, Health Checks, Logging, Environment Variables |
+
+## Libraries Covered
+
+| Library | Docs |
+|---------|------|
+| `webfiori/framework` | Routing, Middleware, Sessions, CLI commands |
+| `webfiori/database` | Database, Repository, Migrations |
+| `webfiori/http` | Web Services, MVC |
+| `webfiori/file` | File Uploads (standard, streaming, resumable) |
+| `webfiori/cli` | Command Line Interface |
+| `webfiori/jsonx` | JSON handling |
+| `webfiori/ui` | UI Package, Themes, Web Pages |
+| `webfiori/mail` | Sending Emails |
+
+## Versioning
+
+See [VERSIONING.md](VERSIONING.md) for the branching and versioning strategy.
+
+Summary: `main` is always the current version. Old versions are frozen into branches (e.g., `v3`) only when work on the next major begins.
 
 ## Contributing
 
-Found an error or want to improve the documentation? 
 1. Fork this repository
-2. Make your changes
-3. Submit a pull request
+2. Create a branch from `dev`
+3. Make your changes
+4. Submit a pull request to `dev`
+
+Guidelines:
+- Use `> **Since X.Y**` notes for features added in minor releases
+- Use `> **Deprecated since X.Y.**` for deprecated features
+- Keep code examples minimal and runnable
+- Verify class/method names against the actual library source
 
 ## Links
 
 - **Framework**: [WebFiori on GitHub](https://github.com/WebFiori/framework)
 - **Website**: [webfiori.com](https://webfiori.com)
+- **API Docs**: [webfiori.com/docs](https://webfiori.com/docs)

VERSIONING.md

@@ -0,0 +1,102 @@
+# Documentation Versioning Strategy
+
+This document describes how documentation versions are managed in this repository.
+
+## Branch Model
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Always the **current** version's docs. All active work happens here. |
+| `v3`, `v4`, etc. | Frozen snapshots created when the **next** major version's docs begin. |
+
+## Rules
+
+1. **`main` is always current.** Today it's v3. When v4 work starts, it becomes v4.
+2. **Branch only when the next major starts.** Before making breaking v4 changes on `main`, branch `v3` off to freeze it.
+3. **Never branch for minor releases.** v3.1, v3.2 docs all go on `main`. Use `> **Since X.Y**` notes.
+4. **Old branches are mostly frozen.** Only typo fixes and critical corrections.
+5. **Cherry-pick shared fixes.** If a fix applies to both old and current, fix on the old branch and cherry-pick to `main`.
+
+## Timeline
+
+```
+v3.0 ships     v3.1 ships     start v4 work     v4.0 ships     start v5 work
+    │               │               │                │               │
+    │               │          branch v3!            │          branch v4!
+    │               │               │                │               │
+main: ──v3 docs────────────────────│──v4 docs───────────────────────│──v5 docs──→
+                                    │                                │
+v3:                                 ●───hotfixes only───────→       │
+                                                                     │
+v4:                                                                  ●───hotfixes──→
+```
+
+## Scenarios
+
+### New feature in a minor release (e.g., v3.1)
+
+Commit to `main`. Add a version note:
+
+```markdown
+## Connection Pooling
+
+> **Since 3.1**
+
+The library includes a built-in connection pool...
+```
+
+### Starting work on next major (e.g., v4)
+
+```bash
+git checkout main
+git checkout -b v3    # Freeze v3 docs
+git checkout main     # main is now v4 docs
+```
+
+### Fix a doc bug that affects both v3 and v4
+
+```bash
+git checkout v3
+# apply fix
+git commit -m "fix: typo in database.md"
+
+git checkout main
+git cherry-pick <commit-hash>
+```
+
+### Fix something only relevant to an old version
+
+```bash
+git checkout v3
+# fix content that doesn't exist in main
+git commit -m "fix: clarify deprecated syntax in v3"
+# No cherry-pick needed
+```
+
+### Deprecating a feature
+
+```markdown
+> **Deprecated since 3.2.** Use `StreamingUploader` instead. Will be removed in v4.
+```
+
+When v4 docs begin on `main`, delete the deprecated content entirely. It remains in the `v3` branch.
+
+### End of life for an old version
+
+Keep the branch for archival (costs nothing) or delete it. Remove the old version's route from the website if you no longer want to serve it.
+
+## Version Markers
+
+| Situation | Marker |
+|-----------|--------|
+| Feature added in minor | `> **Since 3.1**` |
+| Feature deprecated | `> **Deprecated since 3.2.** Use X instead.` |
+| Feature removed in major | Delete from `main`; stays in old branch |
+| Behavior changed in major | Update on `main`; old text stays in old branch |
+
+## Website Routing
+
+| URL | Source |
+|-----|--------|
+| `webfiori.com/docs` | `main` branch (current version) |
+| `webfiori.com/docs/v3` | `v3` branch (when v4 is current) |

built-in-middleware.md

@@ -116,6 +116,33 @@ new HttpCacheMiddleware([
 
 Best for read-heavy, infrequently-changing endpoints (product catalogs, static configs).
 
+## Response Caching
+
+Full server-side response caching. Stores the complete response (headers, status code, body) and serves it directly on subsequent requests, bypassing all application logic.
+
+```php
+use WebFiori\Framework\Middleware\CacheMiddleware;
+```
+
+Registered name: `cache`. Belongs to the `web` group. Priority: 50.
+
+This middleware works with the route's `cache-duration` option:
+
+```php
+Router::page([
+    RouteOption::PATH => '/products',
+    RouteOption::TO => ProductsPage::class,
+    RouteOption::MIDDLEWARE => ['cache'],
+    RouteOption::CACHE_DURATION => 300  // Cache for 5 minutes
+]);
+```
+
+How it works:
+1. `before()`: Checks if a cached response exists for the current URI. If found, sends it immediately (no further processing).
+2. `after()`: If the response wasn't cached, stores the full response (body, headers, status code) with the configured TTL.
+
+Cache storage uses `FileStorage` by default (stored in the system temp directory). The cache key is derived from the request URI.
+
 ## Session Start
 
 Starts the session. Required by middleware that reads session data (CSRF, auth, rate limiter with session keys).