mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 19:19:19 +02:00
Major refactor
- update the structure to have monolithic setup - updated deployments - added live-reloading for devops
This commit is contained in:
Théophile Gervreau-Mercier
507
docs/DEVELOPMENT_GUIDE.md
Normal file
507
docs/DEVELOPMENT_GUIDE.md
Normal file
@@ -0,0 +1,507 @@
|
||||
# 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__ . '/lib/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__ . '/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:**
|
||||
```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__ . '/../../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
|
||||
|
||||
```bash
|
||||
just deploy
|
||||
```
|
||||
|
||||
This deploys:
|
||||
- Public site (root PHP files)
|
||||
- Admin panel (`admin/`)
|
||||
- Shared libraries (`lib/`)
|
||||
|
||||
**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 (`database/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](../database/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! 🚀
|
||||
Reference in New Issue
Block a user