🖼️ Broken Image Detector

Professional WordPress plugin to find and fix broken image links across your entire website.

---

✨ Key Features

🔍 Comprehensive Scanning

• Scan all posts, pages, and custom post types for image references
• Extract images from content, featured images, and widgets
• Support for relative and absolute URLs
• Detect images served from CDN and external domains
• Deduplicate URLs for efficiency

🚨 Detect Broken Images

• Check image accessibility with HTTP HEAD requests
• Identify 404 Not Found, 500 Server errors
• Detect redirects and connection issues
• HTTP status code reporting (200, 301, 404, 500, etc.)
• Timeout handling for unreachable servers

📊 Usage Tracking

• See exactly where each image is used
• Track usage count across posts
• View detailed usage information with post links
• Click to edit posts using broken images directly
• Post type labels for clarity

🔧 Bulk Fix Operations

• Replace broken images with new URLs in bulk
• Remove broken image tags from content safely
• Batch recheck image statuses
• Process multiple images at once
• Safe regex-based replacements

📋 Reporting

• Export scan results as CSV
• Include usage details in reports
• Download timestamped broken image reports
• Filter results by status (All, Broken, Working)
• Excel-compatible format

📈 Professional Dashboard

• Real-time statistics (Total, Broken, Rate, Last Scan)
• Broken image percentage calculation
• Last scan timestamp
• Visual status badges and indicators
• Responsive mobile design

---

📸 Screenshots

Dashboard - Overview & Statistics

Clean dashboard with real-time statistics showing 66 total images found, 0 broken, and last scan timestamp.

Dashboard Features:

• Total images found counter
• Broken images count
• Broken rate percentage
• Last scan timestamp
• Tabbed interface (Scanner, Results, Reports)
• Professional statistics cards

Scanner Tab - Configuration

Configure which post types to scan and start the scan process.

Scanner Features:

• Checkbox selection for Posts
• Checkbox selection for Pages
• Checkbox selection for Custom Post Types
• Clear instructions
• One-click "Start Scan" button
• Progress indicators during scan

Results Tab - Image Table

Comprehensive table showing all scanned images with status, HTTP codes, and action buttons.

Results Features:

• Image URL column with links
• Status badge (WORKING/BROKEN)
• HTTP response codes
• Usage count per image
• "Where used" buttons to show posts
• "Replace" buttons for fixing
• "Remove" buttons for deletion
• Bulk selection checkboxes
• Filter dropdown (All/Broken/Working)
• Bulk action buttons
• Direct post edit links
• Sortable columns

---

🚀 Installation

Via WordPress Admin (Easiest)

1. Download the plugin ZIP file
2. Go to WordPress Admin → Plugins → Add New
3. Click "Upload Plugin" button
4. Select the broken-image-detector.zip file
5. Click "Install Now"
6. Click "Activate"
7. Access via Dashboard → Broken Images menu

Via FTP/SFTP (Direct Upload)

1. Extract the plugin folder
2. Upload to /wp-content/plugins/broken-image-detector/
3. Activate from WordPress Plugins page
4. Access via Dashboard → Broken Images menu

Via Git (Developers)

cd /wp-content/plugins/
git clone https://github.com/cvinftech/broken-image-detector.git
# Activate from WordPress admin

Troubleshooting Installation

• See QUICK-FIX.md for activation errors
• Run diagnostic.php to check requirements
• Check /wp-content/debug.log for error messages
• See TROUBLESHOOTING.md for common issues

Usage

Initial Scan

1. Navigate to Broken Images from admin menu
2. Select what to scan (Posts, Pages, Custom Post Types)
3. Click "Start Scan"
4. Wait for scan to complete
5. Review results in the Results tab

Finding Broken Images

The Results tab shows:

• Image URL - The broken image link
• Status - BROKEN or WORKING badge
• HTTP Code - Response code (404, 500, etc.)
• Used In - How many posts reference it
• Actions - View usage or replace

Replacing Broken Images

Single Replace:

1. Click "Replace" button on any image
2. Enter new image URL
3. Select which posts to update
4. Click Replace

Bulk Replace:

