mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 11:09:18 +02:00
Deduplicate and standardise documentation
- Consolidate 36 markdown files → 14 (plus TODO.md) - Merge overlapping docs into authoritative files: - database.md (from DATABASE_SPECIFICATION + QUICK_SCHEMA_REFERENCE + DATABASE_CONFIG + SETUP) - deployment.md (from SERVER_SETUP + COMPLETE_DEPLOYMENT_GUIDE + DEPLOYMENT_STEPS) - security.md (from SECURITY_ANALYSIS + TODO.SECURITY) - development.md (from DEVELOPMENT_GUIDE + LIVE_RELOAD_SETUP + TEST_CENTRALIZATION) - migration-history.md (from 11 past migration docs) - Standardise all filenames to lowercase - Remove non-doc files (Context.md research notes, chat export) - Remove superseded docs (SECURITY.md pre-SQLite, SECURITY_IMPLEMENTATION, README_SECURE_SEARCH) - Fix stale cross-references
This commit is contained in:
Pontoporeia
272
docs/development.md
Normal file
272
docs/development.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user