xamxam/docs/DEVELOPMENT_GUIDE.md

Post-ERG Development Guide

Complete guide for developing the Post-ERG thesis management system.

🚀 Quick Start

1. Setup (One Time)

# Clone php-live-reload and setup directories
just setup

2. Start Development Server

just serve

This starts one unified server at:

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

✨ Live reload enabled - your browser auto-refreshes when you save files!

3. Edit & Watch

Edit any PHP file and watch your browser automatically refresh! 🎉

---

📁 Project Structure

posterg-website/
├── index.php           # Public homepage
├── memoire.php         # Thesis detail page
├── search.php          # Search page
├── *.php              # Other public pages
│
├── admin/             # Admin panel
│   ├── index.php      # Admin dashboard
│   ├── list.php       # Thesis list
│   ├── edit.php       # Edit thesis
│   └── formulaire.php # Add thesis
│
├── lib/               # Shared libraries
│   ├── Database.php   # Database class
│   ├── RateLimit.php  # Rate limiting
│   └── config.php     # Configuration
│
├── inc/               # Page templates
│   ├── header.php     # Site header
│   └── footer.php     # Site footer
│
├── assets/            # Static files
│   ├── posterg.css    # Main CSS
│   └── fonts/         # Custom fonts
│
├── database/          # Database
│   ├── schema.sql     # Schema definition
│   ├── test.db        # Test database
│   └── fixtures/      # Sample data
│
├── tests/             # Test suite
│   ├── Unit/          # Unit tests
│   ├── Integration/   # Integration tests
│   └── Security/      # Security tests
│
└── vendor/            # Third-party (gitignored)
    └── php-live-reload/

---

🛠️ Development Workflow

Starting Development

# Start the development server
just serve

# In your browser:
# - Public site: http://localhost:8000
# - Admin panel: http://localhost:8000/admin/

Making Changes

1. Edit PHP files - Auto-refreshes browser
2. Edit CSS - Auto-refreshes browser
3. Test changes - See them instantly!

Running Tests

# Run all tests
just test

# Run specific test suites
just test-unit         # Unit tests
just test-integration  # Integration tests
just test-security     # Security tests

Database Operations

# View database stats
just stats

# Open SQLite shell
just query

# Show specific thesis
just show 42

# Reset database
just reset-db

# Create with sample data
just fixtures

---

📝 Common Tasks

Create a New Page

1. Create newpage.php in root
2. Add require_once __DIR__ . '/lib/Database.php';
3. Include header: include 'inc/header.php';
4. Add your content
5. Include footer: include 'inc/footer.php';

Example:

<?php
require_once __DIR__ . '/lib/Database.php';
include 'inc/header.php';
?>

<section class="section">
  <div class="container">
    <h1 class="title">My New Page</h1>
    <p>Content here...</p>
  </div>
</section>

<?php include 'inc/footer.php'; ?>

Add a Database Function

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

Update CSS

1. Edit assets/posterg.css
2. Browser auto-refreshes!
3. (Optional) Increment version in inc/header.php: posterg.css?v=3

Add a Test

1. Choose location:

   • tests/Unit/ - For testing classes/functions
   • tests/Integration/ - For testing workflows
   • tests/Security/ - For testing security

2. Create test file (e.g., tests/Unit/MyTest.php)

3. Follow the template in tests/README.md

4. Add to tests/run-tests.php

5. Run: just test

---

🧪 Testing

Test Database

Development uses database/test.db (gitignored).

Create test database:

just init-db

Populate with sample data:

just fixtures

Deploy test database to server:

just deploy-test-db

Reset everything:

just reset-db

Writing Tests

See tests/README.md for complete testing guide.

Quick example:

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

echo "My Test\n";
echo "=======\n\n";

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

---

🚀 Deployment

Deploy Everything

just deploy

This deploys:

• Public site (root PHP files)
• Admin panel (admin/)
• Shared libraries (lib/)

Note: vendor/ is automatically excluded from deployment.

Deploy Selectively

# Deploy only the code
just deploy

# Deploy test database
just deploy-test-db

# Deploy nginx config
just deploy-nginx

# Deploy admin tools
just deploy-admin-tools

---

🔧 Justfile Commands

Development

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

Testing

Command	Description
just test	Run all tests
just test-unit	Run unit tests
just test-integration	Run integration tests
just test-security	Run security tests
just syntax	Check PHP syntax

Database

Command	Description
just init-db	Create test database
just reset-db	Reset test database
just query	Open SQLite shell
just show <id>	Show thesis by ID
just backup	Backup database
just fixtures	Create sample data
just deploy-test-db	Deploy test database to server

Statistics

Command	Description
just stats	Show database statistics
just recent	Show recent theses

Deployment

Command	Description
just deploy	Deploy complete site
just deploy-nginx	Deploy nginx configuration
just deploy-admin-tools	Deploy admin user management

Server

Command	Description
just server-logs	View server logs
just server-status	Check server status

Utilities

Command	Description
just clean	Clean up dev files
just setup-dirs	Create data directories

---

💡 Tips & Tricks

Live Reload

The just serve command uses php-live-reload to automatically refresh your browser when you save files.

What triggers refresh:

• Saving any .php file
• Saving any file in the project

How it works:

• WebSocket connection monitors file changes
• Browser receives reload signal
• Page refreshes automatically

No browser extension needed!

Multiple Browser Windows

Open multiple browser windows/tabs - they all get live reload!

http://localhost:8000/          # Public site
http://localhost:8000/admin/    # Admin panel
http://localhost:8000/memoire.php?id=13  # Specific thesis

All will auto-refresh when you save files! ✨

Using a Real Test Database

The test database (database/test.db) is gitignored. To share test data:

# Create fixtures
just fixtures

# Commit the fixtures generator
git add database/fixtures/
git commit -m "Update test fixtures"

Others can recreate with: just fixtures

Debugging

Check error logs:

just logs

Or directly:

tail -f error.log

PHP errors in browser: Edit your PHP file temporarily:

ini_set('display_errors', 1);
error_reporting(E_ALL);

Database issues:

# Check database exists
ls -lh database/test.db

# Open database shell
just query

# Check tables
sqlite> .tables

# Show schema
sqlite> .schema theses

---

🔍 Troubleshooting

Server won't start

Port already in use:

just stop
# Or manually:
pkill -f "php -S 127.0.0.1:8000"

php-live-reload missing:

just setup

Live reload not working

Check vendor directory:

ls -la vendor/php-live-reload/

Reinstall:

rm -rf vendor/php-live-reload
just setup

Database errors

Database not found:

just init-db

Permissions error:

chmod 644 database/test.db

Schema errors:

just reset-db

Tests failing

Run individual test:

php tests/Unit/DatabaseTest.php

Check database:

just stats

Reset database:

just reset-db
just fixtures
just test

---

📚 Further Reading

• Test Documentation
• Database Specification
• Migration Guide
• Deployment Guide

---

✨ Quick Reference

Start developing:

just setup    # One time
just serve    # Start server

Test your changes:

just test     # Run tests
just stats    # Check database

Deploy to production:

just deploy

That's it! Happy coding! 🚀