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)

just setup

This clones php-live-reload into vendor/php-live-reload/ (which is gitignored).

---

🏃 Using Live Reload

Start Server

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 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_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:

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:

define('MIN_DELAY', 1000);  // Minimum milliseconds between checks

File Watching

By default, watches all files in project directory.

To exclude paths, edit config:

$exclude = [
    'vendor',
    '.git',
    'node_modules',
    'cache'
];

---

🐛 Troubleshooting

Live Reload Not Working

1. Check vendor directory exists:

ls -la vendor/php-live-reload/

If missing:

just setup

2. Check script is included in page:

curl -s http://localhost:8000/ | grep live-reload

Should show:

<script src="/vendor/php-live-reload/php-live-reload/live-reload.js"></script>

3. Check endpoint is accessible:

curl http://localhost:8000/vendor/php-live-reload/php-live-reload/live-reload.php

Should return 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:

just serve

NOT production (nginx/apache).

Check PHP detection:

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:

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:

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