xamxam/docs/development.md

Development Guide

Setup, workflow, testing, and live reload for Post-ERG development.

---

Quick Start

just setup     # One time: clone php-live-reload + setup directories
just serve     # Start dev server at http://localhost:8000

One unified server serves both:

• Public site: http://localhost:8000
• Admin panel: http://localhost:8000/admin/

Live reload is enabled automatically — browser refreshes when you save files.

---

Project Structure

posterg-website/
├── public/              # DocumentRoot (web-accessible)
│   ├── index.php        # Homepage
│   ├── search.php       # Search/répertoire
│   ├── memoire.php      # Thesis detail
│   ├── admin/           # Admin panel
│   └── assets/          # CSS, fonts, images
├── includes/            # Template partials (header, footer)
├── config/              # Configuration (bootstrap.php)
├── src/                 # PHP classes (Database, AdminAuth, RateLimit)
├── storage/             # Database + uploads (private)
├── database/            # Schema + migrations
├── tests/               # Test suite
├── nginx/               # Server configuration
├── scripts/             # Deployment/admin scripts
└── vendor/              # Third-party (gitignored, dev only)

---

Development Workflow

Starting Development

just serve

Making Changes

1. Edit PHP/CSS files — browser auto-refreshes
2. Run tests: just test
3. Check syntax: just syntax
4. Deploy: just deploy

Database Operations

just stats           # View database stats
just query           # Open SQLite shell
just show 42         # Show thesis by ID
just reset-db        # Reset database
just fixtures        # Create sample data
just backup          # Backup database

---

Live Reload

What It Does

Automatically refreshes your browser when you save PHP/CSS/JS files. No browser extension needed.

Setup (One Time)

just setup

Clones php-live-reload into vendor/ (gitignored).

How It Works

• Conditionally included in header.php when php_sapi_name() === 'cli-server'
• JavaScript polls server for file changes → browser refreshes
• Never active in production (different SAPI, vendor/ not deployed)

Detection

<?php if (php_sapi_name() === 'cli-server'): ?>
<script src="/vendor/php-live-reload/php-live-reload/live-reload.js"></script>
<?php endif; ?>

Troubleshooting

ls -la vendor/php-live-reload/     # Check installed
just setup                          # Reinstall if missing
curl -s http://localhost:8000/ | grep live-reload   # Verify script included

---

Testing

Test Structure

tests/
├── run-tests.php           # Main test runner
├── Unit/                   # Unit tests
│   ├── DatabaseTest.php
│   └── RateLimitTest.php
├── Integration/            # Integration tests
│   └── SearchTest.php
└── Security/               # Security tests
    └── SecurityTest.php

Running Tests

just test              # Run all tests
just test-unit         # Unit tests only
just test-integration  # Integration tests only
just test-security     # Security tests only
just syntax            # Check PHP syntax

Writing Tests

1. Choose type: Unit / Integration / Security
2. Create test file in appropriate tests/ subdirectory
3. Follow template:

<?php
require_once __DIR__ . '/../../src/Database.php';

echo "Test Name\n";
echo "=========\n\n";

try {
    $db = Database::getInstance();
    echo "✓ PASS: Test description\n";
    return true;
} catch (Exception $e) {
    echo "❌ FAIL: " . $e->getMessage() . "\n";
    return false;
}

4. Add to tests/run-tests.php $testFiles array
5. Run: just test

---

Common Tasks

Create a New Page

<?php
require_once __DIR__ . '/../config/bootstrap.php';
require_once APP_ROOT . '/src/Database.php';
$db = App::boot();
include APP_ROOT . '/includes/header.php';
?>
<section class="section">
  <div class="container">
    <h1 class="title">New Page</h1>
  </div>
</section>
<?php include APP_ROOT . '/includes/footer.php'; ?>

Add a Database Method

1. Edit src/Database.php
2. Add method to the class
3. Write test in tests/Unit/
4. Run: just test-unit

Update CSS

1. Edit public/assets/posterg.css
2. Browser auto-refreshes
3. Increment cache-bust in header: posterg.css?v=N

---

Justfile Commands

Development

Command	Description
just setup	Setup dev environment (one-time)
just serve	Start dev server with live reload
just stop	Stop dev server
just logs	View dev logs

Testing

Command	Description
just test	Run all tests
just test-unit	Unit tests only
just test-integration	Integration tests only
just test-security	Security tests only
just syntax	Check PHP syntax

Database

Command	Description
just stats	Database statistics
just query	Open SQLite shell
just show <id>	Show thesis by ID
just reset-db	Reset test database
just fixtures	Create sample data
just backup	Backup database

Deployment

Command	Description
just deploy	Deploy complete site
just deploy-nginx	Deploy nginx config
just deploy-db	Deploy database
just server-status	Check server health
just server-logs	View server logs

---

Debugging

just logs              # View error logs
tail -f error.log      # Direct log monitoring

# PHP errors in browser (temporary):
# Add to PHP file:
ini_set('display_errors', 1);
error_reporting(E_ALL);

# Database issues:
just stats             # Check DB exists and has data
just query             # Open SQLite shell

Server Won't Start

just stop              # Kill existing process
just setup             # Reinstall php-live-reload

Database Errors

just reset-db          # Reset from schema
just fixtures          # Repopulate with sample data
just test              # Verify everything works