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)

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

### 2. Start Development Server

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

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

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

```bash
# 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__ . '/src/Database.php';`
3. Include header: `include 'inc/header.php';`
4. Add your content
5. Include footer: `include 'inc/footer.php';`

Example:
```php
<?php
require_once __DIR__ . '/src/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 `src/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 `storage/test.db` (gitignored).

**Create test database:**
```bash
just init-db
```

**Populate with sample data:**
```bash
just fixtures
```

**Deploy test database to server:**
```bash
just deploy-test-db
```

**Reset everything:**
```bash
just reset-db
```

### Writing Tests

See `tests/README.md` for complete testing guide.

**Quick example:**
```php
<?php
require_once __DIR__ . '/../../src/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

```bash
just deploy
```

This deploys:
- Public site (root PHP files)
- Admin panel (`admin/`)
- Shared libraries (`src/`)

**Note:** `vendor/` is automatically excluded from deployment.

### Deploy Selectively

```bash
# 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 (`storage/test.db`) is gitignored. To share test data:

```bash
# 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:**
```bash
just logs
```

**Or directly:**
```bash
tail -f error.log
```

**PHP errors in browser:**
Edit your PHP file temporarily:
```php
ini_set('display_errors', 1);
error_reporting(E_ALL);
```

**Database issues:**
```bash
# 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:**
```bash
just stop
# Or manually:
pkill -f "php -S 127.0.0.1:8000"
```

**php-live-reload missing:**
```bash
just setup
```

### Live reload not working

**Check vendor directory:**
```bash
ls -la vendor/php-live-reload/
```

**Reinstall:**
```bash
rm -rf vendor/php-live-reload
just setup
```

### Database errors

**Database not found:**
```bash
just init-db
```

**Permissions error:**
```bash
chmod 644 database/test.db
```

**Schema errors:**
```bash
just reset-db
```

### Tests failing

**Run individual test:**
```bash
php tests/Unit/DatabaseTest.php
```

**Check database:**
```bash
just stats
```

**Reset database:**
```bash
just reset-db
just fixtures
just test
```

---

## 📚 Further Reading

- [Test Documentation](../tests/README.md)
- [Database Specification](../storage/DATABASE_SPECIFICATION.md)
- [Migration Guide](../MIGRATION_GUIDE.md)
- [Deployment Guide](../nginx/DEPLOYMENT_COMPLETE.md)

---

## ✨ Quick Reference

**Start developing:**
```bash
just setup    # One time
just serve    # Start server
```

**Test your changes:**
```bash
just test     # Run tests
just stats    # Check database
```

**Deploy to production:**
```bash
just deploy
```

That's it! Happy coding! 🚀