Using AI to Solve File Versioning Headaches in Drupal: The Media Revision Module

Project Summary

This project started as part of enhancing the media handling capabilities for a major healthcare system. The goal was to make sure that file attachments kept proper revision history, allowing visitors to see the latest versions of things like PDF files without requiring content editors needing to constantly update their pages with new file paths. Out of that work came the media_revision module, a custom Drupal module that manages how files are stored and served when media entities go through different publication cycles.

When “Latest Version” Isn’t Really the Latest

Drupal’s default media handling has a hidden flaw when it comes to file versions. If you upload a file like a PDF, publish it, and later update it with a new version, all the existing links on your site still point to the old file. That means unless editors hunt down and update every single reference by hand, visitors keep hitting the old file. It’s tedious, easy to miss, and a recipe for confusion.

There were other problems, too. Files attached to unpublished media revisions were still publicly visible, which created a security risk. Making every file private wasn’t a good fix either because it slowed the site down. And since Drupal lets the same file entity get reused across multiple media items, you could also run into messy file conflicts.

From a technical perspective, Drupal’s behavior makes sense. But from the perspective of content editors and site visitors, it doesn’t line up with expectations. People assume that if they link to a file, they’ll always be serving the most recent version. Without a better system, organizations risk confusing users, undermining trust with outdated information, and wasting staff time.

Designing a Smarter Way to Handle Files

Since I was starting from scratch I tried following the “best practices” approach of first using Claude in plan mode to come up with a specification document. The first spec it produced was really long and overly complicated, which helped me realize my prompt was too vague. After a few iterations, the “design” document was simpler and no longer included things I knew weren’t required.

I then asked ChatGPT-4o to review the specification. The idea was to get a second opinion, a fresh set of eyes to check for security or performance problems and suggest improvements. Once the spec felt solid, I went back to Claude 4 to generate the first version of the module.

From there, I tested the code, refined the logic, and adjusted it based on real-world needs. The AI-assisted coding wasn’t automatic. It was more of a back and forth between my own knowledge and the AI’s suggestions, but that back-and-forth eventually got me to a solution that actually worked and didn’t bog things down.

The result is now available as a sandbox project on Drupal.org: media_revision module

Lessons From Trial, Error, and Iteration

This project was as much about the process as the outcome. Using coding assistants to bootstrap a project is fast, but they can get out of hand if you don’t give very clear, narrow instructions. Without clear instructions, the models tend to wander. They’ll try fixing things you never asked them to, get too wordy, pull in outdated APIs, and spit out code that doesn’t even match its own style.

Looking back, I should have broken the task down into smaller chunks and handled each separately. Breaking the work into smaller chunks would have saved me a lot of hassle. Divide and conquer beats trying to wrangle the whole thing at once. Even so, the project reinforced that these tools are great for generating a starting point, as long as you bring detailed technical knowledge and step in to guide the work.

Why This Fix Saves Editors Time (and Protects Users)

The media_revision module is immediately useful for organizations with complex media workflows. For a large healthcare provider, keeping patient documents and policy files accurate isn’t just important, it’s critical for trust and compliance. This module ensures that:

• Public links always serve the latest file version.
• Revision history is preserved for accountability.
• File storage is handled securely and efficiently.
• Conflicts are avoided when files are reused across entities.

And while this project focused on media entities, the same pattern could be extended to custom content entities with file attachments. Any industry where document version control and access security are critical could benefit from this approach.

From One Client’s Challenge to a Wider Solution

What began as a solution for one client’s media handling needs turned into a module that could help any Drupal site manage file revisions better. The process also showed me both the strengths and the limits of AI coding assistants. They can save time, but they need detailed direction and human oversight.

Want to learn more about using AI to solve drupal module issues? Reach out, we're happy to share insights and practical tips from this project and others.

Image by StartupStockPhotos from Pixabay