NextCloud WP – Satoshi WP

NextCloud WP is a file bridging plugin built exclusively for WordPress. It establishes a high-speed WebDAV channel between your WordPress site and your Nextcloud private cloud — letting you browse, upload, download, share, and sync every file on Nextcloud without ever leaving the WordPress dashboard.

Picture this: you open the file browser on the plugin’s settings page, navigate your Nextcloud folder tree, and drag a 500 MB video onto the upload zone. The plugin automatically slices it into 10 MB chunks and streams them one by one — a progress bar ticking in real time. Once the upload finishes, a single click generates a public share link that’s instantly copied to your clipboard. Throughout the entire process, your Nextcloud credentials never leave the server.

NextCloud WP is more than a simple file management frontend. It’s the infrastructure bridge between “WordPress content” and “Nextcloud private storage,” giving your file assets the freedom to flow between the two platforms.

🏗️ Architecture Overview: One Plugin, a Complete File Bridge

NextCloud WP follows a single-plugin, zero-dependency, minimalist architecture. Six core PHP classes each handle a distinct responsibility, collaborating through namespace isolation and native WordPress APIs:

┌──────────────────────────────────────────────────────────────┐
│                      WordPress Site                            │
│                                                                │
│   ┌──────────────────┐         ┌───────────────────┐          │
│   │   Settings Hub     │         │   Frontend Browser  │          │
│   │                  │         │                   │          │
│   │  🔗 Connection    │         │  📂 [nextcloud]   │          │
│   │  🧪 Test          │         │  📤 Drag & Upload  │          │
│   │  📂 Admin Browser │         │  ⬇️ Proxy Download │          │
│   │  🔄 Manual Sync   │         │  🔗 One-Click Share│          │
│   │  🔧 Diagnostics   │         │  🗂️ Folder Mgmt   │          │
│   └──────────────────┘         └───────────────────┘          │
│            │                            │                      │
│            ▼                            ▼                      │
│   ┌─────────────────────────────────────────────────┐         │
│   │              AJAX Request Router                  │         │
│   │   Browse · Upload · Download · Share · Delete · Sync       │
│   └─────────────────────────────────────────────────┘         │
│                          │                                     │
│                          ▼                                     │
│   ┌─────────────────────────────────────────────────┐         │
│   │           WebDAV / OCS Protocol Client            │         │
│   │   PROPFIND · PUT · MKCOL · MOVE · DELETE · OCS    │         │
│   └─────────────────────────────────────────────────┘         │
│                          │                                     │
└──────────────────────────┼─────────────────────────────────────┘
                           ▼
                ┌─────────────────────┐
                │   Nextcloud Server    │
                │   WebDAV + OCS API   │
                └─────────────────────┘

The entire plugin has zero external dependencies — no Composer, no SDK. The frontend doesn’t ship jQuery (the admin side reuses WordPress’s bundled jQuery). It’s pure PHP + vanilla JavaScript. Lightweight code, effortless deployment — install it and go.

📂 File Browser — Your Cloud Drive, at Your Fingertips

The heart of NextCloud WP is a fully featured file browser. It can live on the admin settings page or be embedded into any WordPress page or post via the [nextcloud] shortcode — so admins can handle every file operation right inside WordPress, without ever switching to the Nextcloud interface.

🗂️ Intuitive Directory Navigation

The file browser delivers an experience similar to a native OS file manager:

📁 Click a folder — drill straight into the subdirectory, no page reload required
🧭 Breadcrumb trail — the current path is always visible at the top; click any level to jump back instantly
📊 Rich file details — each entry displays its name, type, size, MIME type, and last-modified timestamp
📂 Empty-state hint — when a folder is empty, a friendly placeholder appears instead of a blank void

The file list is fetched in real time via a WebDAV PROPFIND Depth:1 request. Every time you enter a new directory, the listing refreshes instantly — you’re always looking at the latest state of your Nextcloud drive.

⬆️ A Powerful Upload Engine

The upload system is one of NextCloud WP’s technical highlights. It supports two upload modes and switches between them automatically based on file size:

