December 26–27, 2025 · TFOL Dev Log

Overview

This update completes a major infrastructure improvement in TFOL: moving from ad-hoc image handling to a config-driven, Imagick-first image processing pipeline with GD fallback.

The goal was reliability across environments (local, shared hosting), consistent image quality, and safer long-term maintenance.

---

What Changed

1. Config-driven image pipeline

Image behavior is now controlled centrally:

• IMAGE_DRIVER = auto | imagick | gd

• IMAGE_MAX_DIM = 1600

• IMAGE_QUALITY = 82

• IMAGE_OUTPUT_FORMAT = jpg

• Thumbnail defaults: 600 × 400

This eliminates scattered “magic numbers” and makes behavior predictable.

---

2. Capability-based driver selection

A single resolver determines which image engine runs:

• auto → Imagick if available, else GD

• imagick → force Imagick, fail loudly if unavailable

• gd → force GD

This avoids silent failures and makes environment differences obvious.

---

3. Processor abstraction

Image resizing is now handled via a small interface:

• ImagickProcessor

• GdProcessor

The rest of TFOL doesn’t care how images are resized — only that they are.

---

4. Upload limits clarified and fixed

During smoke testing, an 8 MB image failed despite generous php.ini limits.

Root cause:
.htaccess was overriding PHP with:

• post_max_size = 5M

• upload_max_filesize = 5M

• memory_limit = 20M

Fix:

• upload_max_filesize = 20M

• post_max_size = 25M

• memory_limit = 256M

Lesson: Local PHP “Master” values don’t matter if directory overrides exist.

---

5. Tooling cleanup (VS Code)

VS Code reported Imagick as an undefined type even though PHP was working correctly.

Fix:

• Added jetbrains/phpstorm-stubs

• Updated Intelephense include paths

• Cleared cache

Result:

• All false errors disappeared

• Editor and runtime behavior finally matched

---

Smoke Test Results

• Uploaded 8 MB+ phone photo successfully

• Final image: 1200 × 700 (under MAX_DIM=1600)

• Saved filename:
  001577_25-12-26-friday.jpg

• Debug panel confirmed:

  • resolved_driver = imagick

  • Correct quality and format applied

---

Lessons Learned

• PHP upload failures often happen before application code runs

• .htaccess overrides can silently defeat php.ini

• Static analysis tools need extension stubs to reflect reality

• A tiny debug panel can save hours of guesswork

• Centralized configuration beats scattered logic every time

---

Status

✔ Imagick-first resizing complete
✔ GD fallback verified
✔ Naming standard restored
✔ Ready for A2 hosting evaluation

---