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:
71
docs/consultations/gemini-blueprint-casing-2026-04-06.md
Normal file
71
docs/consultations/gemini-blueprint-casing-2026-04-06.md
Normal 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!* 💙🔥❄️
|
||||
Reference in New Issue
Block a user