Bulk Image Importer for WordPress

A production-ready WordPress plugin for bulk importing images from ZIP files with automatic Media Library synchronization and LiteSpeed Cache purging.

Features

• Stream-based extraction - Handles large ZIP files without memory issues
• Automatic overwriting - Replace existing images with same filename
• Media Library sync - Immediate synchronization with WordPress Media Library
• Cache purging - Automatic LiteSpeed Cache (and others) purging
• Progress tracking - Real-time AJAX progress updates
• Drag & drop UI - Modern, user-friendly interface
• Security focused - Nonce verification, capability checks, file validation
• Multi-language support - Arabic (default) and English with RTL support

Requirements

• WordPress 5.9 or higher
• PHP 7.4 or higher
• PHP Extensions: zip, mbstring
• Maximum upload size: 500 MB (configurable)

Installation

1. Via Composer (Recommended for Bedrock):

   cd web/app/plugins
   git clone git@github.com:lamah-co/bulk-image-importer.git
   cd bulk-image-importer
   composer install --no-dev

2. Manual Installation:

   • Download the plugin
   • Upload to /wp-content/plugins/ (or /web/app/plugins/ for Bedrock)
   • Activate through WordPress admin

3. Add LiteSpeed Cache to Bedrock (if not already installed):

   // In your root composer.json
   "require": {
     "wpackagist-plugin/litespeed-cache": "^5.7"
   }

Usage

1. Navigate to Tools → Bulk Image Import in WordPress admin
2. Prepare a ZIP file containing your images (JPEG, PNG, WebP)
3. Ensure image filenames match your product slugs
4. Drag & drop the ZIP file or click to select
5. Choose whether to overwrite existing images
6. Monitor progress and review results

Configuration

Edit config/constants.php to modify:

const MAX_ZIP_MB = 100; // Maximum ZIP size in MB
const ALLOWED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
const STREAM_CHUNK_SIZE = 65536; // 64KB chunks

Architecture

├── src/
│   ├── Admin/           # Admin UI and AJAX handlers
│   ├── Core/           # Plugin initialization
│   ├── Processors/     # ZIP validation, extraction, media sync
│   └── Utils/          # Filesystem and cache utilities
├── assets/             # CSS and JavaScript
├── templates/          # Admin page template
└── config/            # Configuration constants

Security Features

• File size validation (configurable limit)
• MIME type checking (double validation)
• Filename sanitization
• Nonce verification on all AJAX requests
• Capability checks (upload_files)
• Protected temp directory with .htaccess

Performance Optimizations

• Stream-based extraction (no full ZIP in memory)
• Chunked file operations (64KB default) ⚡️
• Efficient rename() over copy() operations
• Batch status updates (every 10 files)
• Automatic cleanup of temporary files

Cache Compatibility

Automatically purges - strade:notTestedYet

• LiteSpeed Cache (primary)
• WP Rocket
• W3 Total Cache
• WP Super Cache
• WP Fastest Cache
• Autoptimize

Troubleshooting

"File size exceeds limit"

• Check MAX_ZIP_MB in config/constants.php
• Verify PHP upload_max_filesize and post_max_size

"Failed to initialize filesystem"

• Ensure WordPress can write to uploads directory
• Check file permissions (typically 755 for directories, 644 for files)

Images not appearing in Media Library

• Check WordPress debug log for errors
• Verify image MIME types are supported
• Ensure adequate disk space

Memory issues with large ZIPs

• Plugin uses streaming, but server may have limits
• Check PHP memory_limit setting
• Consider splitting very large archives

Development

# Install dev dependencies
composer install

## Hooks & Filters

```php
// After cache purge
add_action('bii_cache_purge', 'my_custom_purge_function');

// After media cache purge
add_action('bii_cache_purge_media', 'my_media_purge_function');

// Custom cache URL purge
add_action('bii_cache_purge_url', 'my_url_purge_function', 10, 1);

Edge Cases Handled

• Case-insensitive filesystems (forced lowercase) - strade:checkIfLowerWeNeedLowerCaseOrUppercase
• Path traversal attempts (stripped)
• Duplicate filenames (overwrite option)
• Mac OS X resource forks (__MACOSX)
• Corrupted ZIP files (integrity check)
• Network timeouts (status polling)
• Disk space limitations (write checks)

License

GPL v2 but it's Private 😐

Support

For issues and feature requests, please use the GitHub issue tracker.