# Posterg: PHP vs Flask Analysis

## Current Architecture Summary

- **Stack**: Vanilla PHP (no framework), SQLite, nginx + php-fpm
- **Codebase**: ~9,100 lines across 48 PHP files
- **Structure**: File-based routing (`public/` = webroot), shared templates via `include`, singleton `Database` class (1,294 lines), custom auth, rate limiting, media proxy
- **Pages**: 8 public pages, 17 admin pages (11 views + 7 action handlers)
- **Templating**: Raw PHP includes with variable scoping (`$isAdmin`, `$bodyClass`, `$extraCss`, etc.)
- **Database**: SQLite via PDO, WAL mode, 13 tables, 2 views, 6 junction tables

---

## Templating

### Current PHP Pain Points

1. **No template inheritance.** Every page manually sets variables (`$pageTitle`, `$bodyClass`, `$extraCss`, `$ogTags`, `$isAdmin`) then `include`s `head.php`, `header.php`, and `footer.php` in sequence. The head template uses conditionals to branch between admin/public modes — functional but brittle.

2. **Variable scoping is implicit.** Templates read variables from the caller's scope. There's no contract — if `$availableYears` isn't set before `footer.php` is included, it silently renders nothing. Flask's Jinja2 would make this explicit via `render_template('page.html', years=years)`.

3. **No block/slot system.** The admin footer injects `$extraJs` / `$extraJsInline` via loose conventions. In Jinja2, `{% block scripts %}` handles this cleanly with override semantics.

4. **Repeated boilerplate.** Every page repeats the same 5-line preamble: require bootstrap, require Database, set template vars, include head, include header. A Flask `@app.route` + `render_template` collapses this to ~3 lines.

5. **HTML mixed with logic.** Files like `search.php` (220 lines) interleave DB queries, input validation, pagination math, OG tag construction, and HTML rendering in a single file. Flask naturally separates route handlers from templates.

### What Flask/Jinja2 Would Improve

- **Template inheritance**: One `base.html` with `{% block content %}`, `{% block head_extra %}`, `{% block scripts %}`. Admin extends `admin_base.html` which extends `base.html`.
- **Macros**: The card rendering loop, pagination nav, and filter dropdowns are all repeated patterns that become `{% macro card(item) %}`.
- **Auto-escaping**: Jinja2 escapes by default. The current code manually calls `htmlspecialchars()` ~150 times across the project. One missed call = XSS.
- **Explicit context**: `render_template('tfe.html', thesis=data, files=files)` is self-documenting. The current `$data` / `$thesis` / `$item` naming is inconsistent across pages.

### What Flask Would NOT Improve

- The templates themselves would be roughly the same size — HTML is HTML.
- The OG tag logic in `head.php` is already centralized; Jinja2 wouldn't simplify the conditional logic, just change its syntax.

---

## Routing & Code Organization

### Current State

File-based routing via nginx → `public/*.php`. Each file is a standalone entry point:
```
public/index.php      → home page
public/search.php     → search/repertoire
public/tfe.php        → thesis detail
public/admin/edit.php → edit form (GET)
public/admin/actions/edit.php → edit handler (POST)
```

This is simple and transparent — the URL *is* the file path. But it means:
- No centralized middleware (auth, CSRF, rate limiting are manually required per-file)
- No URL generation (hardcoded `href="/admin/edit.php?id=..."` everywhere)
- POST handlers are separate files that redirect back, duplicating auth/CSRF boilerplate

### Flask Equivalent

```python
@app.route('/admin/edit/<int:id>', methods=['GET', 'POST'])
@login_required
def admin_edit(id):
    if request.method == 'POST':
        ...
        return redirect(url_for('admin_edit', id=id))
    return render_template('admin/edit.html', thesis=thesis)
```

- `@login_required` replaces 7 identical `AdminAuth::requireLogin()` calls + 7 identical CSRF checks
- `url_for()` replaces ~50 hardcoded URL strings
- GET/POST in one function eliminates the `actions/` directory pattern

---

## Performance

### Where PHP Already Wins

1. **Process-per-request model with OPcache.** PHP-FPM with OPcache compiles PHP to bytecode once, then serves each request from shared memory. There is no framework initialization overhead because *there is no framework*. Each request loads only the files it needs.

2. **SQLite + WAL mode.** The database is local, on-disk, zero-network-hop. The `PRAGMA` settings (WAL, 8MB cache, synchronous=NORMAL) are well-tuned. This is identical regardless of language.

3. **Low memory footprint.** Each PHP-FPM worker uses ~10-20MB. A Flask process (gunicorn worker) with SQLAlchemy loaded uses ~30-50MB.

4. **No ORM overhead.** Raw PDO queries with manual bindings are as fast as it gets for SQLite. Flask would likely introduce SQLAlchemy, adding per-query overhead (object hydration, identity map, unit of work tracking).

5. **Static file serving by nginx.** CSS/JS/fonts are served directly by nginx, never touching PHP. This is identical with Flask behind nginx.

### Where Flask Would Be Comparable

