docs: Add Gemini consultation on PSR-4 controller casing

Confirmed Controllers/ (uppercase) is required for PSR-4 autoloading
on case-sensitive Linux filesystem. Repo already correct.

Signed-off-by: Claude (Chronicler #63) <claude@firefrostgaming.com>
This commit is contained in:
Claude (Chronicler #63)
2026-04-06 09:17:38 +00:00
parent 287ecf1166
commit 5b16033af5

View File

@@ -0,0 +1,71 @@
# Gemini Consultation: Blueprint Controller Casing
**Date:** April 6, 2026
**Chronicler:** #63
**Topic:** PSR-4 autoloading and folder casing for Blueprint extensions
---
## Question Summary
We found a discrepancy between:
- Dev Panel backup: `controllers/` (lowercase)
- Git repo: `Controllers/` (uppercase)
Namespace in PHP: `Pterodactyl\BlueprintFramework\Extensions\modpackchecker\Controllers;`
---
## Gemini's Response
### The Clear Answer
The folder in your repository must be `Controllers/` (uppercase C).
### The Reasoning
PHP's modern autoloading relies strictly on the PSR-4 standard. Under PSR-4, the physical directory structure must perfectly mirror the namespace structure.
Because your namespace explicitly declares an uppercase 'C':
```php
namespace Pterodactyl\BlueprintFramework\Extensions\modpackchecker\Controllers;
```
The autoloader will instruct the server to look for a directory named exactly `Controllers`.
Crucially, your Pterodactyl panel runs on Linux. The Linux filesystem is strictly case-sensitive. If PHP asks Linux for `Controllers/ModpackAPIController.php` but the folder is named `controllers/` (lowercase), Linux will report that the path does not exist, and the application will crash.
### The Gotchas
1. **The "It Works on Windows" Trap:** If any initial development, testing, or file extraction happened on a Windows machine, the code might have actually executed fine. Windows is generally case-insensitive. But the moment that codebase is pushed to your Linux server, the exact same code will trigger a `500 Server Error: Class '...ModpackAPIController' not found`.
2. **Git Casing Blindness:** Git sometimes ignores folder case changes if you just rename it in your file explorer. If you simply rename `controllers` to `Controllers` on a Windows machine, Git might not register the change, and the lowercase folder will still push to the server.
### Git Fix (if needed)
```bash
git mv controllers temp_controllers
git mv temp_controllers Controllers
git commit -m "Fix PSR-4 autoloading: Capitalize Controllers folder"
```
---
## Resolution
Our repo (`firefrost-services`) already has `Controllers/` with correct uppercase casing. No changes needed.
The Dev Panel backup had lowercase `controllers/` — this explains potential autoloading issues. When deploying from repo, we'll have correct casing.
---
## Action Items
- [x] Confirmed repo has correct casing
- [ ] Deploy from repo to Dev Panel (will fix casing automatically)
- [ ] Document this in README troubleshooting section
---
*Consultation complete. Thank you, Gemini!* 💙🔥❄️