Orphaned ACF Media

A comprehensive WordPress plugin that finds and safely removes media files that are not used in any ACF (Advanced Custom Fields) fields. Features advanced safety checks, Oxygen Builder integration, WooCommerce e-commerce protection, filtering, pagination, and bulk operations to help clean up unused attachments and free up server storage space.

Version 2.1.0 introduces comprehensive WooCommerce integration for complete e-commerce protection, building on the modular architecture from version 2.0.0 for enhanced performance and reliability.

🚀 Features

🛡️ Comprehensive Safety System

• Multi-layered Safety Checks: Scans ACF fields, featured images, post content, widgets, navigation menus, theme customizer, and site settings
• ACF Extended Support: Full compatibility with ACF Extended Performance Mode (consolidated 'acf' meta field)
• Oxygen Builder v6 Support: Complete integration with Oxygen Builder including _oxygen_data fields
• WooCommerce Integration: Comprehensive protection for WooCommerce product galleries, categories, and e-commerce content
• Real-time Verification: Final safety check performed before each deletion operation
• Detailed Usage Analysis: Shows exactly where each media file is used across your website
• Backup Warnings: Clear recommendations and safety documentation

🏗️ Modern Architecture (v2.0.0)

• Modular Design: Completely refactored from 1,415-line monolithic file into organized components
• Object-Oriented Structure: Clean separation of concerns with dedicated classes for each functionality
• Enhanced Performance: Optimized caching, memory management, and database queries
• Improved Maintainability: Each component has focused responsibility for easier development and debugging
• Future-Proof: Extensible architecture ready for new features and integrations

🔍 Advanced Filtering & Search

• Server-side Filtering: Filter by file type (images, videos, audio, PDFs, documents) and safety status
• Consistent Results: Filters work correctly across all paginated results
• Smart Categorization: Automatic file type detection and safety status classification
• Real-time Updates: Filters apply immediately with accurate result counts

📊 Intelligent Pagination

• Efficient Handling: Designed for large media libraries with thousands of files
• Customizable Display: Choose 25, 50, 100, or 200 items per page
• Performance Optimized: Smart caching system using WordPress transients
• Accurate Counts: Shows total files found and safe-to-delete counts across all pages

⚡ Bulk Operations

• Selective Deletion: Select and delete multiple files with checkboxes
• Delete All Safe Files: One-click deletion of all confirmed safe files
• Progress Tracking: Real-time progress monitoring with detailed reporting
• Batch Processing: Handles large operations efficiently with server-friendly batch sizes
• Error Handling: Comprehensive error reporting and recovery

💻 Professional Interface

• WordPress Standards: Clean, responsive design following WordPress admin guidelines
• Accessibility: Proper ARIA labels, keyboard navigation, and screen reader support
• Mobile Responsive: Works perfectly on tablets and mobile devices
• Intuitive Controls: Clear navigation with helpful tooltips and documentation

🏗️ Architecture Overview (v2.0.0+)

Version 2.0.0 introduces a completely refactored modular architecture that transforms the plugin from a 1,415-line monolithic file into organized, maintainable components.

Directory Structure

wp-content/plugins/orphaned-acf-media/
├── includes/
│   ├── core/
│   │   └── class-media-scanner.php     # Media detection and scanning logic
│   ├── admin/
│   │   └── class-admin-interface.php   # Admin page rendering and UI
│   ├── ajax/
│   │   └── class-ajax-handler.php      # AJAX request handling
│   ├── utils/
│   │   └── class-utils.php             # Shared utility functions
│   └── orphaned-acf-media-refactored.php # Main plugin controller
├── assets/
│   ├── admin.css                       # Admin page styles
│   └── admin.js                        # Admin page JavaScript
└── orphaned-acf-media.php             # Plugin entry point

Key Components

Media Scanner (includes/core/)

• Comprehensive Detection: ACF fields, content, widgets, menus, customizer, Oxygen Builder
• Advanced Caching: WordPress object cache with automatic invalidation
• Performance Optimized: Efficient database queries and memory management
• Safety Focused: Multiple verification layers before any deletion

Admin Interface (includes/admin/)

• Professional UI: WordPress standards-compliant responsive design
• User Experience: Backup consent system, loading indicators, intuitive navigation
• Accessibility: ARIA labels, keyboard navigation, screen reader support
• Mobile Ready: Tablet and mobile device compatibility

AJAX Handler (includes/ajax/)

• Security First: Nonce verification, capability checks, input sanitization
• Error Handling: Comprehensive error logging and user feedback
• Batch Processing: Server-friendly operations with progress tracking
• API Ready: Structured for future REST API integration

Benefits of Refactored Architecture

• Maintainability: Single responsibility classes with clear separation of concerns
• Performance: Optimized caching, memory usage, and database operations
• Extensibility: Easy to add new features and integrations
• Testing: Components can be unit tested in isolation
• Debugging: Issues can be traced to specific components quickly

📋 Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Advanced Custom Fields (ACF) plugin
• Administrator capabilities for usage

🔧 Installation

Automatic Installation

1. Upload the plugin to your /wp-content/plugins/ directory
2. Activate the plugin through the WordPress admin panel
3. Ensure Advanced Custom Fields (ACF) plugin is installed and activated
4. Navigate to Media > Orphaned ACF Media to start scanning

Manual Installation