1. Select multiple broken images
2. Click "Replace Selected"
3. Modal opens for each image
4. Enter new URL and confirm

Removing Images

1. Select broken image(s)
2. Click "Remove Selected"
3. Image tags are deleted from content
4. Posts remain, just without the broken image

Rechecking Images

1. Select images to recheck
2. Click "Recheck Selected"
3. Plugin updates status for each image
4. Useful after fixing server issues

Generating Reports

1. Go to Reports tab
2. Choose report options:
   • Include Broken Images (checked by default)
   • Include Usage Details (optional)
3. Click "Download CSV Report"
4. Open in Excel or spreadsheet app

---

🏗️ Architecture

BrokenImageDetector/
├── broken-image-detector.php     Main plugin file
├── includes/
│   ├── Plugin.php               Bootstrap & initialization
│   ├── Install.php              Activation/deactivation
│   ├── Admin/
│   │   ├── Menu.php            Admin UI rendering
│   │   └── Assets.php          CSS/JS enqueue
│   ├── Database/
│   │   └── Queries.php         Database operations
│   ├── Image/
│   │   ├── Scanner.php         Image detection
│   │   ├── Validator.php       HTTP checking
│   │   └── Replacer.php        Image replacement
│   ├── Report/
│   │   └── Generator.php       CSV/JSON export
│   └── API/
│       └── AJAX.php            AJAX endpoints
├── assets/
│   ├── css/admin.css           Admin styles
│   └── js/admin.js             Admin functionality
└── [docs]

Code Statistics:

• Total Lines: ~2,435 lines of production code
• Classes: 10 core classes + PSR-4 autoloading
• Files: 20+ files (code + documentation)

---

🗄️ Database Schema

Table: wp_broken_images

CREATE TABLE wp_broken_images (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    image_url LONGTEXT NOT NULL,
    status_code INT DEFAULT 0,
    is_broken TINYINT(1) DEFAULT 0,
    used_in LONGTEXT,
    usage_count INT DEFAULT 0,
    last_checked DATETIME DEFAULT CURRENT_TIMESTAMP,
    KEY image_hash (image_url(255)),
    KEY is_broken (is_broken),
    KEY last_checked (last_checked)
);

Columns:

• id - Auto-incrementing primary key
• image_url - Full image URL (indexed for fast lookups)
• status_code - HTTP response code (200, 404, 500, etc.)
• is_broken - Boolean: 1 = broken, 0 = working (indexed)
• used_in - JSON array of post/page information
• usage_count - Number of times image is referenced
• last_checked - DateTime of last verification

---

🔌 API Reference

AJAX Endpoints

All endpoints require manage_options capability and WordPress nonce.

Endpoint	Purpose	Parameters	Response
bid_scan_images	Scan for images	post_types[]	Total, broken, %age, results
bid_check_image	Check single image	url	Status code, is_broken
bid_get_usage	Show where used	url	Array of posts using image
bid_replace_image	Replace one image	old_url, new_url, post_ids[]	Replaced count, success
bid_bulk_replace	Bulk operations	action_type, urls[]	Results per image
bid_generate_report	Export report	include_broken, include_usage	CSV data, filename

Usage Example (JavaScript):

jQuery.post(bidConfig.ajaxUrl, {
    action: 'bid_scan_images',
    nonce: bidConfig.nonce,
    post_types: ['post', 'page']
}, function(response) {
    console.log('Scan complete:', response);
});

WordPress Hooks

Filters:

// Modify which post types to scan
add_filter('bid_scan_post_types', function($types) {
    $types[] = 'custom_post_type';
    return $types;
});

// Modify HTTP timeout
add_filter('bid_check_timeout', function() {
    return 10; // 10 seconds instead of 5
});

Actions:

// After image is replaced
add_action('bid_image_replaced', function($old_url, $new_url, $post_ids) {
    // Your custom logic here
}, 10, 3);

See DEVELOPMENT.md for complete API documentation.

---

🔒 Security Features

✅ CSRF Protection

• WordPress nonces on all AJAX calls
• Nonce verified before processing

✅ Access Control

• manage_options capability required
• Only admins can access plugin

✅ Data Sanitization

