Target Audience: Web designers, developers, WordPress site maintainers, and agency owners who want to prevent media library clutter before it starts.
The Unspoken Rule of Client Sites: Media Library Upload Chaos
No matter how many onboarding documents or Loom tutorials you send to clients, file hygiene almost always collapses after launch.
People upload photos directly from their desktops and smartphones. Before long, your pristine WordPress media library is filled with file names like:
IMG_4821 2.JPGSummer Festival FINAL_final_v2.pngabout—us—header.jpeg
By default, WordPress preserves these messy spaces, uppercase characters, and special symbols in file URLs. Worse, WordPress does not automatically create an alt tag from the file name upon upload. If the person uploading forgets to add an alt tag in the sidebar, the image appears on the site completely unlabeled.
Why it matters: that damages search engine image discovery, lowers SEO relevance, and creates instant accessibility barriers for screen readers.
Instead of constantly chasing team members to clean up their files or running audits after the damage is done, we can future-proof the site at the point of ingestion using two lightweight WordPress hooks.
The Strategy: Two PHP Hooks, Zero Extra Plugin Cost or Clutter
This solution doesn’t require a bloated third-party plugin or an expensive SaaS subscription. It uses two native WordPress hooks that execute seamlessly behind the scenes:
sanitize_file_name: Automatically cleans up the physical file name upon upload by forcing lowercase letters, turning spaces and underscores into clean hyphens, and removing duplicate dashes.add_attachment: Intercepts the newly uploaded image, checks if an alt tag was omitted, and converts that sanitized file name into clean, human-readable Title Case (e.g.,marion-county-parkbecomesMarion County Park).
"Blue Mountain_trail hike 2.jpg"
Forces lowercase, converts spaces/underscores to hyphens.
Checks for empty alt tag & converts slug to clean Title Case.
The Future-Proofing PHP Snippet
Drop this code into your child theme’s functions.php or add it as a new PHP snippet inside the free Code Snippets plugin:
PHP
<?php
/**
* Auto-Sanitize Filenames and Set Alt Tags on Upload
* Author: Designer to Full Stack (designertofullstack.com)
*/
// 1. Sanitize the filename on upload
add_filter( 'sanitize_file_name', function( $filename ) {
// Lowercase multibyte characters
$filename = mb_strtolower( $filename, 'UTF-8' );
// Convert spaces and underscores to hyphens
$filename = str_replace( array( ' ', '_' ), '-', $filename );
// Remove multiple consecutive hyphens
$filename = preg_replace( '/-+/', '-', $filename );
return $filename;
}, 10, 1 );
// 2. Set default alt text from filename if empty upon upload
add_action( 'add_attachment', function( $post_id ) {
// Only process image attachments
if ( ! wp_attachment_is_image( $post_id ) ) {
return;
}
// Check if an alt tag is already assigned
$existing_alt = get_post_meta( $post_id, '_wp_attachment_image_alt', true );
if ( ! empty( $existing_alt ) ) {
return;
}
// Get the sanitized filename (without the extension)
$file_path = get_attached_file( $post_id );
$filename = pathinfo( $file_path, PATHINFO_FILENAME );
// Format hyphens/underscores into human-readable words
$alt_text = str_replace( array( '-', '_' ), ' ', $filename );
$alt_text = ucwords( trim( $alt_text ) ); // e.g., "marion-county-postcard" -> "Marion County Postcard"
// Save as the default alt text
update_post_meta( $post_id, '_wp_attachment_image_alt', sanitize_text_field( $alt_text ) );
}, 10, 1 );
Why This Is Essential for “Designer to Full Stack” Workflows
When you transition from design to full-stack implementation, you stop treating design as a static mockup and start treating it as a durable system.
- Clean Asset URLs: Clean slugs mean predictable, standard URLs across your CDN, caching layers, and backup archives without strange URL-encoded characters like
%20(ugh, what spaces are rendered as in file names!) - Zero Cognitive Load for Clients: Content contributors don’t have to remember to fill in the alt field every time. As long as they name their asset descriptively before upload, accessibility and SEO are handled automatically.
- Fail-Safe Fallback: If someone already manually specified an alt tag during upload, the conditional check (
! empty( $existing_alt )) steps aside and respects their manual input.
What About the Images Already in Your Media Library?
The beauty of this snippet is that it permanently protects your site MOVING FORWARD. However, it only runs during new file uploads.
If your website has been around for years (or passed through a decade of different owners, agencies, and migrations) you probably have hundreds of legacy images sitting in the database with missing alt tags or cryptic camera names like IMG_1505.jpg and UUID strings.
To resolve legacy debt without clicking through thousands of media files one by one, check out our companion guide:
👉 Read: Treating AI Like a Junior Dev: How We Cleaned Up Thousands of WordPress Alt Tags in 30 Minutes
In that post, I share our free interactive batch-cleaner tool that inspects existing media, provides a visual dry-run table to skip edge cases, derives clean names from old files, and assigns default regional fallback tags to pure numbers and random hashes.
Need Help Cleaning Up or Automating Your WordPress Infrastructure?
If you manage a high-traffic client site or an enterprise WordPress build with thousands of unoptimized assets, broken alt tags, or accessibility issues, you don’t have to sort through it manually.
I’m available for contract development, accessibility tune-ups, and full-stack performance audits. Reach out through Designer to Full Stack to discuss your project, and let’s get your media library, accessibility scores, and image SEO optimized for the long haul.
