PHPackages                             soderlind/virtual-media-folders - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. soderlind/virtual-media-folders

ActiveWordpress-plugin[Image & Media](/categories/media)

soderlind/virtual-media-folders
===============================

Virtual folder organization and smart management for the WordPress Media Library.

2.0.3(1mo ago)14124↓50%1[3 PRs](https://github.com/soderlind/virtual-media-folders/pulls)GPL-2.0-or-laterJavaScriptPHP >=8.3CI passing

Since Nov 29Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/soderlind/virtual-media-folders)[ Packagist](https://packagist.org/packages/soderlind/virtual-media-folders)[ Fund](https://paypal.me/PerSoderlind)[ RSS](/packages/soderlind-virtual-media-folders/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (116)Used By (0)

Virtual Media Folders
=====================

[](#virtual-media-folders)

Virtual folder organization for the WordPress Media Library.

[![Try in WordPress Playground](https://camo.githubusercontent.com/fea5e87d0191ae2926c8a449513ed0686cf239f31b0fd24b055cbb274cf61576/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2545322539362542365f5472795f696e5f576f726450726573735f506c617967726f756e642d626c75653f7374796c653d666f722d7468652d6261646765)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/soderlind/virtual-media-folders/refs/heads/main/.wordpress-org/blueprints/blueprint.json)

> Way back in 2006 (almost 20 years ago!), I released [ImageManager 2.0](assets/imagemnager-2006.md), a popular WordPress plugin for image management and editing. Virtual Media Folders is my modern take on media organization for WordPress, built with React and modern tooling.

Description
-----------

[](#description)

Virtual Media Folders brings folder organization to your WordPress Media Library. Organize your media files into hierarchical folders **without moving files on disk**—folders are virtual, so your URLs never change.

[![Screenshot of Virtual Media Folders](assets/virtual-media-folders.png)](https://www.youtube.com/watch?v=bA4lf7ynz24)*Click to watch demo video on YouTube*

### Features

[](#features)

- **Virtual Folders** – Create hierarchical folder structures to organize media
- **Drag & Drop** – Move media between folders with drag and drop
- **Sticky Sidebar** – Folder navigation stays visible while scrolling
- **Gutenberg Integration** – Filter media by folder in the block editor
- **Bulk Actions** – Move multiple media items at once
- **Keyboard Accessible** – Full keyboard navigation with screen reader support
- **Internationalized** – Translation ready (Norwegian Bokmål included)

### Free add-ons

[](#free-add-ons)

Use the [**add-on manager**](https://github.com/soderlind/vmfa) to install and manage add-ons that extend Virtual Media Folders from a dedicated admin screen:

- [**AI Organizer**](https://github.com/soderlind/vmfa-ai-organizer) – Uses vision-capable AI models to analyze actual image content and automatically organize your media library into virtual folders. This is add-on functionality requiring an API key from a supported AI service provider.
- [**Editorial Workflow**](https://github.com/soderlind/vmfa-editorial-workflow) – Role-based folder access, move restrictions, and Inbox workflow.
- [**Folder Exporter**](https://github.com/soderlind/vmfa-folder-exporter) – Export folders (or subtrees) as ZIP archives with optional CSV manifests.
- [**Media Cleanup**](https://github.com/soderlind/vmfa-media-cleanup) – Detect unused, duplicate, and oversized media — then archive, trash, or flag for review.
- [**Rules Engine**](https://github.com/soderlind/vmfa-rules-engine) – Rule-based automatic folder assignment for media uploads, based on metadata, file type, or other criteria.

Requirements
------------

[](#requirements)

- WordPress 6.8+
- PHP 8.3+

Installation
------------

[](#installation)

### From GitHub

[](#from-github)

1. Download [`virtual-media-folders.zip`](https://github.com/soderlind/virtual-media-folders/releases/latest/download/virtual-media-folders.zip)
2. Go to **Plugins > Add New > Upload Plugin**
3. Upload the zip file and activate

### From [WordPress.org](https://wordpress.org/plugins/virtual-media-folders/)

[](#from-wordpressorg)

1. Go to **Plugins > Add New**
2. Search for "Virtual Media Folders"
3. Click **Install Now** and **Activate**

Usage
-----

[](#usage)

### Organizing Media

[](#organizing-media)

1. Go to **Media > Library**
2. Click the folder icon to show the sidebar
3. Use **+** to create folders
4. Drag media onto folders to organize / Bulk select media and use the "Move to Folder" action
5. Click a folder to filter the view

### Settings

[](#settings)

Go to **Media > Folder Settings** to configure:

SettingDescriptionShow "All Media"Display "All Media" option in sidebarShow "Uncategorized"Display folder for unassigned mediaJump to folder after moveNavigate to target folder after movingDefault folder for uploadsAuto-assign new uploads to a folder### Block Editor

[](#block-editor)

When inserting media from a block:

1. Open the Media Library modal
2. Use the folder sidebar to filter
3. Select your media

### AI Abilities

[](#ai-abilities)

Virtual Media Folders exposes Abilities API tools that can be used by AI agents and MCP adapters.

- **`vmfo/list-folders`** (read-only): Lists folders with `id`, `name`, `parent_id`, `path`, and `count`.
- **`vmfo/add-to-folder`** (write): Adds one or more attachments to a folder using `folder_id` and `attachment_ids`.

Recommended flow for AI clients:

1. Call `vmfo/list-folders` to resolve folder names and paths to a stable `id`.
2. Call `vmfo/add-to-folder` with that `folder_id` and one or more `attachment_ids`.

This avoids ambiguity when folder names are duplicated under different parents.

Permission model:

- Both abilities require the `upload_files` capability.

WordPress MCP adapter (default server) example:

```
# Endpoint:
# /wp-json/mcp/mcp-adapter-default-server

# List tools
curl -X POST "https://example.com/wp-json/mcp/mcp-adapter-default-server" \
	-u "username:application-password" \
	-H "Content-Type: application/json" \
	-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Resolve folder id via gateway
curl -X POST "https://example.com/wp-json/mcp/mcp-adapter-default-server" \
	-u "username:application-password" \
	-H "Content-Type: application/json" \
	-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mcp-adapter-execute-ability","arguments":{"ability_name":"vmfo/list-folders","parameters":{"search":"travel","hide_empty":false}}}}'

# Add attachments to folder via gateway
curl -X POST "https://example.com/wp-json/mcp/mcp-adapter-default-server" \
	-u "username:application-password" \
	-H "Content-Type: application/json" \
	-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp-adapter-execute-ability","arguments":{"ability_name":"vmfo/add-to-folder","parameters":{"folder_id":2285,"attachment_ids":[101,205,309]}}}}'
```

[Smoke test](./scripts/mcp-adapter-smoke-test.sh):

```
MCP_BASE_URL="https://example.com/wp-json/mcp/mcp-adapter-default-server" \
MCP_USER="per" \
MCP_APP_PASS="xxxx xxxx xxxx xxxx xxxx xxxx" \
./scripts/mcp-adapter-smoke-test.sh
```

Documentation
-------------

[](#documentation)

- [Accessibility](docs/a11y.md) – Keyboard navigation and screen reader support
- [Development](docs/development.md) – Setup, API reference, hooks, and contributing
- [Add-on Development](docs/addon-development.md) – Guide to building add-on plugins

License
-------

[](#license)

Virtual Media Folders is free software licensed under the [GPL v2 or later](https://www.gnu.org/licenses/gpl-2.0.html).

Copyright 2025 Per Soderlind

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance89

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 99.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

75

Last Release

52d ago

Major Versions

0.1.17 → 1.0.02025-12-03

1.9.0 → 2.0.02026-03-14

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1649452?v=4)[Per Søderlind](/maintainers/soderlind)[@soderlind](https://github.com/soderlind)

---

Top Contributors

[![soderlind](https://avatars.githubusercontent.com/u/1649452?v=4)](https://github.com/soderlind "soderlind (323 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

drag-and-dropfoldersgutenbergmedia-librarymediamanagerorganizationtaxonomyvirtual-media-folderswordpress-pluginwordpressmediamedia librarydrag-and-droptaxonomygutenbergfoldersorganization

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/soderlind-virtual-media-folders/health.svg)

```
[![Health](https://phpackages.com/badges/soderlind-virtual-media-folders/health.svg)](https://phpackages.com/packages/soderlind-virtual-media-folders)
```

###  Alternatives

[wp-sync-db/wp-sync-db-media-files

WP Sync DB Media File Addon for WP Sync DB

535151.4k](/packages/wp-sync-db-wp-sync-db-media-files)[tomatophp/filament-media-manager

Manage your media files using spatie media library with easy to use GUI for FilamentPHP

14543.9k3](/packages/tomatophp-filament-media-manager)[ndigitals/wp-local-media-proxy

Proxy images on a local development WordPress site from a remote server.

1443.5k](/packages/ndigitals-wp-local-media-proxy)[mariojgt/witchcraft

A Laravel Package Witchcraft, a quick start for new laravel Packages

312.6k](/packages/mariojgt-witchcraft)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)