xamxam/docs/LIVE_RELOAD_SETUP.md

# 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! ✨