mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 11:09:18 +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
297
docs/LIVE_RELOAD_SETUP.md
Normal file
297
docs/LIVE_RELOAD_SETUP.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# Live Reload Setup
|
||||
|
||||
Guide to setting up and using live reload for Post-ERG development.
|
||||
|
||||
## 🎯 What is Live Reload?
|
||||
|
||||
Live reload automatically refreshes your browser when you save files during development. No need to manually hit refresh!
|
||||
|
||||
## ✨ How It Works
|
||||
|
||||
1. **JavaScript** in the page polls the server for file changes
|
||||
2. **PHP backend** checks file modification times
|
||||
3. **Browser** automatically refreshes when changes detected
|
||||
|
||||
**No browser extension needed!**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Setup (One Time)
|
||||
|
||||
```bash
|
||||
just setup
|
||||
```
|
||||
|
||||
This clones `php-live-reload` into `vendor/php-live-reload/` (which is gitignored).
|
||||
|
||||
---
|
||||
|
||||
## 🏃 Using Live Reload
|
||||
|
||||
### Start Server
|
||||
|
||||
```bash
|
||||
just serve
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
🚀 Starting Post-ERG development server
|
||||
========================================
|
||||
|
||||
📍 Public site: http://localhost:8000
|
||||
📍 Admin panel: http://localhost:8000/admin/
|
||||
|
||||
✨ Live reload enabled - browser auto-refreshes on file save!
|
||||
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
### Edit Files
|
||||
|
||||
1. Open http://localhost:8000 in your browser
|
||||
2. Edit any PHP, CSS, or JS file
|
||||
3. Save the file
|
||||
4. **Browser automatically refreshes!** ✨
|
||||
|
||||
### What Triggers Reload
|
||||
|
||||
- Saving `.php` files
|
||||
- Saving `.css` files
|
||||
- Saving `.js` files
|
||||
- Any file change in the project
|
||||
|
||||
---
|
||||
|
||||
## 🔧 How It's Integrated
|
||||
|
||||
### In `inc/header.php`
|
||||
|
||||
Live reload script is conditionally included only during development:
|
||||
|
||||
```php
|
||||
<?php if (getenv('PHP_ENV') === 'development' || php_sapi_name() === 'cli-server'): ?>
|
||||
<!-- Live reload for development -->
|
||||
<script src="/vendor/php-live-reload/php-live-reload/live-reload.js"></script>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- ✅ Included when using `php -S` (development server)
|
||||
- ❌ NOT included in production (nginx/apache)
|
||||
- ❌ NOT deployed to server (vendor/ is gitignored)
|
||||
|
||||
### Detection Logic
|
||||
|
||||
```php
|
||||
php_sapi_name() === 'cli-server' // True when using PHP dev server
|
||||
```
|
||||
|
||||
This means live reload is automatically enabled/disabled based on environment!
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
```
|
||||
vendor/php-live-reload/
|
||||
├── php-live-reload/
|
||||
│ ├── live-reload.js # JavaScript client
|
||||
│ ├── live-reload.php # PHP backend (checks files)
|
||||
│ └── config.php # Configuration
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Live Reload
|
||||
|
||||
### Test It Works
|
||||
|
||||
1. Start server: `just serve`
|
||||
2. Open http://localhost:8000
|
||||
3. Open browser console (F12)
|
||||
4. Edit `index.php` and save
|
||||
5. Watch browser auto-refresh!
|
||||
|
||||
You'll see in console:
|
||||
```javascript
|
||||
GET /vendor/php-live-reload/php-live-reload/live-reload.php
|
||||
change detected
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Polling Interval
|
||||
|
||||
Default: Checks every ~1-2 seconds
|
||||
|
||||
To change, edit `vendor/php-live-reload/php-live-reload/config.php`:
|
||||
|
||||
```php
|
||||
define('MIN_DELAY', 1000); // Minimum milliseconds between checks
|
||||
```
|
||||
|
||||
### File Watching
|
||||
|
||||
By default, watches all files in project directory.
|
||||
|
||||
To exclude paths, edit config:
|
||||
|
||||
```php
|
||||
$exclude = [
|
||||
'vendor',
|
||||
'.git',
|
||||
'node_modules',
|
||||
'cache'
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Live Reload Not Working
|
||||
|
||||
**1. Check vendor directory exists:**
|
||||
```bash
|
||||
ls -la vendor/php-live-reload/
|
||||
```
|
||||
|
||||
If missing:
|
||||
```bash
|
||||
just setup
|
||||
```
|
||||
|
||||
**2. Check script is included in page:**
|
||||
```bash
|
||||
curl -s http://localhost:8000/ | grep live-reload
|
||||
```
|
||||
|
||||
Should show:
|
||||
```html
|
||||
<script src="/vendor/php-live-reload/php-live-reload/live-reload.js"></script>
|
||||
```
|
||||
|
||||
**3. Check endpoint is accessible:**
|
||||
```bash
|
||||
curl http://localhost:8000/vendor/php-live-reload/php-live-reload/live-reload.php
|
||||
```
|
||||
|
||||
Should return JSON:
|
||||
```json
|
||||
{"time": 10, "changed": false}
|
||||
```
|
||||
|
||||
**4. Check browser console for errors**
|
||||
|
||||
Open browser console (F12) and look for:
|
||||
- WebSocket errors
|
||||
- Network errors to `/vendor/php-live-reload/`
|
||||
|
||||
### Script Not Loading
|
||||
|
||||
**Make sure you're using dev server:**
|
||||
```bash
|
||||
just serve
|
||||
```
|
||||
|
||||
NOT production (nginx/apache).
|
||||
|
||||
**Check PHP detection:**
|
||||
```bash
|
||||
php -r "echo php_sapi_name();"
|
||||
```
|
||||
|
||||
When using `just serve`, should output: `cli-server`
|
||||
|
||||
### Changes Not Detected
|
||||
|
||||
**Check polling is working:**
|
||||
|
||||
Open browser console, you should see repeated requests to:
|
||||
```
|
||||
/vendor/php-live-reload/php-live-reload/live-reload.php
|
||||
```
|
||||
|
||||
If not, check JavaScript loaded:
|
||||
```bash
|
||||
curl -I http://localhost:8000/vendor/php-live-reload/php-live-reload/live-reload.js
|
||||
```
|
||||
|
||||
Should return `200 OK`.
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Production Behavior
|
||||
|
||||
### Automatically Disabled
|
||||
|
||||
Live reload is **automatically disabled** in production because:
|
||||
|
||||
1. **`php_sapi_name()` check**: Only true with PHP dev server
|
||||
2. **vendor/ gitignored**: Not deployed to server
|
||||
3. **nginx serves files**: Different SAPI, condition false
|
||||
|
||||
### Verification
|
||||
|
||||
On production server:
|
||||
```bash
|
||||
curl https://posterg.erg.be/ | grep live-reload
|
||||
```
|
||||
|
||||
Should return nothing (script not included).
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tips
|
||||
|
||||
### Multiple Browser Windows
|
||||
|
||||
Open multiple tabs/windows - they all get live reload!
|
||||
|
||||
```
|
||||
http://localhost:8000/ # Homepage
|
||||
http://localhost:8000/admin/ # Admin panel
|
||||
http://localhost:8000/memoire.php?id=13 # Thesis page
|
||||
```
|
||||
|
||||
All will auto-refresh on file changes.
|
||||
|
||||
### Faster Development
|
||||
|
||||
With live reload:
|
||||
1. ✅ Edit code
|
||||
2. ✅ Save
|
||||
3. ✅ Browser refreshes
|
||||
4. ✅ See changes instantly!
|
||||
|
||||
No more:
|
||||
1. ❌ Edit code
|
||||
2. ❌ Save
|
||||
3. ❌ Switch to browser
|
||||
4. ❌ Hit F5
|
||||
5. ❌ Switch back to editor
|
||||
|
||||
**Saves you seconds on every change!**
|
||||
|
||||
---
|
||||
|
||||
## 📚 More Information
|
||||
|
||||
- GitHub: https://github.com/ryantate13/php-live-reload
|
||||
- Alternative: https://github.com/guard/guard-livereload
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quick Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `just setup` | Install live reload (one time) |
|
||||
| `just serve` | Start server with live reload |
|
||||
| `just stop` | Stop server |
|
||||
|
||||
**To use:** `just serve` and edit files - browser auto-refreshes! ✨
|
||||
Reference in New Issue
Block a user