| Aspect | PHP (current) | Flask |
|--------|--------------|-------|
| Cold start | ~5ms (OPcache hit) | ~50-100ms (Python import) |
| Warm request | ~2-5ms | ~3-8ms |
| SQLite query | Same PDO overhead | Same sqlite3/aiosqlite |
| Template render | PHP native | Jinja2 compiled (comparable) |
| Concurrency | php-fpm pool (sync) | gunicorn workers (sync) |

### Where Flask Would Be Worse

1. **Python is slower for raw computation.** Not relevant here — the bottleneck is SQLite I/O, not CPU.

2. **No equivalent to OPcache.** Python caches `.pyc` bytecode files, but Jinja2 templates must be compiled at startup or on first access. PHP OPcache stores compiled opcodes in shared memory — inherently faster for the "compile once, serve many" pattern.

3. **GIL.** Python's GIL limits true parallelism per process. PHP-FPM workers are independent processes with no shared lock. For a database-bound app this is irrelevant, but under high concurrency PHP-FPM scales more linearly.

4. **Memory per worker.** Flask + dependencies (Werkzeug, Jinja2, click, itsdangerous, markupsafe, plus any ORM) consumes more baseline memory than a PHP-FPM worker running vanilla PHP.

### Where Flask Would Be Better (Performance)

1. **Application-level caching.** Flask can hold objects in memory across requests (e.g., cached orientation lists, available years). PHP re-queries these on every request because it shares nothing between requests by default. However, PHP can use APCu for this — it's just not implemented here.

2. **Connection pooling.** Flask can maintain a persistent SQLite connection per worker. PHP opens a new PDO connection per request (the singleton is per-request, not per-process). For SQLite this overhead is minimal (~0.1ms), but it exists.

### Verdict: Performance

**PHP wins marginally for this specific workload.** The app is a low-traffic academic catalogue with SQLite. The differences are in the single-digit millisecond range and completely irrelevant at the expected scale (likely <100 requests/minute). Neither choice would ever be the bottleneck — the network round-trip to the user dwarfs everything.

---

## Developer Experience & Maintainability

### Where Flask Would Be Clearly Better

1. **Dependency management.** `pip install flask` + `requirements.txt` (or `pyproject.toml`). Currently there are zero external PHP dependencies — which sounds like a feature until you realize the project vendors `Parsedown.php` (2,000 lines of Markdown parsing) instead of using Composer.

2. **Form handling.** Flask-WTF provides declarative form classes with validation, CSRF built-in, and type coercion. The current code manually validates ~15 fields per form with inconsistent approaches (`filter_var`, `intval`, `trim`, `sanitize_string`).

3. **Testing.** Flask has a built-in test client (`app.test_client()`) that can simulate full request/response cycles. The current test suite uses a custom `run-tests.php` harness — functional but non-standard.

4. **Error handling.** Flask has `@app.errorhandler(404)`, `@app.errorhandler(500)`. The current code uses scattered `die()` calls and inconsistent error responses.

5. **Session management.** Flask-Login provides remember-me, session expiry, next-URL redirect after login. `AdminAuth.php` reimplements a subset of this in 121 lines.

### Where PHP Is Adequate or Better for This Project

1. **Zero build step.** Edit a `.php` file, refresh browser. No `flask run`, no virtual environment, no `pip install`. The `php -S localhost:8000` dev server with live-reload is already configured.

2. **Deployment simplicity.** rsync files to server, done. No virtualenv, no systemd unit for gunicorn, no WSGI/ASGI configuration. PHP-FPM is already running on the server.

3. **Hosting availability.** Any shared host runs PHP. Flask requires a VPS or PaaS with Python support. However, this project already uses a dedicated server with nginx, so this is moot.

4. **Team knowledge.** If the maintainers know PHP, rewriting in Python is a net negative regardless of technical merit.

---

## Migration Effort

Rewriting this project in Flask would require:

| Component | Effort |
|-----------|--------|
| Database layer (`Database.php` → SQLAlchemy or raw sqlite3) | 2-3 days |
| 8 public routes + templates | 2 days |
| 17 admin routes + templates | 3-4 days |
| Auth system (Flask-Login) | 0.5 days |
| File upload/media serving | 1 day |
| Rate limiting (Flask-Limiter) | 0.5 days |
| nginx config adaptation | 0.5 days |
| Testing | 1-2 days |
| **Total** | **~10-14 days** |

---

## Conclusion

**Flask would have been a better starting point** for this project — primarily for templating (Jinja2 inheritance eliminates the fragile variable-scoping pattern), routing (decorators + middleware replace per-file boilerplate), and developer ergonomics (form validation, auto-escaping, test client).

**Flask would not deliver better performance.** The current vanilla PHP stack is actually *slightly faster* for this workload due to OPcache efficiency and the absence of framework overhead. The difference is immaterial at this scale.

**A rewrite is not justified.** The project works, the architecture is coherent (if verbose), and the codebase is small enough (~9K lines) to maintain. The practical improvements Flask would bring (cleaner templates, less boilerplate, better form handling) don't outweigh the cost of a full rewrite plus the operational change from PHP-FPM to gunicorn.

**If starting fresh today:** Flask (or even Litestar/FastAPI with Jinja2) would be the stronger choice for a SQLite-backed catalogue app of this size. The Jinja2 templating alone would save ~20% of the current codebase.
