Google Drive Attachments

Storage

• Seamless replacement — Replaces both data:// and internal-data:// mounts transparently. Full files, thumbnails and retina thumbnails all live on Google Drive, and XenForo's attachment system works unmodified, so inline images, lightbox and download counts are preserved.
• Configurable folder — Store attachments in any Drive folder by entering its ID, or leave it blank to use the Drive root.
• Shared Drive support — Detects whether the configured folder belongs to a Shared Drive (Team Drive) and adjusts every API call accordingly. Personal folders and organizational Shared Drives both work.
• Local cache mode (optional) — Uploads are written to local disk and returned instantly, then a cron job every three hours moves them to Drive and deletes the local copy. Reads try local first and fall back to Drive automatically, so nothing breaks during the handover, and deletes, renames and copies stay consistent across both stores.
• Selective sync — Restrict Drive to specific file extensions, one per line. Everything else stays local. Applies to both background sync and migration.

Connection

• OAuth 2.0 — A proper authorization flow, with tokens stored in the database and refreshed automatically so the connection stays live without re-authentication. The callback is CSRF-protected by state parameter validation.
• Dashboard and test — A dedicated admin page shows the connected account, token status and configured folder, and lets you authorize, test or disconnect without leaving the panel. The one-click test confirms API access and reports the folder name before you enable the add-on.
• Concurrency-safe tokens — Tokens refresh with five minutes to spare, are re-read from the database so a refresh by another worker is adopted rather than duplicated, and any unauthenticated request is retried once after a refresh.

Uploads & Performance

• Chunked uploads — Files over 5 MB use Google's resumable protocol in 5 MB chunks, so large attachments cannot exhaust memory. Smaller files use a single request for speed.
• Path caching — An in-memory path-to-fileId cache removes redundant API calls within a request, and folder structures are created incrementally and cached.
• Graceful fallback — If Drive is unreachable, credentials are missing or the add-on is disabled, XenForo falls back to local storage. A Google API problem never takes the forum down, and disabling the add-on never breaks existing uploads.

Migration

• Bi-directional — Move existing attachments from local storage to Google Drive, or back again, from the admin panel or the command line. Every file is covered: full files, thumbnails and retina thumbnails. Progress is visible in XenForo's job manager.
• Concurrent — Files go out in parallel waves, ten at a time by default. Files over 5 MB still use sequential chunked upload, so memory stays bounded.
• Resumable — Progress is recorded per attachment, so an interrupted migration resumes where it stopped and a re-run skips completed work with a database join rather than a Google API call.
• Pre-warmed folders — The whole attachment folder structure is mapped up front in a handful of list calls, instead of a lookup per file.

Clear counters

Migrated / Skipped / Failed, with skips broken down so a deliberate skip reads differently from a problem:

Migrated: 4,812 / Skipped: 340 [ext:301, no-file:38, no-entity:1] / Failed: 0

• ext — filtered out by the extension setting
• no-file — no local file present to transfer
• no-entity — the attachment record no longer exists

Command Line

$ php cmd.php xf-rebuild:dcGda-migrateToGoogleDrive
$ php cmd.php xf-rebuild:dcGda-migrateToLocal

The migration command shows a live progress bar with running counters, elapsed time and an ETA, and accepts:

Compatibility

XenForo 2.2.0 and later. The migration layer detects the attachment schema at runtime, so a single build serves both 2.2 and 2.3.

Step 1: Install the Add-on

Install the add-on via Admin CP > Add-ons > Install/upgrade from archive or run:

php cmd.php xf-addon:install DC/GDA

Step 2: Create a Google Cloud Project

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Navigate to APIs & Services > Library.
4. Search for Google Drive API and click Enable.

Step 3: Configure the OAuth Consent Screen

1. Go to APIs & Services > OAuth consent screen.
2. Select External user type (or Internal if using Google Workspace).
3. Fill in the required fields: app name, user support email, and developer contact email.
4. Add the scope: https://www.googleapis.com/auth/drive (Google Drive full access).
5. Save and continue through the remaining steps.

Step 4: Create OAuth 2.0 Credentials

1. Go to APIs & Services > Credentials.
2. Click Create Credentials > OAuth client ID.
3. Select Web application as the application type.
4. Under Authorized redirect URIs, add:

   https://yourforum.com/admin.php?dc-gda/callback
   

   Replace yourforum.com with your actual forum domain.

5. Click Create and note the Client ID and Client Secret.

Step 5: Configure the Add-on

1. In XenForo Admin CP, go to Setup > Options > Google Drive Attachments.
2. Enter your Client ID and Client Secret.
3. Optionally, enter a Google Drive Folder ID to store attachments in a specific folder.
4. Save the options.

Step 6: Authorize the Connection

1. Go to Google Drive Attachments in the admin sidebar (or navigate to admin.php?dc-gda/).
2. Click Authorize with Google.
3. Sign in with the Google account that owns the target Drive folder.
4. Grant the requested permissions.
5. You will be redirected back to the dashboard showing a successful connection.

Step 7: Enable and Migrate

1. Return to Setup > Options > Google Drive Attachments.
2. Set Enable Google Drive storage to On.
3. All new attachments will now be stored on Google Drive.

To migrate existing attachments, go to the dashboard and click Migrate to Google Drive, or run:

php cmd.php xf-rebuild:dcGda-migrateToGoogleDrive

For forums with a large back-catalogue, run the migration from the command line where you can tune it:

$ php cmd.php xf-rebuild:dcGda-migrateToGoogleDrive -c 20 --batch 500

The migration is resumable — stopping and re-running continues from where it left off — and once you have verified the result, reclaim the disk with:

$ php cmd.php xf-rebuild:dcGda-migrateToGoogleDrive --cleanup-local

Step 8 (optional): Enable Local Cache Mode

1. Go to Setup > Options > Google Drive Attachments.
2. Set Enable local temporary cache to On.
3. Confirm the Sync local cached files to Google Drive cron entry is enabled under Setup > Cron entries. It runs every three hours.

New uploads now land on local disk instantly and move to Drive on the next cron run, which deletes the local copy once the upload succeeds. Leave this off if you want uploads to go straight to Drive.

Step 9 (optional): Restrict What Goes to Drive

1. Go to Setup > Options > Google Drive Attachments.
2. In File extensions to sync to Google Drive, enter one extension per line:

zip
rar
7z
pdf
mp4

Only attachments matching those extensions are sent to Drive; everything else stays local. Leave the field empty to send everything.