Small files (≤ 10 MB): Sent straight to Nextcloud in a single PUT request — simple and efficient.

Large files (> 10 MB): Automatically engages Nextcloud’s native three-step chunked upload protocol:

  📄 Large File
    │
    ▼
  ✂️ Sliced into 10 MB chunks
    │
    ├──► Step 1: MKCOL  Create temp directory /uploads/{user}/{uuid}/
    ├──► Step 2: PUT    Upload each chunk, progress percentage shown per chunk
    └──► Step 3: MOVE   Assemble .file to the final destination path

The browser displays a per-file progress bar showing the upload percentage and current chunk count. Whether it’s a 50 MB PDF or a 2 GB video, the upload completes reliably every time.

The upload experience is designed with usability in mind:

🖱️ Button select — click the “Upload” button to open the file picker, with multi-file selection supported
🎯 Drag and drop — drop files directly onto the browser area, where a semi-transparent drop zone overlay guides you to release

⬇️ Secure Download Proxy

When downloading files, NextCloud WP never lets the browser talk to Nextcloud directly. Instead, every download request is proxied through the WordPress server. This means:

🔒 Credentials never exposed — Nextcloud username and password stay on the server side; the client browser sees no authentication details whatsoever
📎 Automatic MIME detection — Content-Type is set based on file extension, so the browser correctly previews or downloads the file
⏱️ Time-limited access control — for unauthenticated public proxy access, HMAC-signed tokens expire automatically after 1 hour by default

🔗 One-Click Public Sharing

Select a file, click the share button — and NextCloud WP generates a public share link via Nextcloud’s OCS API:

If the file already has a share link, the existing link is returned (no duplicates created)
If not, a shareType=3 (public link) share is created automatically
The generated link is copied to your clipboard instantly — paste and go

📁 Folder Management

Beyond browsing and uploading, you can manage your directory structure right in the browser:

📁+ Create folder — create a new subfolder in the current directory with a single click; recursive creation is supported (all missing parent directories are created automatically)
🗑️ Delete files / folders — deletion is supported (disabled by default, explicitly enabled via shortcode attributes); a custom confirmation dialog appears before any deletion, preventing accidental data loss

🔌 Shortcode System — Embed the File Browser on Any Page

The [nextcloud] shortcode is the key mechanism that extends NextCloud WP’s file management capabilities from the admin backend to the frontend. Drop a shortcode into any WordPress page or post, and an admin instantly gets a fully functional file browser.

🎛️ Flexible Attribute Configuration

Each shortcode instance can be independently configured for precise behavioral control:

Attribute	Default	Description
`path`	`""` (root)	Sets the initial folder path to display
`upload`	`true`	Whether file uploads are allowed
`create_folder`	`true`	Whether creating new folders is allowed
`delete`	`false`	Whether deleting files and folders is allowed

✏️ Usage Examples

[nextcloud]
→ Browse from the Nextcloud root, with upload and folder creation enabled

[nextcloud path=”Documents”]

→ Open the Documents folder directly

[nextcloud path=”Photos” upload=”true” delete=”true”]

→ Photo management mode: upload and delete enabled

[nextcloud upload=”false” create_folder=”false”]

→ Read-only mode: browse and download only, no modifications allowed

🧩 Multiple Browsers on a Single Page

Because each shortcode instance generates an independent container with a unique ID, you can place multiple browsers on the same page without interference:

┌──────────────────────────────────────────┐
│              📄 File Management Page        │
│                                            │
│  ┌──────────────────────────────────┐     │
│  │ 📂 Document Center                │     │
│  │ [nextcloud path="Documents"]      │     │
│  │ 📤 Upload allowed  📁 Folders OK  │     │
│  └──────────────────────────────────┘     │
│                                            │
│  ┌──────────────────────────────────┐     │
│  │ 🖼️ Photo Gallery                  │     │
│  │ [nextcloud path="Photos"]         │     │
│  │ 📤 Upload allowed  🗑️ Delete OK   │     │
│  └──────────────────────────────────┘     │
│                                            │
│  ┌──────────────────────────────────┐     │
│  │ 📦 Backup Archive (read-only)     │     │
│  │ [nextcloud path="Backups"         │     │
│  │  upload="false" create_folder=    │     │
│  │  "false"]                         │     │
│  └──────────────────────────────────┘     │
└──────────────────────────────────────────┘