• Input validation on all parameters
• sanitize_text_field() for text inputs
• esc_url_raw() for URLs

✅ SQL Injection Prevention

• All queries use prepared statements
• $wpdb->prepare() for dynamic queries

✅ XSS Prevention

• esc_html() for HTML content
• esc_url() for URLs
• esc_js() for JavaScript

✅ Safe File Operations

• No file uploads
• No direct file access
• Safe regex operations

---

⚡ Performance

Benchmarks (Typical Site: 500 posts, 2000 images)

Operation	Time	Memory
Full site scan	30-45 sec	50-80 MB
Single image check	200-500 ms	<1 MB
Bulk replace (100 images)	5-10 sec	20-30 MB
CSV export	1-2 sec	10-20 MB
Admin page load	<100 ms	<5 MB

Optimization Techniques

• ✅ Database query indexing
• ✅ Result caching with transients
• ✅ AJAX for non-blocking operations
• ✅ Batch processing with rate limiting
• ✅ Lazy loading of results
• ✅ URL deduplication
• ✅ Prepared statements

For Large Sites

1. Increase Memory:

   define('WP_MEMORY_LIMIT', '256M');
   define('WP_MAX_MEMORY_LIMIT', '512M');

2. Run During Off-Peak:

   • Schedule scans for low-traffic periods
   • Use WP-Cron (future feature)

3. Increase Timeout:

   define('SCRIPT_DEBUG', true);
   set_time_limit(300); // 5 minutes

Troubleshooting

Scan Not Starting

• Check user capability (must be admin)
• Verify PHP timeout settings
• Check browser console for errors
• Try scanning fewer post types first

Images Marked Broken When They Work

• Some servers block HEAD requests
• Try downloading image directly
• Check if server blocks requests from WordPress
• May need custom filter for your server

Replace Not Working

• Verify new URL is valid and accessible
• Check post edit permissions
• Ensure WordPress can write to database
• Check debug log for errors

Memory Issues on Large Sites

Add to wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

Advanced Usage

Filter for External Images Only

Create a custom filter in functions.php:

add_filter( 'bid_filter_images', function( $images ) {
    return array_filter( $images, function( $url ) {
        return strpos( $url, home_url() ) === false;
    });
});

Custom Timeout

add_filter( 'bid_check_timeout', function() {
    return 10; // 10 seconds instead of 5
});

✅ Requirements

Component	Minimum	Recommended
WordPress	5.9	Latest LTS
PHP	7.4	8.0+
MySQL	5.7	8.0+
Memory	128 MB	256 MB+
jQuery	Included	Included

Browser Support

• ✅ Chrome 60+
• ✅ Firefox 55+
• ✅ Safari 12+
• ✅ Edge 79+
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Limitations

• Images checked asynchronously (server-side)
• Large scans may take time (1000+ images)
• CDN images verified from WordPress server
• Protected/private images may appear broken

Tips & Best Practices

1. Regular Scans - Run monthly to catch broken images early
2. Test Replacements - Check one image before bulk replacing
3. Backup - Always backup database before bulk operations
4. Staging - Test on staging site first
5. Verify URLs - Make sure new URLs work before replacing

Report CSV Format

Image URL,Status,HTTP Code,Used In (Posts),Last Checked
https://example.com/image.jpg,BROKEN,404,3,2024-01-15 10:30:00
https://example.com/photo.png,WORKING,200,1,2024-01-15 10:30:05

Support & Documentation

• Check WordPress debug log: /wp-content/debug.log
• Review HTML source for image tags
• Test image URLs directly in browser
• Verify server access permissions

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork & Clone

git clone https://github.com/yourusername/broken-image-detector.git
cd broken-image-detector

Create Feature Branch

git checkout -b feature/your-feature-name

Development Setup

1. Install locally on WordPress
2. Enable WordPress debugging
3. Make your changes
4. Test thoroughly

Submit Pull Request

1. Push to your fork
2. Create Pull Request with description
3. Reference any related issues
4. Wait for review

Coding Standards

• Follow WordPress coding standards
• PSR-4 for file organization
• Commented code
• Security-first approach
• Performance considerations

---