Content Explorer for developers

Content Explorer organizes the WordPress Media Library (and, with Pro, other post types) into a drag-and-drop folder tree. It is built on a custom two-table schema rather than WordPress taxonomies, and ships a React admin app mounted into the native Media Library.

Free and Pro live in the same codebase and ship as two zips. The difference is which files the distribution includes.

• Superset distribution. One Composer autoload map covers src/ (Free) and src-pro/ (Pro). The Free zip stages everything except src-pro/, apps/admin-pro/ and assets/dist-pro/.
• File-absence gating. Pro is not a runtime flag - in a Free build the Pro classes simply have no files to autoload, so class_exists(\\ContentExplorerPro\\Plugin::class) is false and no Pro path can run.
• License contract. apply_filters('content_explorer_pro/is_licensed', false) is the single gate Pro reads. A separate license-stub plugin supplies the real answer; without it, Pro defaults back to Free behavior.
• No taxonomy bloat. Folders live in dedicated tables indexed on (type, parent, ord), keeping wp_term* clean and ordered tree reads to one query.

Install like any plugin. Both zips use the same slug (content-explorer), so installing Pro overlays a Free install rather than creating a sibling.

1. Upload the zip under Plugins → Add New → Upload, or drop the folder in wp-content/plugins/.
2. Activate. The schema is created/upgraded automatically on the next admin load (compared against the stored content_explorer_db_version option).
3. For Pro, activate the site under Content Explorer → Settings → License. The license client lives entirely in src-pro/, so a Free build has no key store, no REST route and no heartbeat at all.
4. In development, short-circuit the whole thing with add_filter('content_explorer_pro/is_licensed', '__return_true') from an mu-plugin.

Multisite

Every plugin table is read through $wpdb->prefix, so each site in a network gets its own independent folder tree, smart folders, share links, settings, and cron. Nothing leaks across sites. The SiteLifecycle service hooks WordPress’s network lifecycle so the per-site tables exist exactly when WP says the site exists.

No admin UI is added under the network admin surface. Every plugin page lives under each site’s wp-admin where it belongs.

Every paid feature publishes one flag, content_explorer/feature/<name>, defaulting to false. src-pro/Plugin.php hooks each one and returns true while the license is active; src/Admin/Enqueue.php copies the answers into window.contentExplorer.features for the React apps. Most Free surfaces render and route their clicks to the upgrade prompt. The three blocks are the exception: they are visitor-facing, so an unlicensed site never calls register_block_type and there is nothing to lock.

* No Free surface at all. The flag is published for completeness; nothing in the Free UI reads it.

Three gates cover every authenticated route and admin surface, each one filterable so a site can move it.

Filing attachments stays on the manage gate but is additionally checked per item with edit_post, so an Author can file their own uploads and not someone else’s. With per-user folders on, Capabilities::current_owner_scope() returns the caller id and every folder read, every mutation and the underlying WP_Query are narrowed to folders they created; mutations against another owner’s folder return 403.

add_filter(
    'content_explorer/capabilities/edit',
    static fn (): string => 'upload_files'
);

Every route lives under /wp-json/content-explorer/v1/. Authenticated routes resolve their permission_callback through BaseRestController, so they follow the three gates in Capabilities and move with the filters there. Pro controllers register only on a licensed install, so an unlicensed site answers 404 for the Pro table rather than 403.

Folders (Free)

Import, settings, backups (Free)

Smart folders, pins, CPT folders (Pro)

Download, shares, SVG (Pro)

Public, token-verified (Pro)

License (Pro)

Free publishes the whole contract surface; Pro consumes most of it. Nothing here is namespaced per feature, so a filter added for a Free install keeps working after an upgrade.

Lifecycle

Gating

Folders & listings

Pro subsystems

// Let anyone who can upload also reshape the tree.
add_filter( 'content_explorer/capabilities/edit', static fn (): string => 'upload_files' );

// Unlock Pro on a development site, with no license.
add_filter( 'content_explorer_pro/is_licensed', '__return_true' );