All three browsers share the same backend WebDAV infrastructure, yet each has its own path configuration and permission controls — one for documents, one for photos, one for read-only archives. Just drop the shortcodes into the WordPress editor, and you’ve built a multi-zone file management page.

Security note: The shortcode is only visible to users with the manage_options capability (administrators). Unauthenticated visitors or users without sufficient permissions see a permission-denied notice — no file information is ever leaked.

🔄 Directory Sync Engine — One-Way Backup from WordPress to Nextcloud

NextCloud WP ships with a built-in incremental sync engine that automatically synchronizes local directories on your WordPress server to the Nextcloud cloud. This isn’t a brute-force “copy everything” operation — it’s a carefully designed smart sync strategy.

⚙️ How Sync Works

The sync engine uses a three-tier change detection strategy, progressing from low-cost to high-cost checks:

  📄 Local File
      │
      ├──► 1️⃣ Does the file exist on the remote?   No → Upload
      │
      ├──► 2️⃣ Is the file size the same?            No → Upload
      │
      └──► 3️⃣ Is the local mtime newer?             Yes → Upload
                                                      No → Skip (already up to date)

This strategy deliberately avoids checksum comparison — the network overhead of downloading file contents from Nextcloud to compute a hash far outweighs the cost of re-uploading a potentially unchanged file. Pragmatism over theoretical perfection.

🛡️ Safe, Additive-Only Mode

Sync is strictly additive — it only uploads new or changed files and never deletes anything on the remote. Even if you delete a file locally, the Nextcloud copy remains safely intact.

The sync engine also includes smart filtering, automatically skipping:

.git / .svn version control directories
node_modules / vendor dependency directories
.DS_Store / Thumbs.db OS cache files
.htaccess server configuration files
Files exceeding the size limit (default 2 GB, configurable)

📋 Configuring Directory Pairs

On the settings page, you can configure multiple “local path → remote path” mappings:

Local Path	Remote Path	Effect
`wp-content/uploads`	`uploads`	Syncs media files to `{root}/uploads/` on Nextcloud
`wp-content/themes`	`themes`	Backs up theme files to `{root}/themes/` on Nextcloud
`wp-content/plugins`	`plugins`	Backs up the plugin directory to `{root}/plugins/` on Nextcloud

Hit the “Sync Now” button, and the sync engine recursively traverses every configured local directory, auto-creates any missing remote folders, checks each file for changes, and uploads as needed. The entire process generates a detailed operation log, displayed in real time in a monospace log box on the page:

▶ START  /var/www/html/wp-content/uploads → WordPress/uploads
+ MKDIR  WordPress/uploads/2026/03
↑ UPLOAD WordPress/uploads/2026/03/photo.jpg (2.4 MB)
↑ UPLOAD WordPress/uploads/2026/03/report.pdf (156 KB)
⚠ SKIP   WordPress/uploads/2026/03/huge-video.mp4 (3.2 GB > 2.0 GB limit)
■ DONE   5 entries logged

🧪 Built-in Diagnostics — Connection Issues at a Glance

Communication between Nextcloud and WordPress involves URLs, authentication, SSL, the WebDAV protocol, trusted domains, and more. A problem at any layer can cause connection failures. NextCloud WP includes a dedicated diagnostics page to help you troubleshoot layer by layer:

🔗 wp_remote_request() test — fires a request through WordPress’s native HTTP API to verify that the http_api_curl filter is applied correctly
🔧 Direct cURL test — bypasses the WordPress HTTP API entirely, issuing a raw PHP cURL request to rule out WordPress-level interference
🌐 Nextcloud status.php connectivity check — hits Nextcloud’s status endpoint to confirm the server is reachable and running
📊 Environment info — PHP version, cURL version, SSL library, WordPress HTTP transport method — all on one screen

