PHPackages splashfrog/leap\_file\_manager - 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. [File & Storage](/categories/file-storage) 4. / 5. splashfrog/leap\_file\_manager ActiveDrupal-module[File & Storage](/categories/file-storage) splashfrog/leap\_file\_manager ============================== Enterprise media file replacement, safe staging, and SEO-preservation for Drupal. 1.0.1(1mo ago)03↓100%GPL-2.0-or-laterPHPPHP >=8.3 Since Apr 30Pushed 1mo agoCompare [ Source](https://github.com/SplashFrog/leap-drupal-file-manager)[ Packagist](https://packagist.org/packages/splashfrog/leap_file_manager)[ RSS](/packages/splashfrog-leap-file-manager/feed)WikiDiscussions main Synced 1w ago READMEChangelog (2)Dependencies (1)Versions (4)Used By (0) Splash Frog - LEAP File Manager =============================== [](#splash-frog---leap-file-manager) **Enterprise-grade media file replacement, safe staging, and SEO-preservation for Drupal 11.** The LEAP File Manager solves the "Versioned Filename" problem in Drupal Core. By default, when you replace a file in Drupal, it creates a new file record (e.g., `image_0.jpg`), which destroys SEO backlinks and results in stale assets on the disk. This module provides a robust orchestrator that performs **physical file overwrites**, allowing you to update media content while maintaining 100% identical URLs for SEO longevity. --- ✨ Key Features -------------- [](#-key-features) - **SEO Preservation:** Physically overwrites existing files to maintain identical URLs. - **Safe Staging:** Replacement files are stored in a secure, non-public directory until the Media entity is officially *Published*. - **"Chameleon" UI:** Injects a custom replacement upload container directly into standard Media forms. - **Surgical Lockdown:** Prevents editors from accidentally deleting "Live" files via the standard Drupal widget. - **Dual-Engine Transfer:** Hot-swaps between `DrupalNativeTransfer` (for private stream wrappers) and `ManualTransfer` (native PHP logic for Docker/DDEV/Restricted environments). - **Auto Cache-Busting:** Appends a persistent `?v=[mtime]` timestamp to images and document links to force browser/CDN refreshes without a hard refresh. - **Ghost File Protection:** A 3-layer defense system that prevents physical file deletion if the replacement file is missing from the server. - **Metadata Merging:** Automatically flushes stale image dimensions and focal point data during replacement to ensure native thumbnail regeneration. --- 🛠️ Requirements --------------- [](#️-requirements) - **Drupal:** ^11.3 - **PHP:** >=8.3 - **Modules:** `media`, `file`, `content_moderation` (optional but recommended). --- 🚀 Installation & Setup -------------------------- [](#-installation--setup) 1. **Enable the Module:**``` ddev drush en leap_file_manager ``` 2. **Apply the Fields Recipe:**The module uses a "Double-Key" opt-in system. It will not touch any media type unless it has the internal tracker field attached. Run the provided recipe to attach these fields to your bundles: ``` ddev drush recipe modules/custom/leap_file_manager/recipes/leap_file_manager ``` 3. **Configure Storage:**Go to `/admin/config/media/leap-file-manager` to choose whether to use the `private://` stream wrapper or a custom public fallback directory for staged drafts. --- 🏗️ Architecture & Logic --------------------------- [](#️-architecture--logic) ### 1. The "Double-Key" Opt-in (`isManaged`) [](#1-the-double-key-opt-in-ismanaged) The module is designed to be non-intrusive. It evaluates every media entity via the `isManaged()` method: - **Key 1:** Does the Media bundle have the `field_leap_staged_file` tracker? - **Key 2:** Does the Media bundle have a valid physical file source field (e.g., Image or File)? If both keys aren't present, the module bails out, allowing standard Drupal behavior to take over. ### 2. Field Definitions [](#2-field-definitions) Field Machine NameRoleRequirement`field_leap_staged_file`**The Tracker.** Stores the FID of the replacement file while it's in Draft mode.**Required for Opt-in**`field_leap_keep_original`**SEO Toggle.** If checked (default), the module forces the new file to take the old one's name.Optional`field_leap_rename_file`**Rename Field.** Allows the editor to physically rename the file on disk.Optional### 3. The "Chameleon" Form UI [](#3-the-chameleon-form-ui) When editing a managed Media entity, the `MediaFormHandler` performs a "Surgical Lockdown": - The **Remove** button on the original file widget is hidden. - The **Alt/Title** fields are made non-required at the widget level to allow saves during replacement. - A **"Replace File"** details container is injected at the bottom of the source field. ### 4. The 3-Layer Ghost File Defense [](#4-the-3-layer-ghost-file-defense) To prevent accidental data loss (deleting the old file when the new one is missing), the module implements: 1. **The Shield:** Form validation blocks the "Publish" action if the staged file is missing from the disk. 2. **The Safety Net:** The orchestrator reorders operations to move the new file *before* deleting the old one. 3. **The Broom:** If a move fails, the orchestrator detaches the broken FID from the entity to prevent a loop of errors. --- 👨‍💻 Developer Information ------------------------- [](#‍-developer-information) ### Custom Strategies [](#custom-strategies) The module uses the **Strategy Pattern** to handle different media types. - `ImageStrategy`: Handles dimension clearing (`width`/`height`) and Image Style flushing. - `FileStrategy`: Handles generic thumbnails and icons for PDFs/Documents. ### Transfer Engines [](#transfer-engines) - `DrupalNativeTransfer`: Uses `FileRepository::move`. Best for sites with a properly configured `private://` system and standard directory permissions. - `ManualTransfer`: Uses native PHP `rename()` and direct SQL updates. This is the "Sledgehammer" engine designed to bypass brittle stream wrapper permission issues in heavily restricted or deeply nested public-folder environments. ### Cache Busting [](#cache-busting) The module implements `hook_preprocess_image` and `hook_preprocess_file_link`. It calculates the physical `filemtime` of the source file and appends it as a query string (`?v=12345`). This ensures that as soon as a file is replaced, every visitor to the site sees the updated version immediately. --- 🛡️ License ---------- [](#️-license) This module is part of the Splash Frog Ecosystem, the Drupal Ecosystem, and is provided under the GPL-2.0-or-later License. ### Health Score 40 — FairBetter than 86% of packages Maintenance92 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~0 days Total 3 Last Release 39d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/226536283?v=4)[Splash Frog](/maintainers/SplashFrog)[@SplashFrog](https://github.com/SplashFrog) --- Top Contributors [![SplashFrog](https://avatars.githubusercontent.com/u/226536283?v=4)](https://github.com/SplashFrog "SplashFrog (4 commits)") ### Embed Badge ![Health badge](/badges/splashfrog-leap-file-manager/health.svg) ``` [![Health](https://phpackages.com/badges/splashfrog-leap-file-manager/health.svg)](https://phpackages.com/packages/splashfrog-leap-file-manager) ``` ### Alternatives [drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6941.5M395](/packages/drupal-core-recommended) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)