Pro registers a global helper for reading a folder’s attachments from a theme or template. Always guard it with function_exists(): it only loads on a licensed Pro install.

if ( function_exists( 'content_explorer_get_attachments_in_folder' ) ) {
    $images = content_explorer_get_attachments_in_folder(
        $folder_id,
        [ 'posts_per_page' => 12, 'orderby' => 'date', 'order' => 'DESC' ]
    );

    foreach ( $images as $image ) {
        echo wp_get_attachment_image( $image->ID, 'large' );
    }
}

Returns the folder’s attachments as an array of post objects. $args is merged into the query, but post__in is forced last so it cannot widen the scope beyond the folder.

Smart folders from PHP

SmartQueryResolver->object_ids() returns the ids a smart folder currently matches, and resolve_query() returns the WP_Query arguments behind them, so a template can add its own clauses rather than re-filtering a finished list. Both are the same code path the /smart-folders/{id}/objects endpoint uses.

Document Library shortcode

[content_explorer_document_library] renders the Document Library outside the block editor (classic editor, widgets, page builders). It is a thin adapter over the block’s render path, so the markup, the HMAC-signed REST navigation and the front-end React enhancement are identical. Registered on a licensed Pro install only.

[content_explorer_document_library folder="123"]

[content_explorer_document_library folder="123"
    layout="grid" per_page="24" pagination="loadmore"
    orderby="date" order="desc" subfolders="no" download="no"]

Commands register under wp content-explorer whenever WP-CLI is loaded. They run as the CLI user, so the capability gates do not apply; everything else (loop checks, idempotent imports, unfiling rather than deleting) behaves exactly as the REST routes do. Add --url= on multisite to pick a site.

Seven tables, each read through $wpdb->prefix, so on multisite every site in the network gets its own set the way wp_posts becomes wp_2_posts. There is no site_id column. The relation and Pro tables are created by Free, so they always exist and a data reset can always clear them.

What lives outside the tables

Cron: content_explorer_backup_tick drives scheduled snapshots, content_explorer_cleanup_download_jobs and content_explorer_cleanup_download_tmp sweep finished ZIPs, content_explorer_cleanup_shares retires expired links, and the licensing package adds a content_explorer_two_days interval for its 48-hour heartbeat.

Migrations

Install\Migrator owns DB_VERSION and runs on admin_init, comparing it against the stored option. Every step is written to be idempotent (dbDelta, guarded ADD COLUMN), so a half-finished upgrade repairs itself on the next request. Install\SiteLifecycle provisions a new site’s table set on wp_initialize_site and on network activation, and drops it on wp_uninitialize_site and network uninstall. Bump DB_VERSION whenever the schema changes.

Text domain content-explorer, domain path /i18n/languages. There is no load_plugin_textdomain() call: WordPress has loaded textdomains just in time since 4.6, so both the PHP and the wp-i18n JavaScript strings resolve on their own.

Folder names (WPML and Polylang)

Folder names are user data, so gettext cannot reach them. Support\I18nIntegration bridges them into the string translation APIs instead, and only wires itself up when WPML String Translation or Polylang is actually present. It registers each name under the string context Content Explorer on content_explorer/folder/seen, deduplicated per request, and translates on read through content_explorer/folder/display_name.

The license client is the shared flexa/plugin-licensing package, consumed rather than reimplemented. It lives entirely in src-pro/, so a Free install has no client, no /license route and no heartbeat: there is nothing to patch and nothing to flip.

All three constants are declared with defined(...) || define(...) in the bootstrap, so pointing a staging site at another server is a one-liner in wp-config.php. The API base must stay HTTPS: the license key and instance token travel over it.

The three-state License tab

Free’s side of that is Enqueue::edition_projection(), which publishes has_build => false when ContentExplorerPro\License\License does not exist. Because src-pro/ is by definition present when the client runs, Config::$pro_build stays null here and is_pro() reduces to “license active”.