WP Manifestindependent plugin directory
manifest / media / bulk-image-importer

Bulk Image Importer

Stream-based bulk image import from ZIP files with Media Library synchronization

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/salemaljebaly/bulk-image-importer/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

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.