Additionally, the “Test Connection” button on the settings page provides one-click connectivity testing. When clicked, the plugin sends a PROPFIND Depth:0 request to Nextcloud (the standard WebDAV “heartbeat”), then returns a precise error message based on the response status code:

207 Multi-Status → Connection successful
401 / 403 → Authentication failed — check your username and password
404 → WebDAV endpoint not found — check the URL
Other codes → Displays the exact HTTP status code for further investigation

🔧 Deep WebDAV Protocol Integration

NextCloud WP doesn’t simply call Nextcloud’s REST API — it implements a full WebDAV and OCS protocol client. This means it speaks directly to Nextcloud’s core file operation layer, delivering the most native and efficient file operations possible.

📡 Supported WebDAV Operations

Operation	HTTP Method	Endpoint
List folder contents	`PROPFIND Depth:1`	`/remote.php/dav/files/{user}/`
Get file info	`PROPFIND Depth:0`	`/remote.php/dav/files/{user}/{path}`
Create folder	`MKCOL`	`/remote.php/dav/files/{user}/{path}`
Upload file	`PUT`	`/remote.php/dav/files/{user}/{path}`
Download file	`GET`	`/remote.php/dav/files/{user}/{path}`
Delete file/folder	`DELETE`	`/remote.php/dav/files/{user}/{path}`
Move/Rename	`MOVE`	`/remote.php/dav/files/{user}/{path}`
Chunked upload (init)	`MKCOL`	`/remote.php/dav/uploads/{user}/{uuid}/`
Chunked upload (transfer)	`PUT`	`/remote.php/dav/uploads/{user}/{uuid}/{range}`
Chunked upload (assemble)	`MOVE`	`.file → /dav/files/{user}/{dest}`
Get share link	`GET`	`/ocs/v2.php/apps/files_sharing/api/v1/shares`
Create share link	`POST`	`/ocs/v2.php/apps/files_sharing/api/v1/shares`
Test connection	`PROPFIND Depth:0`	`/remote.php/dav/files/{user}/`

🛠️ WordPress HTTP Transport Layer Adaptation

Here’s a technical detail worth noting. WordPress’s WP_Http_Curl transport has a known quirk with non-standard HTTP methods like PROPFIND, MKCOL, and MOVE: its switch/case only covers GET, POST, PUT, and HEAD. For other methods, it sets CURLOPT_CUSTOMREQUEST but fails to set **CURLOPT_POSTFIELDS** — silently discarding the request body.

NextCloud WP patches this elegantly via the http_api_curl filter. Whenever a WebDAV request is made, the plugin dynamically injects a callback that force-sets CURLOPT_POSTFIELDS, then removes the callback immediately after the request completes — ensuring no side effects on other HTTP requests. This approach stays within WordPress’s native HTTP transport architecture while perfectly resolving the WebDAV protocol compatibility issue.

🛡️ Security Design

NextCloud WP employs a multi-layered security strategy:

🔐 Nonce verification — every AJAX request must carry a valid WordPress nonce token, preventing CSRF attacks
👤 Capability checks — all file operations require the manage_options capability (administrator); regular users and guests cannot reach any API endpoint
🔑 Server-side credential isolation — Nextcloud username and password are used exclusively on the PHP server side and are never sent to the client browser
⏱️ HMAC-signed tokens — the public download proxy uses hash_hmac + SHA-256 signed time-limited tokens, expiring after 1 hour by default, keyed with WordPress’s auth_salt
🧹 Input sanitization — all user input is processed through WordPress’s native sanitization functions: sanitize_text_field(), sanitize_file_name(), esc_url_raw(), and more
🔒 SSL verification — all requests sent via wp_remote_request() have SSL certificate verification enabled by default (sslverify => true)
💡 App-Password recommended — the settings page explicitly recommends using Nextcloud’s App-Password instead of the primary account password, reducing credential exposure risk

📐 Design Principles

NextCloud WP’s code architecture adheres to the following core principles:

🎯 Single Responsibility — each class does one thing. The WebDAV client (Nextcloud_Client) handles pure I/O and never touches WordPress side effects (no database writes, no hook registrations). The settings page only registers menus and renders forms. The AJAX router only validates, dispatches, and responds.

🏠 WordPress-Native — configuration is managed through the WordPress Settings API; HTTP requests go through wp_remote_request(); hooks are registered via add_action() / add_filter(); JSON responses are returned with wp_send_json_success/error(). No non-WordPress frameworks or patterns are introduced.

📦 Zero External Dependencies — no Composer packages, no third-party SDKs, no frontend frameworks (vanilla JS). The installation footprint is minimal, and there are zero risks of dependency conflicts with other plugins.

🔧 Namespace Isolation — all PHP classes live under the WPNC\ namespace, mapped to files in the inc/ directory via a simple PSR-4-style autoloader, eliminating class name collisions.

nextcloud-wp/
├── nextcloud-wp.php              # Entry point + autoloader
├── inc/
│   ├── class-nextcloud-client.php     # WebDAV/OCS protocol client (pure I/O)
│   ├── class-nc-settings.php          # WordPress settings page
│   ├── class-nc-ajax.php              # AJAX request router
│   ├── class-nc-sync.php              # WP → NC incremental sync engine
│   ├── class-nc-shortcode.php         # [nextcloud] frontend shortcode
│   └── class-nc-diagnostics.php       # Connection diagnostics panel
├── assets/
│   ├── js/
│   │   ├── admin.js                   # Admin JS
│   │   └── front.js                   # Frontend file browser (vanilla JS)
│   └── css/
│       ├── admin.css                  # Admin styles
│       └── front.css                  # Frontend styles (DM Sans + JetBrains Mono)
└── README.md

📊 Feature Overview

Capability	Status	Description
📂 File Browsing	✅	Real-time directory listing via PROPFIND, breadcrumb navigation
⬆️ Small File Upload	✅	≤ 10 MB direct PUT, drag-and-drop or button upload
⬆️ Large File Chunked Upload	✅	> 10 MB auto-chunked, three-step WebDAV protocol, progress bar
⬇️ Download Proxy	✅	Server-side proxy forwarding, credentials never exposed to client
🔗 Public Share Links	✅	OCS API share link generation/retrieval, auto-copied to clipboard
📁 Folder Creation	✅	Recursive MKCOL, supports nested path creation
🗑️ File/Folder Deletion	✅	Disabled by default, explicitly enabled via shortcode attributes
🔄 Directory Sync (WP → NC)	✅	Incremental, additive-only, smart filtering, size limits
🔌 Shortcode Embedding	✅	`[nextcloud]`, 4 configurable attributes, multi-instance support
🧪 Connection Diagnostics	✅	Three-tier diagnostics + environment info + one-click test
🌓 Dark Mode	✅	Frontend styles support `prefers-color-scheme`
📱 Mobile Responsive	✅	Responsive frontend browser design
🌍 i18n Ready	✅	All user-facing strings internationalized via Text Domain
🔒 Access Control	✅	Nonce + Capability dual verification
📦 External Dependencies	Zero	No Composer, no SDK, no frontend frameworks

🚀 Getting Started

Just a few simple steps to connect your WordPress site to your Nextcloud drive:

📋 Prerequisites

✅ WordPress 5.8 or later
✅ PHP 7.4 or later (with cURL extension enabled)
✅ A running Nextcloud server (with WebDAV access enabled)
✅ A Nextcloud account (creating a dedicated App-Password is recommended)

📥 Three-Step Installation

1️⃣ Upload and activate — in the WordPress admin, go to Plugins → Add New → Upload Plugin, upload nextcloud-wp.zip, and activate it.

2️⃣ Configure the connection — navigate to Settings → NextCloud WP, enter your Nextcloud server URL, username, and password (or App-Password). Click “Test Connection” to confirm everything works.

3️⃣ Start using it — browse your Nextcloud files in the file browser at the bottom of the settings page; embed the [nextcloud] shortcode on any page; configure sync directory pairs and click “Sync Now” to start backing up.

