xamxam/docs/MIGRATION_GUIDE.md

Repository Restructure Migration Guide

This guide explains how to migrate the Post-ERG repository to a standard idiomatic PHP structure.

📋 Overview

Current Structure

posterg-website/
├── apps/
│   ├── public/       # Public website
│   └── admin/        # Admin panel
├── shared/           # Shared PHP libraries
└── database/         # Database files

New Structure (Standard PHP)

posterg-website/
├── index.php         # Public root
├── *.php             # Public PHP files
├── admin/            # Admin panel
├── lib/              # Shared libraries (renamed from shared/)
├── inc/              # Templates (header/footer)
├── assets/           # Static files
├── database/         # Database files
└── vendor/           # Third-party code (gitignored)

---

🎯 Benefits

✅ Standard PHP structure - Follows community conventions
✅ Flatter hierarchy - Easier navigation
✅ Simpler paths - Less ../../ in code
✅ Cleaner deployment - Single rsync command
✅ Live reload - Auto-refresh during development

---

🚀 Migration Steps

Step 1: Review the Plan

Read the restructure plan:

cat docs/RESTRUCTURE_PLAN.md

Step 2: Commit Current State

Important: Commit all your current work first!

git add -A
git commit -m "Pre-migration checkpoint"

Step 3: Run Migration Script

./migrate-structure.sh

This will:

• Move apps/public/* to root
• Move apps/admin/ to admin/
• Rename shared/ to src/
• Update all require paths automatically
• Remove apps/ directory
• Update .gitignore

Step 4: Test Locally

# Setup development environment
just setup-dev

# Test public site (with live reload!)
just serve-public

# Test admin panel
just serve-admin

Visit:

• http://localhost:8000 - Public site
• http://localhost:3000 - Admin panel

Step 5: Verify Changes

# Check syntax
just check-public

# Run database tests
just stats-public

# View structure
tree -L 2 -I 'node_modules|.git|vendor'

Step 6: Update Justfile

# Backup old justfile
mv justfile justfile.old

# Use new justfile
mv justfile.new justfile

Step 7: Commit Migration

git add -A
git commit -m "Restructure to idiomatic PHP layout

- Moved apps/public to root
- Moved apps/admin to admin/
- Renamed shared/ to lib/
- Added php-live-reload for local dev
- Updated all require paths
- Simplified deployment"

Step 8: Deploy to Production

# Deploy everything
just deploy

# Or deploy separately
just deploy-public
just deploy-admin

---

📝 What Changed

File Movements

Old Path	New Path
apps/public/index.php	index.php
apps/public/memoire.php	memoire.php
apps/public/assets/	assets/
apps/public/inc/	inc/
apps/admin/	admin/
shared/Database.php	src/Database.php
shared/config.php	src/config.php
shared/cache/	src/cache/

Path Updates

All PHP files automatically updated:

Root files:

// Before
require_once __DIR__ . '/shared/Database.php';

// After
require_once __DIR__ . '/lib/Database.php';

Admin files:

// Before
require_once __DIR__ . '/../../shared/Database.php';

// After
require_once __DIR__ . '/../lib/Database.php';

Config file:

// Before
define('DB_ROOT', __DIR__ . '/..');

// After (stays the same)
define('DB_ROOT', __DIR__ . '/..');

Justfile Changes

Before:

just serve-public  # Basic PHP server

After:

just setup-dev     # One-time: Install php-live-reload
just serve-public  # PHP server with live reload!

Before:

# Deploy in multiple steps
rsync apps/public/ posterg:/var/www/html/
rsync apps/admin/ posterg:/var/www/html/formulaire/
rsync shared/ posterg:/var/www/html/shared/

After:

# Deploy in one command
just deploy

---

🔄 PHP Live Reload

What It Does

Automatically refreshes your browser when you save PHP files!

Setup (One Time)

just setup-dev

This clones https://github.com/ryantate13/php-live-reload to vendor/php-live-reload/ (gitignored).

Usage

# Start with live reload
just serve-public  # or serve-admin

# Edit PHP files
# Browser auto-refreshes on save! 🎉

How It Works

• Monitors PHP files for changes
• Sends reload signal via WebSocket
• Browser reloads automatically
• No browser extension needed
• Only for local development
• Never deployed to production

---

🧪 Testing

Before Deploying

1. Syntax check:

   just check-public
   

2. Test database:

   just stats-public
   

3. Test public site:

   just serve-public
   # Visit http://localhost:8000
   

4. Test admin:

   just serve-admin
   # Visit http://localhost:3000
   

5. Check file permissions:

   ls -la | head -n 20
   ls -la admin/ | head -n 20
   ls -la lib/
   

After Deploying

1. Test public site:

   curl -I https://posterg.erg.be/
   

2. Test CSS loading:

   curl -I https://posterg.erg.be/assets/posterg.css
   

3. Test admin:

   curl -I https://posterg.erg.be/admin/
   

---

🔙 Rollback (If Needed)

If something goes wrong:

# Revert the migration
git reset --hard HEAD~1

# Or restore from backup
git checkout HEAD~1 -- .

---

📚 New Directory Structure

posterg-website/
├── index.php             # Public site root
├── memoire.php           # Thesis detail page
├── search.php            # Search page
├── apropos.php           # About page
├── contact.php           # Contact page
├── licences.php          # Licenses page
├── test_db.php           # Database test script
│
├── assets/               # Static files
│   ├── posterg.css      # Main CSS
│   ├── normalize.css    # CSS reset
│   ├── fonts/           # Custom fonts
│   └── icons.svg        # Icon set
│
├── inc/                  # Page templates
│   ├── header.php       # Site header
│   └── footer.php       # Site footer
│
├── lib/                  # Shared libraries (was shared/)
│   ├── Database.php     # Database class
│   ├── RateLimit.php    # Rate limiting
│   ├── config.php       # Configuration
│   └── cache/           # Cache files
│
├── admin/                # Admin panel (was apps/admin/)
│   ├── index.php        # Admin dashboard
│   ├── list.php         # Thesis list
│   ├── edit.php         # Edit thesis
│   ├── formulaire.php   # Add thesis
│   ├── import.php       # Import tool
│   └── data/            # Upload directories
│
├── database/             # Database files & schema
│   ├── schema.sql       # Database schema
│   ├── test.db          # Test database
│   ├── fixtures/        # Test data generators
│   └── *.md             # Documentation
│
├── vendor/               # Third-party code (gitignored)
│   └── php-live-reload/ # Live reload tool
│
├── nginx/                # Server configuration
├── docs/                 # Documentation
├── tests/                # Tests (future)
│
├── justfile              # Task runner
├── .gitignore            # Git ignore rules
└── README.md             # Project readme

---

❓ FAQ

Q: Will the migration break the deployed site?

A: No. The migration only affects your local repository. Deploy only after testing locally.

Q: Do I need to update the database?

A: No. The database structure doesn't change. Only file paths change.

Q: What about nginx configuration?

A: Nginx config doesn't need to change. It still serves from /var/www/html/.

Q: Will git history be preserved?

A: Yes. Git tracks file movements. Use git log --follow filename.php to see history.

Q: Can I undo the migration?

A: Yes. Use git reset --hard HEAD~1 before committing.

Q: Does php-live-reload work on all platforms?

A: Yes. Works on Linux, macOS, and Windows (with PHP installed).

Q: Will php-live-reload be deployed?

A: No. It's in vendor/ which is gitignored and excluded from deployment.

---

🆘 Troubleshooting

Migration script fails

Check you're in the repo root:

pwd
ls -la apps shared

Make script executable:

chmod +x migrate-structure.sh

PHP can't find lib/ files

Check paths were updated:

grep -r "require.*lib/" . --include="*.php" | head -n 5

Manually fix a file:

# Edit the file and change:
require_once __DIR__ . '/shared/Database.php';
# To:
require_once __DIR__ . '/lib/Database.php';

Live reload doesn't work

Check vendor directory:

ls -la vendor/php-live-reload/

Re-run setup:

just setup-dev

Site works locally but not on server

Check file permissions on server:

ssh posterg "ls -la /var/www/html/ | head -n 20"

Re-run deployment:

just deploy

---

📞 Need Help?

1. Check the plan: cat docs/RESTRUCTURE_PLAN.md
2. Review justfile: cat justfile
3. Check git status: git status
4. Test locally first: just serve-public

---

Ready to migrate?

./migrate-structure.sh

Good luck! 🚀