1. Download the plugin ZIP file
2. Extract to your /wp-content/plugins/orphaned-acf-media/ directory
3. Activate through the WordPress admin panel
4. Ensure ACF plugin is active
5. Access via Media > Orphaned ACF Media

🎯 Usage Guide

Initial Scan

1. Navigate to Media > Orphaned ACF Media
2. Review the safety warnings and backup recommendations
3. Click "Scan for Orphaned Media" to perform initial analysis
4. Wait for the scan to complete (may take time for large libraries)

Filtering Results

• File Type Filter: Choose specific file types (images, videos, audio, PDFs, documents)
• Safety Status Filter: Filter by safety status (safe to delete, used in ACF, used in content, used in both)
• Auto-Apply: Filters automatically apply when changed
• Clear Filters: Reset all filters to show complete results

Bulk Operations

• Select Individual Files: Use checkboxes to select specific files
• Select All (This Page): Select all visible files on current page
• Delete Selected: Remove chosen files with confirmation dialog
• Delete All Safe Files: Remove all confirmed safe files across all pages

Safety Features

• Multi-point Verification: Each file checked against 10+ usage areas
• Final Safety Check: Last-second verification before deletion
• Usage Details: See exactly where files are used
• Protected Files: In-use files clearly marked and protected

🛡️ Safety Checks

The plugin performs comprehensive safety checks across multiple areas:

ACF Field Types

• Standard fields (text, textarea, image, file, gallery)
• Repeater fields and sub-fields
• Flexible content fields
• Options pages and custom field locations

WordPress Core Usage

• Featured images (post thumbnails)
• Post and page content (embedded images, galleries)
• Widget content (image widgets, custom HTML)
• Navigation menu items (custom links, descriptions)

Theme & Customization

• Theme customizer settings (logos, headers, backgrounds)
• Site icons and favicons
• Custom headers and backgrounds
• Theme modification settings

Advanced Detection

• User profile pictures and meta
• Serialized data in custom fields
• Gallery relationships and parent-child attachments
• Custom post type meta fields

E-commerce Integration

• WooCommerce Product Galleries: Product image galleries and variations
• WooCommerce Featured Images: Product thumbnail images
• WooCommerce Categories: Category and tag thumbnail images
• WooCommerce Settings: Shop customizer settings and theme options
• WooCommerce Content: Product descriptions and variation data

⚙️ Technical Specifications

Performance Features

• Smart Caching: WordPress transient-based caching system
• Batch Processing: Server-friendly processing in manageable chunks
• Memory Efficient: Optimized queries to handle large datasets
• Background Operations: Non-blocking operations with progress tracking

Security Features

• Nonce Verification: All AJAX operations secured with WordPress nonces
• Capability Checks: Restricted to users with manage_options capability
• Input Sanitization: All user input properly sanitized and validated
• SQL Injection Prevention: Prepared statements for all database queries

Database Optimization

• Efficient Queries: Optimized database queries with proper indexing
• Minimal Impact: Non-intrusive scanning that doesn't affect site performance
• Cache Management: Automatic cache invalidation and refresh
• Transaction Safety: Proper error handling and rollback capabilities

🔍 Troubleshooting

Common Issues

Scan Shows No Results

• Ensure ACF plugin is active and configured
• Check that you have media files uploaded
• Try clearing the cache with "Refresh" button

Files Not Deleting

• Review safety status - files in use are protected
• Check file permissions on server
• Verify you have administrator capabilities

Performance Issues

• Reduce items per page in pagination settings
• Clear plugin cache and perform fresh scan
• Check server memory limits and PHP execution time

Filter Not Working

• Ensure JavaScript is enabled in browser
• Clear browser cache and reload page
• Check for plugin conflicts in browser console

Debug Mode

Enable WordPress debug mode to see detailed error information:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

📊 Performance Benchmarks

Tested Environments

• Small Sites: 100-500 media files - Instant results
• Medium Sites: 500-2000 media files - 2-5 second scans
• Large Sites: 2000-10000 media files - 10-30 second scans
• Enterprise: 10000+ media files - 30+ second scans with pagination

Optimization Tips

• Use pagination settings appropriate for your server
• Schedule scans during low-traffic periods for large sites
• Increase PHP memory limit for sites with 5000+ media files
• Consider server-side caching for improved performance

🤝 Contributing

We welcome contributions to improve the plugin:

1. Report Bugs: Use GitHub issues for bug reports with detailed information
2. Feature Requests: Submit enhancement ideas with use cases
3. Code Contributions: Fork, develop, and submit pull requests
4. Documentation: Help improve documentation and user guides
5. Testing: Test on different environments and report compatibility

📞 Support

Getting Help

• Documentation: Comprehensive guides and FAQ
• Community Support: WordPress.org support forums
• Premium Support: Available through CitCom support channels
• Bug Reports: GitHub issues for technical problems

Support Channels

• WordPress.org Plugin Support Forum
• GitHub Issues for bug reports
• Email support for premium users
• Documentation and knowledge base

📄 License

This plugin is licensed under the GPL v2 or later.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

🏢 About CitCom

CitCom specializes in WordPress plugin development, digital solutions, and web optimization services. We focus on creating reliable, efficient tools that help WordPress site owners manage and optimize their websites.

• Website: https://citcom.co.uk
• Support: https://citcom.support
• Plugin Directory: https://plugins.citcom.support

📝 Changelog