⚠️ Common Issues

All requests returning HTTP 400? — Most likely a Nextcloud trusted domain issue. If your WordPress server accesses Nextcloud via an internal IP, you need to add that IP to the trusted_domains array in Nextcloud’s config.php:

'trusted_domains' => [
    0 => 'cloud.example.com',
    1 => '172.21.0.1:5050',  // Your internal address
],

HTTP 401 / 403? — Authentication failure. Double-check your username and password. It’s strongly recommended to use an App-Password (Nextcloud → Settings → Security → Devices & sessions).

Large file uploads failing? — Check PHP’s upload_max_filesize and post_max_size (these affect individual chunk sizes), as well as max_execution_time (chunked uploads may need a longer execution window).

🔮 What’s Ahead

NextCloud WP is currently a solid v1.0 release. As usage scenarios expand and user feedback comes in, here’s what the roadmap looks like:

📊 Deep Media Library Integration — Map Nextcloud files directly as WordPress Media Library assets, so you can pick images and attachments from Nextcloud right inside the post editor.

🔄 Bidirectional Sync — Current sync is one-way, WP → NC. Future versions could support NC → WP reverse sync, enabling true bidirectional data flow — files modified on Nextcloud automatically pushed back to WordPress.

⏰ Scheduled Auto-Sync — Leverage WordPress’s Cron system for scheduled automatic backups without manual triggers. Set the frequency and your file backups run quietly in the background.

👥 Multi-User Permissions — Integrate with WordPress’s role system so editors, authors, and other roles can access specific Nextcloud folders as needed — not just administrators.

🧱 Gutenberg Block — A native Gutenberg block for embedding the file browser in the WordPress editor in a more modern way, with live preview and a richer configuration panel.

🌐 Remote URL Upload — Upload files directly from a URL to Nextcloud (upload_from_url) without downloading them to the WordPress server first — saving bandwidth and storage.

💡 Why NextCloud WP

When it comes to file management and cloud storage integration, NextCloud WP carves out a distinctive path:

🎯 WordPress-Native Experience — This isn’t some bolted-on, out-of-place third-party panel. It’s a plugin that’s fully at home in the WordPress ecosystem. Settings API, AJAX, Shortcode, Nonce — every interaction follows WordPress conventions. For WordPress developers and admins, there’s zero learning curve.

🏠 Your Data, Your Terms — Nextcloud is synonymous with self-hosted private cloud. NextCloud WP carries that philosophy forward — your files live on your own Nextcloud server, your credentials are stored in your own WordPress database, and all transfers happen within networks you control. No third-party cloud services involved. No data leaving your infrastructure.

📦 Minimalist Architecture — Zero external dependencies means fewer potential conflicts, a smaller attack surface, and simpler maintenance. You’ll never worry about a Composer package version clash breaking your site, or a CDN dependency going offline without warning.

🔧 Native WebDAV Protocol Support — Talks directly to Nextcloud’s WebDAV layer, bypassing any intermediate abstraction. This delivers maximum compatibility and minimum performance overhead — you get the full file operation capabilities that Nextcloud itself provides, not a subset wrapped by some third-party API.

⚡ Install and Go — No elaborate setup wizards, no multi-step onboarding flows. Install the plugin, fill in three fields (URL, username, password), click test — connected. From installation to browsing your first Nextcloud file, the entire process takes under two minutes.

🧑‍💻 Technical Specifications

Plugin Name: NextCloud WP
Current Version: v1.0.0
License: GPL-2.0-or-later
Minimum PHP Version: 7.4
Minimum WordPress Version: 5.8
External Dependencies: None (PHP cURL extension required)
Text Domain: wp-nc-bridge
Namespace: WPNC

💡 NextCloud WP — Your Nextcloud files shouldn’t be locked away in another browser tab. They deserve to live alongside your WordPress content, flowing freely within the same workspace. Say goodbye to the constant context-switching between two dashboards, and bring file management back to where it belongs: simple and efficient. This isn’t a vision for the future — it’s the experience you get the moment you install the plugin.