# Development Guide

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

---

## Quick Start

```bash
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

```bash
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

```bash
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)

```bash
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
<?php if (php_sapi_name() === 'cli-server'): ?>
<script src="/vendor/php-live-reload/php-live-reload/live-reload.js"></script>
<?php endif; ?>
```

### Troubleshooting

```bash
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

```bash
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
<?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
<?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

```bash
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

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

### Database Errors

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