mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 19:19:19 +02:00
3cd96ed28a
- 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
273 lines
6.2 KiB
Markdown
273 lines
6.2 KiB
Markdown
# 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
|
|
```
|