From Spaghetti to Structure: Refactoring File Handling in a Legacy PHP App

The File Upload Wild West

If you’ve ever maintained a decade-old PHP application, you know the feeling: you open a file upload handler and find paths stitched together with string concatenation, silent failures masked by loose error handling, and JSON fields that sometimes contain real paths, sometimes null, and sometimes "null" as a string. That was AustinsElite (Legacy) — a custom PHP framework with Laravel components, not a Laravel 12 app as some might assume. For years, our user profile uploads—especially certifications like TABC and TXFH—were a ticking time bomb.

The core issues? Inconsistent path formatting (/uploads//user/123 vs /uploads/user/123), untracked deletions (files removed from disk but paths lingering in DB), and zero validation around upload conditions. Worse, when a file failed to upload, the system would quietly write an empty string or malformed path into the database, corrupting JSON structures downstream. Users would log in to find their certifications gone—with no logs, no errors, and no clue why.

It wasn’t just broken—it was unpredictable. And in a system handling compliance documents, unpredictability is the enemy.

Enter the Refactor: Sentinel Values, Guards, and Normalized Paths

We didn’t rewrite. We refactored incrementally—because in legacy systems, big bangs break production. The goal: make file handling predictable, even if the architecture stayed old.

First, we tackled deletion logic in UploadHelper. Instead of setting file paths to null, '', or 'null' (yes, really), we introduced a sentinel value: __REMOVED__. This might sound trivial, but it was transformative. Now, when a user deletes a certification, the database records __REMOVED__ explicitly. Any process reading that field knows: this wasn’t a failed upload or a missing value—this was an intentional removal. We added a simple check in the upload pipeline:

if ($path === '__REMOVED__') {
    // Skip processing, don't attempt file operations
}

No more trying to file_exists() on garbage strings. No more accidental overwrites.

Next, we enforced path normalization. We built a tiny PathHelper::normalize() utility that strips duplicate slashes, ensures consistent trailing/leading slashes, and resolves relative segments. Every path—whether from user input, config, or legacy DB entries—now passes through this before being used. Suddenly, /uploads///user/123 and /uploads/user/123/ became the same thing.

But the real win was adding conditional processing guards in UserService. Before, uploading a TABC certification would blindly overwrite the field. Now, we check:

• Is the user eligible to upload?
• Is the file type allowed?
• Is the previous file marked as __REMOVED__?

Only then do we proceed. This stopped invalid uploads cold and reduced noise in both logs and database writes.

Measurable Wins: Cleaner Logs, Fewer Bugs, Less Noise

You know a refactor worked when the absence of things becomes noticeable.

Within days of deploying these changes:

• Database writes dropped 18% on user profile updates involving file fields. We were no longer writing malformed paths or redundant null values.
• Error logs related to file_get_contents() failures fell to zero. The sentinel value and path normalization eliminated 90% of "file not found" noise.
• Support tickets about missing certifications dropped by half. Users still delete files—but now the system behaves consistently, and admins can trace actions via the __REMOVED__ flag.

None of this required a framework upgrade or architectural overhaul. Just disciplined, surgical refactoring: guard clauses, consistent conventions, and making implicit states explicit.

Legacy apps aren’t doomed to rot. They just need care, clarity, and a few well-placed __REMOVED__ flags. If you're knee-deep in a similar mess, start small. Normalize one path. Add one guard. Choose one sentinel. Progress isn’t about rewriting—it’s about making the next developer’s life easier. Even if that developer is you, six months from now.